The Debian binary packages in the distribution are generated from Debian sources, which are in a special format to assist the easy and automatic building of binaries.
There was a previous version of the Debian source format, which is now being phased out. Instructions for converting an old-style package are given in the Debian policy manual.
Various tools are provided for manipulating source packages; they pack and unpack sources and help build of binary packages and help manage the distribution of new versions.
They are introduced and typical uses described here; see
dpkg-source(1)
for full
documentation about their arguments and operation.
For examples of how to construct a Debian source package,
and how to use those utilities that are used by Debian
source packages, please see the hello
example
package.
dpkg-source
- packs and unpacks Debian source packages
This program is frequently used by hand, and is also
called from package-independent automated building scripts
such as dpkg-buildpackage
.
To unpack a package it is typically invoked with
dpkg-source -x .../path/to/filename.dsc
with the filename.tar.gz and filename.diff.gz (if applicable) in the same directory. It unpacks into package-version, and if applicable package-version.orig, in the current directory.
To create a packed source archive it is typically invoked:
dpkg-source -b package-version
This will create the .dsc, .tar.gz and
.diff.gz (if appropriate) in the current
directory. dpkg-source
does not clean the
source tree first - this must be done separately if it is
required.
See also Source packages as archives, section 3.3.
dpkg-buildpackage
- overall package-building control script
dpkg-buildpackage
is a script which invokes
dpkg-source
, the debian/rules
targets clean
, build
and
binary
, dpkg-genchanges
and
pgp
to build a signed source and binary
package upload.
It is usually invoked by hand from the top level of the built or unbuilt source directory. It may be invoked with no arguments; useful arguments include:
PATH
.
pgp-command must behave just like
pgp
.
PATH
if necessary, and pass its
second and subsequent arguments to the command it
calls. If no root-command is supplied
then dpkg-buildpackage will take no
special action to gain root privilege, so that for
most packages it will have to be invoked as root to
start with.
dpkg-source(1)
.
dpkg-gencontrol
- generates binary package control files
This program is usually called from debian/rules (see The Debianised source tree, section 3.2) in the top level of the source tree.
This is usually done just before the files and directories in the
temporary directory tree where the package is being built have their
permissions and ownerships set and the package is constructed using
dpkg-deb/
[5].
dpkg-gencontrol
must be called after all the
files which are to go into the package have been placed in
the temporary build directory, so that its calculation of
the installed size of a package is correct.
It is also necessary for dpkg-gencontrol
to
be run after dpkg-shlibdeps
so that the
variable substitutions created by
dpkg-shlibdeps
in debian/substvars
are available.
For a package which generates only one binary package, and
which builds it in debian/tmp relative to the top
of the source package, it is usually sufficient to call
dpkg-gencontrol
.
Sources which build several binaries will typically need something like:
dpkg-gencontrol -Pdebian/tmp-pkg -ppackageThe -P tells
dpkg-gencontrol
that the package is being
built in a non-default directory, and the -p
tells it which package's control file should be generated.
dpkg-gencontrol
also adds information to the
list of files in debian/files, for the benefit of
(for example) a future invocation of
dpkg-genchanges
.
dpkg-shlibdeps
- calculates shared library dependencies
This program is usually called from debian/rules
just before dpkg-gencontrol
(see The Debianised source tree, section 3.2), in the top level of the source tree.
Its arguments are executables [6] for which shared library dependencies should be included in the binary package's control file.
If some of the executable(s) shared libraries should only warrant a Recommends or Suggests, or if some warrant a Pre-Depends, this can be achieved by using the -ddependency-field option before those executable(s). (Each -d option takes effect until the next -d.)
dpkg-shlibdeps
does not directly cause the
output control file to be modified. Instead by default it
adds to the debian/substvars file variable
settings like shlibs:Depends. These variable
settings must be referenced in dependency fields in the
appropriate per-binary-package sections of the source
control file.
For example, the procps
package generates two
kinds of binaries, simple C binaries like ps
which require a predependency and full-screen ncurses
binaries like top
which require only a
recommendation. It can say in its debian/rules:
dpkg-shlibdeps -dPre-Depends ps -dRecommends topand then in its main control file debian/control:
... Package: procps Pre-Depends: ${shlibs:Pre-Depends} Recommends: ${shlibs:Recommends} ...
Sources which produce several binary packages with
different shared library dependency requirements can use
the -pvarnameprefix option to override
the default shlib: prefix (one invocation of
dpkg-shlibdeps
per setting of this option).
They can thus produce several sets of dependency
variables, each of the form
varnameprefix:dependencyfield,
which can be referred to in the appropriate parts of the
binary package control files.
dpkg-distaddfile
- adds a file to debian/files
Some packages' uploads need to include files other than the source and binary package files.
dpkg-distaddfile
adds a file to the
debian/files file so that it will be included in
the .changes file when
dpkg-genchanges
is run.
It is usually invoked from the binary
target of
debian/rules:
dpkg-distaddfile filename section priorityThe filename is relative to the directory where
dpkg-genchanges
will expect to find it - this
is usually the directory above the top level of the source
tree. The debian/rules target should put the
file there just before or just after calling
dpkg-distaddfile
.
The section and priority are passed unchanged into the resulting .changes file. See Section and Priority, subsection 4.2.9.
dpkg-genchanges
- generates a .changes upload control file
This program is usually called by package-independent
automatic building scripts such as
dpkg-buildpackage
, but it may also be called
by hand.
It is usually called in the top level of a built source tree, and when invoked with no arguments will print out a straightforward .changes file based on the information in the source package's changelog and control file and the binary and source packages which should have been built.
dpkg-parsechangelog
- produces parsed representation of a changelog
This program is used internally by
dpkg-source
et al. It may also occasionally
be useful in debian/rules and elsewhere. It
parses a changelog, debian/changelog by default,
and prints a control-file format representation of the
information in it to standard output.
The source archive scheme described later is intended to allow a Debianised source tree with some associated control information to be reproduced and transported easily. The Debianised source tree is a version of the original program with certain files added for the benefit of the Debianisation process, and with any other changes required made to the rest of the source code and installation scripts.
The extra files created for Debian are in the subdirectory debian of the top level of the Debianised source tree. They are described below.
This file is an executable makefile, and contains the package-specific recipies for compiling the package and building binary package(s) out of the source.
It must start with the line #!/usr/bin/make -f,
so that it can be invoked by saying its name rather than
invoking make
explicitly.
Since an interactive debian/rules script makes it
impossible to autocompile that package and also makes it
hard for other people to reproduce the same binary
package, all required targets have to be
non-interactive. At a minimul, required targets are the
ones called by dpkg-buildpackage
, namely,
clean, binary, binary-arch, and
build. It also follows that any target that these
targets depend on must also be non-interactive.
The targets which are required to be present are:
build
target
does not make much sense. For these packages it is
good enough to provide two (or more) targets
(build-a and build-b or whatever)
for each of the ways of building the package, and a
build
target that does nothing. The
binary
target will have to build the
package in each of the possible ways and make the
binary package out of each.
The build
target must not do anything
that might require root privilege.
The build
target may need to run
clean
first - see below.
When a package has a configuration routine that
takes a long time, or when the makefiles are poorly
designed, or when build
needs to run
clean
first, it is a good idea to
touch build when the build process is
complete. This will ensure that if debian/rules
build is run again it will not rebuild the
whole program.
binary
target should be all that is
necessary for the user to build the binary
package. All these targets are required to be
non-interactive. It is split into two parts:
binary-arch
builds the packages' output
files which are specific to a particular
architecture, and binary-indep
builds
those which are not.
binary
should usually be a target with
no commands which simply depends on
binary-arch
and
binary-indep
.
Both binary-*
targets should depend on
the build
target, above, so that the
package is built if it has not been already. It
should then create the relevant binary package(s),
using dpkg-gencontrol
to make their
control files and dpkg-deb
to build
them and place them in the parent of the top level
directory.
If one of the binary-*
targets has
nothing to do (this will be always be the case if
the source generates only a single binary package,
whether architecture-dependent or not) it
must still exist, but should always
succeed.
Binary packages, chapter 2 describes how to construct
binary packages.
The binary
targets must be invoked as
root.
build
and binary
targets
may have had, except that it should leave alone any
output files created in the parent directory by a
run of binary
. This target is required
to be non-interactive.
If a build
file is touched at the end
of the build
target, as suggested
above, it must be removed as the first thing that
clean
does, so that running
build
again after an interrupted
clean
doesn't think that everything is
already done.
The clean
target must be invoked as
root if binary
has been invoked since
the last clean
, or if
build
has been invoked as root (since
build
may create directories, for
example).
The build
, binary
and
clean
targets must be invoked with a current
directory of the package's top-level directory.
Additional targets may exist in debian/rules, either as published or undocumented interfaces or for the package's internal use.
This file contains version-independent details about the source package and about the binary packages it creates.
It is a series of sets of control fields, each syntactically similar to a binary package control file. The sets are separated by one or more blank lines. The first set is information about the source package in general; each subsequent set describes one binary package that the source tree builds.
The syntax and semantics of the fields are described below in Control files and their fields, chapter 4.
The general (binary-package-independent) fields are:
The per-binary-package fields are:
These fields are used by dpkg-gencontrol
to
generate control files for binary packages (see below), by
dpkg-genchanges
to generate the
.changes file to accompany the upload, and by
dpkg-source
when it creates the .dsc
source control file as part of a source archive.
The fields here may contain variable references - their
values will be substituted by
dpkg-gencontrol
, dpkg-genchanges
or dpkg-source
when they generate output
control files. See debian/substvars
and variable substitutions, subsection 3.2.4 for details.
Additional user-defined fields may be added to the source package control file. Such fields will be ignored, and not copied to (for example) binary or source package control files or upload control files.
If you wish to add additional unsupported fields to these output files you should use the mechanism described here.
Fields in the main source control information file with names starting X, followed by one or more of the letters BCS and a hyphen -, will be copied to the output files. Only the part of the field name after the hyphen will be used in the output file. Where the letter B is used the field will appear in binary package control files, where the letter S is used in source package control files and where C is used in upload control (.changes) files.
For example, if the main source information control file contains the field
XBS-Comment: I stand between the candle and the star.then the binary and source package control files will contain the field
Comment: I stand between the candle and the star.
This file records the changes to the Debian-specific parts of the package [7].
It has a special format which allows the package building tools to discover which version of the package is being built and find out other release-specific information.
That format is a series of entries like this:
package (version) distribution(s); urgency=urgency * change details more change details * even more change details -- maintainer name and email address date
package and version are the source package name and version number.
distribution(s) lists the distributions where this version should be installed when it is uploaded - it is copied to the Distribution field in the .changes file. See Distribution, subsection 4.2.14.
urgency is the value for the Urgency
field in the .changes file for the upload. See
Urgency, subsection 4.2.15. It is not possible to specify an
urgency containing commas; commas are used to separate
keyword=value settings in
the dpkg
changelog format (though there is
currently only one useful keyword,
urgency).
The change details may in fact be any series of lines starting with at least two spaces, but conventionally each change starts with an asterisk and a separating space and continuation lines are indented so as to bring them in line with the start of the text above. Blank lines may be used here to separate groups of changes, if desired.
The maintainer name and email address should not necessarily be those of the usual package maintainer. They should be the details of the person doing this version. The information here will be copied to the .changes file, and then later used to send an acknowledgement when the upload has been installed.
The date should be in RFC822 format [8]; it should include the timezone specified numerically, with the timezone name or abbreviation optionally present as a comment.
The first `title' line with the package name should start at the left hand margin; the `trailer' line with the maintainer and date details should be preceded by exactly one space. The maintainer details and the date must be separated by exactly two spaces.
An Emacs mode for editing this format is available: it is called debian-changelog-mode. You can have this mode selected automatically when you edit a Debian changelog by adding a local variables clause to the end of the changelog.
It is possible to use a different format to the standard one, by providing a parser for the format you wish to use.
In order to have dpkg-parsechangelog run your parser, you must include a line within the last 40 lines of your file matching the Perl regular expression: \schangelog-format:\s+([0-9a-z]+)\W The part in parentheses should be the name of the format. For example, you might say:
@@@ changelog-format: joebloggs @@@Changelog format names are non-empty strings of alphanumerics.
If such a line exists then dpkg-parsechangelog will look for the parser as /usr/lib/dpkg/parsechangelog/format-name or /usr/local/lib/dpkg/parsechangelog/format-name; it is an error for it not to find it, or for it not to be an executable program. The default changelog format is dpkg, and a parser for it is provided with the dpkg package.
The parser will be invoked with the changelog open on standard input at the start of the file. It should read the file (it may seek if it wishes) to determine the information required and return the parsed information to standard output in the form of a series of control fields in the standard format. By default it should return information about only the most recent version in the changelog; it should accept a -vversion option to return changes information from all versions present strictly after version, and it should then be an error for version not to be present in the changelog.
The fields are:
If several versions are being returned (due to the use of -v), the urgency value should be of the highest urgency code listed at the start of any of the versions requested followed by the concatenated (space-separated) comments from all the versions requested; the maintainer, version, distribution and date should always be from the most recent version.
For the format of the Changes field see Changes, subsection 4.2.18.
If the changelog format which is being parsed always or almost always leaves a blank line between individual change notes these blank lines should be stripped out, so as to make the resulting output compact.
If the changelog format does not contain date or package name information this information should be omitted from the output. The parser should not attempt to synthesise it or find it from other sources.
If the changelog does not have the expected format the parser should exit with a nonzero exit status, rather than trying to muddle through and possibly generating incorrect output.
A changelog parser may not interact with the user at all.
When dpkg-gencontrol
,
dpkg-genchanges
and dpkg-source
generate control files they do variable substitutions on
their output just before writing it. Variable
substitutions have the form
${variable-name}. The optional file
debian/substvars contains variable substitutions
to be used; variables can also be set directly from
debian/rules using the -V option to the
source packaging commands, and certain predefined
variables are available.
The is usually generated and modified dynamically by
debian/rules targets; in this case it must be
removed by the clean
target.
See dpkg-source(1)
for full
details about source variable substitutions, including the
format of debian/substvars.
This file is not a permanent part of the source tree; it
is used while building packages to record which files are
being generated. dpkg-genchanges
uses it
when it generates a .changes file.
It should not exist in a shipped source package, and so it
(and any backup files or temporary files such as
files.new
[9]) should be removed by the
clean
target. It may also be wise to
ensure a fresh start by emptying or removing it at the
start of the binary
target.
dpkg-gencontrol
adds an entry to this file
for the .deb file that will be created by
dpkg-deb
from the control file that it
generates, so for most packages all that needs to be done
with this file is to delete it in clean
.
If a package upload includes files besides the source
package and any binary packages whose control files were
made with dpkg-gencontrol
then they should be
placed in the parent of the package's top-level directory
and dpkg-distaddfile
should be called to add
the file to the list in debian/files.
This is the canonical temporary location for the
construction of binary packages by the binary
target. The directory tmp serves as the root of
the filesystem tree as it is being constructed (for
example, by using the package's upstream makefiles install
targets and redirecting the output there), and it also
contains the DEBIAN subdirectory. See Creating package files -
dpkg-deb
, section 2.1.
If several binary packages are generated from the same source tree it is usual to use several debian/tmpsomething directories, for example tmp-a or tmp-doc.
Whatever tmp directories are created and used by
binary
must of course be removed by the
clean
target.
As it exists on the FTP site, a Debian source package consists of three related files. You must have the right versions of all three to be able to use them.
This file contains a series of fields, identified and separated just like the fields in the control file of a binary package. The fields are listed below; their syntax is described above, in Control files and their fields, chapter 4.
The source package control file is generated by
dpkg-source
when it builds the source
archive, from other files in the source package,
described above. When unpacking it is checked against
the files and directories in the other parts of the
source package, as described below.
tar
file containing the source code from
the upstream authors of the program. The tarfile
unpacks into a directory
package-upstream-version.orig,
and does not contain files anywhere other than in
there or in its subdirectories.
dpkg-source
if necessary when unpacking.
The dpkg-source
program will
automatically make the debian/rules file
executable (see below).
If there is no original source code - for example, if the package is specially prepared for Debian or the Debian maintainer is the same as the upstream maintainer - the format is slightly different: then there is no diff, and the tarfile is named package_version.tar.gz and contains a directory package-version.
dpkg-source
dpkg-source -x is the recommended way to unpack a Debian source package. However, if it is not available it is possible to unpack a Debian source archive as follows:
It is not possible to generate a valid Debian source archive
without using dpkg-source
. In particular,
attempting to use diff
directly to generate the
.diff.gz file will not work.
The source package may not contain any hard links [10] [11], device special files, sockets or setuid or setgid files. [12]
The source packaging tools manage the changes between the
original and Debianised source using diff
and
patch
. Turning the original source tree as
included in the .orig.tar.gz into the debianised
source must not involve any changes which cannot be
handled by these tools. Problematic changes which cause
dpkg-source
to halt with an error when
building the source package are:
dpkg-source
to
print a warning but continue anyway are:
dpkg-source
, are:
The debian directory and debian/rules
are handled specially by dpkg-source
- before
applying the changes it will create the debian
directory, and afterwards it will make
debian/rules world-exectuable.