DPKG-SOURCE(E) dpkg utilities DPKG-SOURCE(E) NAME dpkg-source, dpkg-gencontrol, dpkg-shlibdeps, dpkg-gen- changes, dpkg-buildpackage, dpkg-distaddfile, dpkg-par- sechangelog - Debian source package tools SYNOPSIS dpkg-source -x filename.dsc dpkg-source -b [options] directory [orig-directory|''] dpkg-gencontrol [options] dpkg-shlibdeps options dpkg-genchanges [options] dpkg-buildpackage [options] dpkg-distaddfile [options] filename section priority dpkg-parsechangelog [options] DESCRIPTION dpkg-source packs and unpacks Debian source archives. dpkg-gencontrol reads information from an unpacked Debian source tree and generates a binary package control file (which defaults to debian/tmp/DEBIAN/control); it also adds an entry for the binary package to debian/files. dpkg-shlibdeps calculates shared library dependencies for executables named in its arguments. The dependencies are added to the substitution variables file debian/substvars as variable names shlibs:dependencyfield where dependency- field is a dependency field name. Any other variables starting shlibs: are removed from the file. dpkg-shlib- deps will read shared library dependency information from debian/shlibs.local, /etc/dpkg/shlibs.override, the shlibs control area file of the package containing the file which objdump reports as satisfying the library dependency, or /etc/dpkg/shlibs.default. The first match will be used. See the Debian packaging manual for details of the format of shared library dependency files. dpkg-genchanges reads information from an unpacked and built Debian source tree and from the files it has gener- ated and generates a Debian upload control file (.changes file). dpkg-buildpackage is a control script which can be used to help automate the building of a package. dpkg-distaddfile adds an entry for a named file to debian/files. dpkg-parsechangelog reads and parses the changelog of an unpacked Debian source tree and outputs the information in it to standard output in a machine-readable form. None of these commands allow multiple options to be com- bined into one, and they do not allow the value for an option to be specified in a separate argument. COMMON OPTIONS Many of these programs share options; these are described here, together with the programs that accept them. -h Display the particular program's version and usage message, including a synopsis of the options it understands. This option is understood by all the source package tools. -vversion In dpkg-buildpackage, dpkg-genchanges and dpkg-par- sechangelog this causes changelog information from all versions strictly later than version (which must appear in the changelog file) to be used. In dpkg-gencontrol it sets the version number of the binary package which will be generated. -Cchangesdescription Read the description of the changes from the file changesdescription rather than using the informa- tion from the source tree's changelog file. This is understood by dpkg-buildpackage and dpkg-gen- changes. -mmaintaineraddress Use maintaineraddress as the name and email address of the maintainer for this package, rather than using the information from the source tree's con- trol. This is understood by dpkg-buildpackage and dpkg-genchanges. -emaintaineraddress Use maintaineraddress as the name and email address of the maintainer for this upload, rather than using the information from the source tree's changelog. This is understood by dpkg-buildpackage and dpkg-genchanges. -si, -sa, -sd These options control whether the original source archive is included in the upload generated by dpkg-buildpackage and dpkg-genchanges if any source is being generated (ie, -b or -B haven't been used). By default, or if -si is specified, the original source will be included if the version number ends in -0 or -1, ie if the Debian revision part of the version number is 0 or 1. -sa forces the inclusion of the original source; -sd forces its exclusion and includes only the diff. -Vname=value Set an output substitution variable. This option is understood by dpkg-source, dpkg-gencontrol and dpkg-genchanges. See below for a discussion of output substitution. -Tsubstvarsfile Read (or, for dpkg-shlibdeps, write) substitution variables in substvarsfile; the default is debian/substvars. This option is understood by dpkg-source, dpkg-gencontrol, dpkg-shlibdeps and dpkg-genchanges. -Dfield=value Override or add an output control file field. This option is understood by dpkg-source, dpkg-gencon- trol and dpkg-genchanges. -Ufield Remove an output control file field. This option is understood by dpkg-source, dpkg-gencontrol and dpkg-genchanges. -b|-B|-S For dpkg-genchanges and dpkg-buildpackage -b and -B specify that a binary-only build is taking place. -b indicates that no source files are to be built and/or distributed, and -B that no architecture- independent binary package files are to be dis- tributed either. -S specifies that only the source should be uploaded and no binary packages need to be made. The distinction between -b and -B is only used by dpkg-buildpackage; dpkg-genchanges just produces a .changes file for whatever files were produced by the binary-* target(t) of the package being built. -b tells dpkg-source to build a source package (rather than to extract one) - see below. -ccontrolfile Specifies the main source control file to read information from. The default is debian/control. This option is understood by dpkg-source, dpkg-gen- control and dpkg-genchanges. -lchangelogfile Specifies the change log file to read information from. The default is debian/changelog. This option is understood by dpkg-source, dpkg-gencon- trol and dpkg-genchanges. -ffileslistfile Read or write the list of files to be uploaded here, rather than using debian/files. This option is understood by dpkg-gencontrol, dpkg-genchanges and dpkg-distaddfile. -Fchangelogformat Specifies the format of the changelog. By default the format is read from a special line near the bottom of the changelog (see the Debian packaging manual) or failing that defaults to debian, the standard format described in the Debian packaging manual. This option is understood by dpkg-source, dpkg-gencontrol and dpkg-genchanges. -W This option turns certain errors into warnings. Only dpkg-source uses this, but dpkg-buildpackage recognizes it, and passes it thru to dpkg-source. -E This option negates a previously set -W. It is currently only understood by dpkg-buildpackage and dpkg-source. DPKG-SOURCE OPTIONS When the common options -c and -l are given with relative pathnames these are interpreted starting at the source tree's top level directory. -x Extract a source package. One non-option argument should be supplied, the name of the Debian source control file (.dsc). No options are useful with dpkg-source -x. dpkg-source will read the names of the other file(e) making up the source package from the control file; they are assumed to be in the same directory as the .dsc. The files in the extracted package will have their permissions and ownerships set to those which would have been expected if the files and directories had simply been created - directories and executable files will be 0777 and plain files will be 0666, both modified by the extractors' umask; if the par- ent directory is setgid then the extracted directo- ries will be too, and all the files and directories will inherit its group ownership. -b Build: pack up a source tree. One or two non- option arguments should be supplied. The first is taken as the name of the directory containing the unpacked source tree. If a second argument is sup- plied it should be the name of the original source directory or tarfile or the empty string if the package is a Debian-specific one and so has no Debianisation diffs. If no second argument is sup- plied then dpkg-source will look for the original source tarfile package_upstream-version.orig.tar.gz or the original source directory directory.orig or the empty string (no original source, and so no diff) depending on the arguments. -i[<regexp>] You may specify a perl regular expression to match files you want filtered out of the list of files for the diff. (This list is generated by a find command.) -i by itself enables the option, with a default that will filter out CVS, RCS and libtool .deps subdirectories, and all files within them, as well as ~ suffixed backup files and DEADJOEs. This is very helpful in cutting out extraneous files that get included in the .diff.gz, (eg: "debian/BUGS_TODO/*" or "debian/RCS/*,v"). For instance, if you maintain a package that you track via remote CVS, where you don't have access permis- sions for commiting the debian control files and making tags for cvs-buildpackage(e), it is neces- sary to perform an extra checkout/update into a directory you keep pristine, to generate the .orig.tar.gz from. That directory will have CVS/Entries files in it that will contain times- tamps that differ from the ones in your working directory, thus causing them to be unnecessarily included in every .diff.gz, unless you use the -i switch. -sa,-sp,-su,-sk,-sA,-sP,-sU,-sK,-ss with -b If -sk or -sp is specified dpkg-source expects the original source as a tarfile, by default pack- age_upstream-version.orig.tar.gz. It will leave this original source in place as a tarfile, or copy it to the current directory if it isn't already there If -sp is used rather than -sk it will remove it again afterwards. If -su or -sr is specified the original source is expected as a directory, by default package- upstream-version.orig and dpkg-source will create a new original source archive from it. If -sr is used dpkg-source will remove that directory after it has been used. If -ss is specified dpkg-source will expect that the original source is available both as a direc- tory and as a tarfile. If will use the directory to create the diff, but the tarfile to create the .dsc. This option must be used with care - if the directory and tarfile do not match a bad source archive will be generated. If -sn is specified dpkg-source will not look for any original source, and will not generate a diff. The second argument, if supplied, must be the empty string. This is used for Debian-specific packages which do not have a separate upstream source and therefore have no debianisation diffs. If -sa or -sA is specified dpkg-source will look for the original source archive as a tarfile or as a directory - the second argument, if any, may be either, or the empty string (this is equivalent to using -sn). If a tarfile is found it will unpack it to create the diff and remove it afterwards (this is equivalent to -sp); if a directory is found it will pack it to create the original source and remove it afterwards (this is equivalent to -sr); if neither is found it will assume that the package has no debianisation diffs, only a straightforward source archive (this is equivalent to -sn). If both are found then dpkg-source will ignore the directory, overwriting it, if -sA was specified (this is equivalent to -sP) or raise an error if -sa was specified. -sA is the default. -sa, -sp, -sk, -su and -sr will not overwrite existing tarfiles or directories. If this is desired then -sA, -sP, -sK, -su and -sR should be used instead. -sp,-su,-sn with -x In all cases any existing original source tree will be removed. If -sp is used when extracting then the original source (if any) will be left as a tarfile. If it is not already located in the current directory or if an existing but different file is there it will be copied there. This is the default. -su unpacks the original source tree. -sn ensures that the original source is neither copied to the current directory nor unpacked. Any original source tree that was in the current direc- tory is still removed. DPKG-GENCONTROL OPTIONS dpkg-gencontrol does not take any non-option arguments. -ppackage Generate information for the binary package pack- age. If the source control file lists only one binary package then this option may be omitted; otherwise it is essential to select which binary package's information to generate. -nfilename Assume the filename of the package will be filename instead of the normal package_version_arch.deb filename. -is, -ip, -isp Include the Section and Priority fields for this package from the main source control file in the binary package control file being generated. Usu- ally this information is not included here, but only in the .changes file. -isp includes both fields, -is only the Section and -ip only the Pri- ority. -Ppackagebuilddir Tells dpkg-source that the package is being built in packagebuilddir instead of debian/tmp. This value is used to find the default value of the Installed-Size substitution variable and control file field (using du), and for the default location of the output file. -O Causes the control file to be printed to standard output, rather than to debian/tmp/DEBIAN/control (or packagebuilddir/DEBIAN/control if -P was used). DPKG-SHLIBDEPS OPTIONS dpkg-shlibdeps interprets non-option arguments as exe- cutable names, just as if they'd been supplied as -eexe- cutable. -eexecutable Include dependencies appropriate for the shared libraries required by executable. -ddependencyfield Add dependencies to be added to the control file dependency field dependencyfield. (The dependen- cies for this field are placed in the variable shlibs:dependencyfield.) The -ddependencyfield option takes effect for all executables after the option, until the next -dde- pendencyfield. The default dependencyfield is Depends. If the same dependency entry (or set of alterna- tives) appears in more than one of the recognised dependency field names Pre-Depends, Depends, Recom- mends, Enhances or Suggests then dpkg-shlibdeps will automatically remove the dependency from all fields except the one representing the most impor- tant dependencies. -pvarnameprefix Causes substitution variables to start with var- nameprefix: instead of shlib:. Likewise, any existing substitution variables starting with var- nameprefix: (rather than shlib:) are removed from the the substitution variables file. -Llocalshlibsfile Causes dpkg-shlibs to read overriding shared library dependency information from localshlibsfile instead of debian/shlibs.local. -O Causes the substitution variable settings to be printed to standard output, rather than being added to the substitution variables file (debian/subst- vars by default). DPKG-GENCHANGES OPTIONS dpkg-genchanges does not take any non-option arguments. -uuploadfilesdir Look for the files to be uploaded in uploadfilesdir rather than .. (dpkg-genchanges needs to find these files so that it can include their sizes and checksums in the .changes file). -q Usually dpkg-genchanges will produce informative messages on standard error, for example about how many of the package's source files are being uploaded. -q suppresses these messages. DPKG-BUILDPACKAGE OPTIONS dpkg-buildpackage does not take any non-option arguments. -kkey-id Specify a key-ID to use when signing packages. -rgain-root-command When dpkg-buildpackage needs to execute part of the build process as root, it prefixes the command it executes with gain-root-command if one has been specified. gain-root-command should be the name of a program on the PATH and will get as arguments the name of the real command to run and the arguments it should take. gain-root-command should not con- tain spaces or any other shell metacharacters. gain-root-command might typically be sudo, super or really. su is not suitable, since it requires a -c option to run a command and even then it can only invoke the user's shell with -c instead of passing arguments individually to the command to be run. -psign-command When dpkg-buildpackage needs to execute GPG or PGP to sign a source control (.dsc) file or a .changes file it will run sign-command (searching the PATH if necessary) instead of pgp. sign-command will get all the arguments that pgp would have gotten. If sign-command takes its arguments in GPG rather than PGP style, you should give the -sgpg option. sign-command should not contain spaces or any other shell metacharacters. -tc Clean the source tree (using gain-root-command debian/rules clean) after the package has been built. -us, -uc Do not sign the source package or the .changes file, respectively. -aarchitecture Specify the Debian architecture we build for. The architecture of the machine we build on is deter- mined automatically, and is also the default for the host machine. -i[<regexp>] Passed unchanged to dpkg-source. -D Check build dependencies and conflicts; abort if unsatisfied. -d Do not check build dependencies and conflicts. -nc Do not clean the source tree(imlies -b). DPKG-DISTADDFILE ARGUMENTS dpkg-distaddfile does not take any non-common options. It takes three non-option arguments, the filename and the section and priority for the .changes file. The filename should be specified relative to the directory where dpkg-genchanges will expect to find the files, usu- ally .., rather than being a pathname relative to the cur- rent directory when dpkg-distaddfile is run. DPKG-PARSECHANGELOG ARGUMENTS dpkg-parsechangelog does not take any non-common options or non-option arguments. VARIABLE SUBSTITUTION Before dpkg-source, dpkg-gencontrol and dpkg-genchanges write their control information (to the source control file .dsc for dpkg-source and to standard output for dpkg- gencontrol and dpkg-genchanges) they perform some variable substitutions on the output file. A variable substitution has the form ${variable-name}. Variable names consist of alphanumerics, hyphens and colons and start with an alphanumeric. Variable substitu- tions are performed repeatedly until none are left; the full text of the field after the substitution is rescanned to look for more substitutions. After all the substitutions have been done each occurence of the string ${} (which is not a legal substitution) is replaced with a $ sign. Variables can be set using the -V common option. They can be also specified in the file debian/substvars (or what- ever other file is specified using the -T option). This file consists of lines of the form name=value. Trailing whitespace on each line, blank lines, and lines starting with a # symbol (comments) are ignored. Additionally, the following standard variables are avail- able: Arch The current build architecture (from dpkg --print- architecture). Source-Version The source package version (from the changelog file). Installed-Size The total size of the package's installed files. This value is copied into the corresponding control file field; setting it will modify the value of that field. If this variable isn't set dpkg-gen- control will use du -k debian/tmp to find the default value. Extra-Size Additional disk space used when the package is installed. If this variable is set its value is added to that of the Installed-Size variable (whether set explicitly or using the default value) before it is copied into the Installed-Size control file field. F:fieldname The value of the output field fieldname (which must be given in the canonical capitalisation). Setting these variables has no effect other than on places where they are expanded explicitly. Format The .changes file format version generated by this version of the source packaging scripts. If you set this variable the contents of the Format field in the .changes file will change too. Newline, Space, Tab These variables each hold the corresponding charac- ter. shlibs:dependencyfield Variable settings with names of this form are gen- erated by dpkg-shlibdeps - see above. If a variable is referred to but not defined it generates a warning and an empty value is assumed. FILES debian/control The main source control information file, giving version-independent information about the source package and the binary packages it can produce. debian/changelog The changelog file, used to obtain version-depen- dent information about the source package, such as the urgency and distribution of an upload, the changes made since a particular release, and the source version number itself. debian/files The list of generated files which are part of the upload being prepared. dpkg-gencontrol adds the presumed filenames of binary packages whose control files it generates here; dpkg-distaddfile can be used to add additional files. dpkg-genchanges reads the data here when producing a .changes file. debian/substvars List of substitution variables and values. debian/shlibs.local Package-local overriding shared library dependency information. /etc/dpkg/shlibs.override Per-system overriding shared library dependency information. /etc/dpkg/shlibs.default Per-system default shared library dependency information. BUGS The point at which field overriding occurs compared to certain standard output field settings is rather confused. The binary package entries in the debian/files file will be passed through variable substitution twice. This should not matter, since $, { and } are not legal in pack- age names or version numbers. It should be possible to specify spaces and shell metacharacters in and initial arguments for gain-root-com- mand and sign-command. SEE ALSO Debian packaging manual, Debian policy manual, dpkg-deb(b), dpkg(g), dselect(t), gpg(g), pgp(p). AUTHOR The utilities and this manpage were written by Ian Jack- son. COPYRIGHT Copyright (C) 1995-1996 Ian Jackson Copyright (C) 2000 Wichert Akkerman This is free software; see the GNU General Public Licence version 2 or later for copying conditions. There is NO WARRANTY. See /usr/share/doc/dpkg/copyright and /usr/share/common-licenses/GPL for details. Debian Project Januari 2000 DPKG-SOURCE(E)