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. See dpkg-source(1)
for details.
The extra files created for Debian are in the subdirectory debian
of the top level of the Debianised source tree. They are described
below.
debian/rules
- the main building script
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.
The targets which are required to be present are:
build
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
Binary packages, chapter 2 describes how to construct binary packages.
The binary target must be invoked as root.
clean
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).
get-orig-source
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.
Additional targets may exist in debian/rules
, either as
published or undocumented interfaces or for the package's internal
use.
debian/control
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:
Source
(mandatory)Maintainer
Section
and Priority
(classification, mandatory)Standards-Version
The per-binary-package fields are:
Package
(mandatory)Architecture
(mandatory)Description
Section
and Priority
(classification)Essential
Depends
et al. (package interrelationships)
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.1.4 for details.
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.
debian/changelog
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; 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.
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]+)\WThe part in parentheses should be the name of the format.
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 -v
version 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:
Source
Version
(mandatory)Distribution
(mandatory)Urgency
(mandatory)Maintainer
(mandatory)Date
Changes
(mandatory)
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.
debian/substvars
and variable substitutions
${
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 file may be a static part of the source archive, or generated and
modified dynamically by debian/rules
targets. In the latter
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
.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
[5]) 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
.
debian/tmp
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/tmp
something 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.
.dsc
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.
package_
upstream-version.orig.tar.gz
gzip -9
) 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.
package_
version-revision.diff.gz
diff -u
) giving the changes which
are required to turn the original source into the Debian source.
These changes may only include editing and creating plain files. The
permissions of files, the targets of symbolic links and the
characteristics of special files or pipes may not be changed and no
files may be removed or renamed.
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 -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:
.orig
directory..orig
directory to
package-
version
.debian
at the top of the source
tree.patch -p0
.
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 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:
debian
.debian/rules
) and directories.
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.