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 C.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 filesThis program is usually called from debian/rules (see The Debianised source tree, Section C.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/
[65].
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 -ppackage
The -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 C.2), in the top level of the source tree.
Its arguments are executables. [66] for which shared library dependencies should be included in the binary package's control file.
If some of the found 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 top
and 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/filesSome 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 priority
The 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, Section D.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.
dpkg-architecture
- information about the build and host systemThis program can be used manually, but is also invoked by dpkg-buildpackage or debian/rules to set to set environment or make variables which specify the build and host architecture for the package building process.
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:
A package may also provide both of the targets build-arch and build-indep. The build-arch target, if provided, should perform all non-interactive configuration and compilation required for producing all architecture-dependant binary packages (those packages for which the body of the Architecture field in debian/control is not all). Similarly, the build-indep target, if provided, should perform all non-interactive configuration and compilation required for producing all architecture-independent binary packages (those packages for which the body of the Architecture field in debian/control is all). The build target should depend on those of the targets build-arch and build-indep that are provided in the rules file.
If one or both of the targets build-arch and build-indep are not provided, then invoking debian/rules with one of the not-provided targets as arguments should produce a exit status code of 2. Usually this is provided automatically by make if the target is missing.
For some packages, notably ones where the same source tree is compiled in different ways to produce two binary packages, the 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 targets build, build-arch and build-indep 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 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 (from old Packaging Manual), Appendix B describes how to construct binary packages.
The binary targets must be invoked as root.
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).
This target may be invoked in any directory, and should take care to clean up any temporary files it may have left.
This target is optional, but providing it if possible is a good idea.
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.
The architecture we build on and build for is determined by make variables via
dpkg-architecture (see dpkg-architecture
-
information about the build and host system, Section C.1.8). You can get
the Debian architecture and the GNU style architecture specification string for
the build machine as well as the host machine. Here is a list of supported
make variables:
where * is either BUILD for specification of the build machine or HOST for specification of the machine we build for.
Backward compatibility can be provided in the rules file by setting the needed variables to suitable default values, please refer to the documentation of dpkg-architecture for details.
It is important to understand that the DEB_*_ARCH string does only determine which Debian architecture we build on resp. for. It should not be used to get the CPU or System information, the GNU style variables should be used for that.
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 (from old Packaging Manual), Appendix D.
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, Section C.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 [67].
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, Section D.2.14.
urgency is the value for the Urgency field in the
.changes file for the upload. See Urgency, Section
D.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 [68]; 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, Section D.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 [69]) 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 B.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.
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.
All the directories in the diff must exist, except the debian
subdirectory of the top of the source tree, which will be created by
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 [70] [71], device special files, sockets or setuid or setgid files. [72]
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:
Changes which cause dpkg-source
to print a warning but continue
anyway are:
Changes which are not represented, but which are not detected by
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.
Debian Policy Manual
version 3.5.6.1, 2002-03-14ijackson@gnu.ai.mit.edu
schwarz@debian.org
bweaver@debian.org
debian-policy@lists.debian.org