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
dependencyfield
is a dependency field name. Any other variables starting
shlibs:
are removed from the file.
dpkg-shlibdeps
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 generated 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 combined 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-parsechangelog
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 information from the source tree's changelog
file. This is understood by
dpkg-buildpackage and dpkg-genchanges.
-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 control.
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-gencontrol 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
distributed 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(s) 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-gencontrol 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-gencontrol 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(s) 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 parent directory is setgid then the
extracted directories 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 supplied
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 supplied 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 permissions for commiting the debian
control files and making tags for cvs-buildpackage(1), it is
necessary 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 timestamps 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
package_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 directory
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 directory is still removed.
DPKG-GENCONTROL OPTIONS
dpkg-gencontrol
does not take any non-option arguments.
-ppackage
Generate information for the binary package
package.
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. Usually this information
is not included here, but only in the
.changes
file.
-isp
includes both fields,
-is only the Section and -ip only the Priority.
-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 executable names, just as if they'd
been supplied as
-eexecutable.
-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 dependencies for this field are placed in the variable
shlibs:dependencyfield.)
The
-ddependencyfield
option takes effect for all executables after the option, until the
next
-ddependencyfield.
The default
dependencyfield
is
Depends.
If the same dependency entry (or set of alternatives) appears in more
than one of the recognised dependency field names
Pre-Depends, Depends, Recommends, Enhances or Suggests
then
dpkg-shlibdeps
will automatically remove the dependency from all fields except the
one representing the most important dependencies.
-pvarnameprefix
Causes substitution variables to start with
varnameprefix:
instead of
shlib:.
Likewise, any existing substitution variables starting with
varnameprefix:
(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/substvars
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 contain 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-commanddebian/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 determined 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, usually
..,
rather than being a pathname relative to the current 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 substitutions 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 whatever 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 available:
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-gencontrol
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 character.
shlibs:dependencyfield
Variable settings with names of this form are generated 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-dependent 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.
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 package names or version numbers.
It should be possible to specify spaces and shell metacharacters in
and initial arguments for
gain-root-command and sign-command.
The utilities and this manpage were written by Ian Jackson.
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.