Source packages should specify the most recent version number of this policy document with which your package complied when it was last updated.
This information may be used to file bug reports automatically if your package becomes too much out of date.
The version is specified in the Standards-Version control field. The format of the Standards-Version field is described in Standards-Version, Section 5.6.11.
You should regularly, and especially if your package has become out of date, check for the newest Policy Manual available and update your package, if necessary. When your package complies with the new standards you should update the Standards-Version source package field and release it.[10]
Source packages should specify which binary packages they require to be installed or not to be installed in order to build correctly. For example, if building a package requires a certain compiler, then the compiler should be specified as a build-time dependency.
It is not necessary to explicitly specify build-time relationships on a minimal
set of packages that are always needed to compile, link and put in a Debian
package a standard "Hello World!" program written in C or C++. The
required packages are called build-essential, and an informational
list can be found in /usr/share/doc/build-essential/list
(which is
contained in the build-essential package).[11]
When specifying the set of build-time dependencies, one should list only those packages explicitly required by the build. It is not necessary to list packages which are required merely because some other package in the list of build-time dependencies depends on them.[12]
If build-time dependencies are specified, it must be possible to build the package and produce working binaries on a system with only essential and build-essential packages installed and also those required to satisfy the build-time relationships (including any implied relationships). In particular, this means that version clauses should be used rigorously in build-time relationships so that one cannot produce bad or inconsistently configured packages when the relationships are properly satisfied.
Declaring relationships between packages, Chapter 7 explains the technical details.
If changes to the source code are made that are not specific to the needs of the Debian system, they should be sent to the upstream authors in whatever form they prefer so as to be included in the upstream version of the package.
If you need to configure the package differently for Debian or for Linux, and
the upstream source doesn't provide a way to do so, you should add such
configuration facilities (for example, a new autoconf
test or
#define) and send the patch to the upstream authors, with the
default set to the way they originally had it. You can then easily override
the default in your debian/rules
or wherever is appropriate.
You should make sure that the configure
utility detects the
correct architecture specification string (refer to Architecture specification
strings, Section 11.1 for details).
If you need to edit a Makefile
where GNU-style
configure
scripts are used, you should edit the .in
files rather than editing the Makefile
directly. This allows the
user to reconfigure the package if necessary. You should not
configure the package and edit the generated Makefile
! This makes
it impossible for someone else to later reconfigure the package without losing
the changes you made.
debian/changelog
Changes in the Debian version of the package should be briefly explained in the
Debian changelog file debian/changelog
.[13] This includes modifications made
in the Debian package compared to the upstream one as well as other changes and
updates to the package. [14]
The format of the debian/changelog
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 [optional blank line(s), stripped] * change details more change details [blank line(s), included in output of dpkg-parsechangelog] * even more change details [optional blank line(s), stripped] -- maintainer name <email address>[two spaces] 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 5.6.14.
urgency is the value for the Urgency field in the
.changes
file for the upload (see Urgency, Section
5.6.17). 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).[15]
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.
If this upload resolves bugs recorded in the Bug Tracking System (BTS), they may be automatically closed on the inclusion of this package into the Debian archive by including the string: closes: Bug#nnnnn in the change details.[16] This information is conveyed via the Closes field in the .changes file (see Closes, Section 5.6.22).
The maintainer name and email address used in the changelog should be the details of the person uploading this version. They are not necessarily those of the usual package maintainer. The information here will be copied to the Changed-By field in the .changes file (see Changed-By, Section 5.6.4), and then later used to send an acknowledgement when the upload has been installed.
The date should be in RFC822 format[17]; it should include the time zone specified numerically, with the time zone name or abbreviation optionally present as a comment in parentheses.
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.
For more information on placement of the changelog files within binary packages, please see Changelog files, Section 12.7.
In non-experimental packages you must use a format for
debian/changelog
which is supported by the most recent released
version of dpkg
.
It is possible to use a format different from the standard one by providing a
changelog parser for the format you wish to use. The parser must have an API
compatible with that expected by dpkg-genchanges
and
dpkg-gencontrol
, and it must not interact with the user at all.
[18]
When make
invokes a command in a makefile (including your
package's upstream makefiles and debian/rules
), it does so using
sh
. This means that sh
's usual bad error handling
properties apply: if you include a miniature script as one of the commands in
your makefile you'll find that if you don't do anything about it then errors
are not detected and make
will blithely continue after problems.
Every time you put more than one shell command (this includes using a loop) in a makefile command you must make sure that errors are trapped. For simple compound commands, such as changing directory and then running a program, using && rather than semicolon as a command separator is sufficient. For more complex commands including most loops and conditionals you should include a separate set -e command at the start of every makefile command that's actually one of these miniature shell scripts.
Maintainers should preserve the modification times of the upstream source files in a package, as far as is reasonably possible.[19]
The source package may not contain any hard links[20], device special files, sockets or setuid or setgid files.[21]
debian/rules
This file must be an executable makefile, and contains the package-specific recipes for compiling the package and building binary package(s) from 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
auto-compile that package and also makes it hard for other people to reproduce
the same binary package, all required targets MUST be non-interactive.
At a minimum, required targets are the ones called by
dpkg-buildpackage
, namely, clean, binary,
binary-arch, binary-indep, and build. It also
follows that any target that these targets depend on must also be
non-interactive.
The targets are as follows (required unless stated otherwise):
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 build target must not do anything that might require root privilege.
The build target may need to run the clean target first - see below.
When a package has a configuration and build routine which 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.[22]
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.
The build-arch and build-indep targets must not do anything that might require root privilege.
binary-arch
builds the binary packages which are
specific to a particular architecture, and binary-indep builds
those which are not.
binary may be (and commonly is) a target with no commands which simply depends on binary-arch and binary-indep.
Both binary-* targets should depend on the build
target, or on the appropriate build-arch or
build-indep target, if provided, 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.
Both the binary-arch and binary-indep targets must exist. If one of them has nothing to do (which will always be the case if the source generates only a single binary package, whether architecture-dependent or not), it must still exist and must always succeed.
The binary targets must be invoked as root.[23]
If a build file is touched at the end of the build target, as suggested above, it should be removed as the first action that clean performs, so that running build again after an interrupted clean doesn't think that everything is already done.
The clean target may need to 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 the current directory being 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 architectures we build on and build for are determined by make
variables using the utility dpkg-architecture
.
You can determine the Debian architecture and the GNU style architecture
specification string for the build machine (the machine type we are building
on) as well as for the host machine (the machine type we are building for).
Here is a list of supported make
variables:
where * is either BUILD for specification of the build machine or HOST for specification of the host machine.
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 only determines which Debian architecture we are building on or for. It should not be used to get the CPU or system information; the GNU style variables should be used for that.
debian/substvars
When dpkg-gencontrol
, dpkg-genchanges
and
dpkg-source
generate control files they perform variable
substitutions on their output just before writing it. Variable substitutions
have the form ${variable}. 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 also available.
The debian/substvars
file is usually generated and modified
dynamically by debian/rules
targets, in which 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
.
debian/files
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
[24]) 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.
When dpkg-gencontrol
is run for a binary package, it adds an entry
to debian/files
for the .deb
file that will be
created when dpkg-deb --build is run for that binary package. So
for most packages all that needs to be done with this file is to delete it in
the clean target.
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
.
Debian Policy Manual
version 3.6.2.1, 2005-07-21