Maintainers should preserve the modification times of the upstream source files in a package, as far as is reasonably possible.[15]
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 required and optional targets are as follows:
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.[16]
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.[17]
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.
This file records the changes to the Debian-specific parts of the package[18].
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 <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 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).[19]
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.[20]
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, and then later used to send an acknowledgement when the upload has been installed.
The date should be in RFC822 format[21]; 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.
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 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 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[22]) 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.
The source package may not contain any hard links[23], device special files, sockets or setuid or setgid files.[24]
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.[25]
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.
Debian Policy Manual
version 3.5.6.1, 2002-03-14ijackson@gnu.ai.mit.eduschwarz@debian.orgbweaver@debian.orgdebian-policy@lists.debian.org