dpkg-source(1) dpkg utilities dpkg-source(1)
NAME
dpkg-source, dpkg-gencontrol, dpkg-shlibdeps, dpkg-genchanges,
dpkg-buildpackage, dpkg-distaddfile, dpkg-parsechangelog - Debian
source package tools
SYNOPSIS
dpkg-source -x filename.dsc [output-directory]
dpkg-source -b [options] directory [orig-directory|orig-targz|]
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 pack
age 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:dependency
field where dependencyfield is a dependency field name. Any other vari
ables 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.
The format for a shared library dependency information entry in these
files is (see the Debian Policy Manual for details):
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 auto
mate 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 sep
arate argument.
COMMON OPTIONS
Many of these programs share options; these are described here,
together with the programs that accept them.
-h,--help
Display the particular programs usage message, including a syn
opsis of the options it understands. This option is understood
by all the source package tools.
--version
Display the particular programs version, including copyright
and license information. 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 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 changesde
scription rather than using the information from the source
trees changelog file. This is understood by dpkg-buildpackage
and dpkg-genchanges.
-mmaintaineraddress
Use maintaineraddress as the name and email address of the main
tainer for this package, rather than using the information from
the source trees control file. This is understood by
dpkg-buildpackage and dpkg-genchanges.
-emaintaineraddress
Use maintaineraddress as the name and email address of the main
tainer for this upload, rather than using the information from
the source trees changelog. This is understood by dpkg-build
package and dpkg-genchanges.
-si, -sa, -sd
These options control whether the original source archive is
included in the upload generated by dpkg-buildpackage or
dpkg-genchanges if any source is being generated (i.e., -b or -B
havent been used).
By default, or if -si is specified, the original source will be
included if the version number ends in -0 or -1, i.e. 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 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-gen
changes 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-gencon
trol, 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 or
failing that defaults to the debian standard format. 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 trees top level direc
tory.
-x Extract a source package. One non-option argument must be sup
plied, the name of the Debian source control file (.dsc). An
optional second non-option argument may be supplied to specify
the directory to extract the source package to, this must not
exist. If no output directory is specified, the source package
is extracted into a directory named source-version- under the
current working directory.
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 direc
tory 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 direc
tory containing the unpacked source tree. If a second argument
is supplied it should be the name of the original source direc
tory 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 orig
inal source directory directory.orig or the empty string (no
original source, and so no diff) depending on the arguments.
-i[]
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 control files and
directories of the most common revision control systems, backup
and swap files and Libtool build output directories.
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 dont have access permis
sions for committing 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 unneces
sarily included in every .diff.gz, unless you use the -i switch.
-I
If this option is specified, the filename will be passed to
tars --exclude option when it is called to generate a
.orig.tar.gz or .tar.gz file. For example, -ICVS will make tar
skip over CVS directories when generating a .tar.gz file. The
option may be repeated multiple times to list multiple filenames
to exclude.
-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-ver
sion.orig.tar.gz. It will leave this original source in place
as a tarfile, or copy it to the current directory if it isnt
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-spe
cific 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 origi
nal 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 equiva
lent 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 speci
fied. -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.
All the -sX options are mutually exclusive. If you specify more than
one only the last one will be used.
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 packages 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
These options are ignored for compatibility with older versions
of dpkg-dev but are now deprecated. Previously they were used to
tell dpkg-gencontrol to include the Section and Priority fields
in the control file. This is now the default behaviour. If you
want to get the old behaviour you can use the -U option to
delete the fields from the control file.
-Ppackagebuilddir
Tells dpkg-source that the package is being built in package
builddir 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 packagebuild
dir/DEBIAN/control if -P was used).
dpkg-SHLIBDEPS OPTIONS
dpkg-shlibdeps interprets non-option arguments as executable names,
just as if theyd 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 dependen
cies.
-pvarnameprefix
Causes substitution variables to start with varnameprefix:
instead of shlibs:. Likewise, any existing substitution vari
ables starting with varnameprefix: (rather than shlibs:) are
removed from the the substitution variables file.
-Llocalshlibsfile
Causes dpkg-shlibdeps to read overriding shared library depen
dency information from localshlibsfile instead of
debian/shlibs.local.
-O Causes the substitution variable settings to be printed to stan
dard output, rather than being added to the substitution vari
ables file (debian/substvars by default).
-ttype Causes dpkg-shlibdeps to prefer shared library dependency infor
mation tagged for the given package type. If no tagged informa
tion is available, falls back to untagged information. The
default package type is "deb". Shared library dependency infor
mation is tagged for a given type by prefixing it with the name
of the type, a colon, and whitespace.
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 packages
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 pro
cess 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 typi
cally be fakeroot, 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 users 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, respec
tively.
-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[]
Passed unchanged to dpkg-source.
-I
Passed unchanged to dpkg-source. May be repeated multiple
times.
-D Check build dependencies and conflicts; abort if unsatisfied.
-d Do not check build dependencies and conflicts.
-nc Do not clean the source tree(implies -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-dis
taddfile 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 alphanu
meric. 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 occurrence 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 spec
ified 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.
source:Upstream-Version
The upstream source package version, including the Debian ver
sion epoch if any.
binary:Version
The binary package version (which may differ from source:Version
in a binNMU for example).
Source-Version
The source package version (from the changelog file). This vari
able is now deprecated as its meaning is different from its
function, please use the source:Version or binary:Version as
appropriate.
Installed-Size
The total size of the packages installed files. This value is
copied into the corresponding control file field; setting it
will modify the value of that field. If this variable isnt 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 con
trol 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 con
tents 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.
dpkg:Upstream-Version
The upstream version of dpkg.
dpkg:Version
The full version of dpkg.
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-inde
pendent 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.
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 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.
SEE ALSO
dpkg-deb(1), dpkg(1), dselect(1), gpg(1), pgp(1).
AUTHOR
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.
Debian Project 2006-05-23 dpkg-source(1)
|
