Maintainers are encouraged to preserve the modification times of the upstream source files in a package, as far as is reasonably possible. Even though this is optional, this is still a good idea. [8]
This file must be an executable makefile, and contains the package-specific recipes 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
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, and build. It also follows that any target that
these targets depend on must also be non-interactive.
The targets which must be present are:
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 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 must 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
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, 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, and must
always succeed.
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
must be non-interactive.
If a build
file is touched at the end of the build
target, as suggested above, it should 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 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 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. 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 records the changes to the Debian-specific parts of the package [9].
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 3.2.4.
urgency is the value for the Urgency field in the
.changes file for the upload. 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 need 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 [10]; it should include the time zone specified numerically, with the time zone 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.
It is possible to use a different format to the standard one, by providing a parser for the format you wish to use.
A changelog parser must 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 [11]) 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.
The source package may not contain any hard links [12] [13], device special files, sockets or setuid or setgid files. [14]
The description is intended to describe the program to a user who has never met it before so that they know whether they want to install it. It should also give information about the significant dependencies and conflicts between this package and others, so that the user knows why these dependencies and conflicts have been declared.
The single line synopsis should be kept brief - certainly under 80 characters.
Do not include the package name in the synopsis line. The display software knows how to display this already, and you do not need to state it. Remember that in many situations the user may only see the synopsis line - make it as informative as you can.
Do not try to continue the single line synopsis into the extended description. This will not work correctly when the full description is displayed, and makes no sense where only the summary (the single line synopsis) is available.
The extended description should describe what the package does and how it relates to the rest of the system (in terms of, for example, which subsystem it is which part of).
The description field needs to make sense to anyone, even people who have no idea about any of the things the package deals with. [15]
Put important information first, both in the synopsis and extended description. Sometimes only the first part of the synopsis or of the description will be displayed. You can assume that there will usually be a way to see the whole extended description.
You may include information about dependencies and so forth in the extended description, if you wish.
Do not use tab characters. Their effect is not predictable.
ijackson@gnu.ai.mit.edu
schwarz@debian.org
bweaver@debian.org
debian-policy@lists.debian.org