+ </chapt>
+
+ <chapt id="controlfields"><heading>Control files and their fields</heading>
+
+ <p>
+ Many of the tools in the package management suite manipulate
+ data represented in a common format, known as <em>control
+ data</em>. The data is often stored in <em>control
+ files</em>. Binary and source packages have control files,
+ and the <tt>.changes</tt> files which control the installation
+ of uploaded files are also in control file format.
+ <prgn>Dpkg</prgn>'s internal databases are in a similar
+ format.
+ </p>
+
+ <sect><heading>Syntax of control files</heading>
+
+ <p>
+ A control file consists of one or more paragraphs of fields.
+ The paragraphs are separated by blank lines. Some control
+ files allow only one paragraph; others allow several, in
+ which case each paragraph usually refers to a different
+ package. (For example, in source packages, the first
+ paragraph refers to the source package, and later paragraphs
+ refer to binary packages generated from the source.)
+ </p>
+
+ <p>
+ Each paragraph consists of a series of data fields; each
+ field consists of the field name, followed by a colon and
+ then the data/value associated with that field. It ends at
+ the end of the line. Horizontal whitespace (spaces and
+ tabs) may occur immediately before or after the value and is
+ ignored there; it is conventional to put a single space
+ after the colon. For example, a field might be:
+ <example>
+ Package: libc6
+ </example>
+ the field name is <tt>Package</tt> and the field value
+ <tt>libc6</tt>.
+ </p>
+
+ <p>
+ Some fields' values may span several lines; in this case
+ each continuation line <em>must</em> start with a space or
+ tab. Any trailing spaces or tabs at the end of individual
+ lines of a field value are ignored.
+ </p>
+
+ <p>
+ Except where otherwise stated only a single line of data is
+ allowed and whitespace is not significant in a field body.
+ Whitespace must not appear inside names (of packages,
+ architectures, files or anything else) or version numbers,
+ or between the characters of multi-character version
+ relationships.
+ </p>
+
+ <p>
+ Field names are not case-sensitive, but it is usual to
+ capitalize the field names using mixed case as shown below.
+ </p>
+
+ <p>
+ Blank lines, or lines consisting only of spaces and tabs,
+ are not allowed within field values or between fields - that
+ would mean a new paragraph.
+ </p>
+
+ </sect>
+
+ <sect><heading>List of fields</heading>
+ <p>
+ This list here is not supposed to be exhaustive. Most fields
+ are dealt with elsewhere in this document.
+ </p>
+ <sect1 id="f-Package"><heading><tt>Package</tt>
+ </heading>
+
+ <p>
+ The name of the binary package. Package names consist of
+ the alphanumerics and <tt>+</tt> <tt>-</tt> <tt>.</tt>
+ (plus, minus and full stop).
+ </p>
+
+ <p>
+ They must be at least two characters long and must start
+ with an alphanumeric character and not be all digits. The
+ use of lowercase package names is strongly recommended
+ unless the package you're building (or referring to, in
+ other fields) is already using uppercase.</p>
+ </sect1>
+
+ <sect1 id="f-Version"><heading><tt>Version</tt>
+ </heading>
+
+ <p>
+ This lists the source or binary package's version number -
+ see <ref id="versions">.
+ </p>
+
+ </sect1>
+
+ <sect1
+ id="f-Standards-Version"><heading><tt>Standards-Version</tt>
+ </heading>
+
+ <p>
+ The most recent version of the standards (the policy
+ manual and associated texts) with which the package
+ complies. This is updated manually when editing the
+ source package to conform to newer standards; it can
+ sometimes be used to tell when a package needs attention.
+ Its format is described above; see
+ <ref id="standardsversion">.
+ </p>
+ </sect1>
+
+
+ <sect1 id="f-Distribution"><heading><tt>Distribution</tt>
+ </heading>
+
+ <p>
+ In a <tt>.changes</tt> file or parsed changelog output
+ this contains the (space-separated) name(s) of the
+ distribution(s) where this version of the package should
+ be installed. Valid distributions are determined by the
+ archive maintainers.
+ <footnote>
+ Current distribution names are:
+ <taglist>
+ <tag><em>stable</em></tag>
+ <item>
+ <p>
+ This is the current `released' version of Debian
+ GNU/Linux. Once the distribution is
+ <em>stable</em> only security fixes and other
+ major bug fixes are allowed. When changes are
+ made to this distribution, the release number is
+ increased (for example: 2.2r1 becomes 2.2r2 then
+ 2.2r3, etc).
+ </p>
+ </item>
+
+ <tag><em>unstable</em></tag>
+ <item>
+ <p>
+ This distribution value refers to the
+ <em>developmental</em> part of the Debian
+ distribution tree. New packages, new upstream
+ versions of packages and bug fixes go into the
+ <em>unstable</em> directory tree. Download from
+ this distribution at your own risk.
+ </p>
+ </item>
+
+ <tag><em>testing</em></tag>
+ <item>
+ <p>
+ This distribution value refers to the
+ <em>testing</em> part of the Debian distribution
+ tree. It receives its packages from the
+ unstable distribution after a short time lag to
+ ensure that there are no major issues with the
+ unstable packages. It is less prone to breakage
+ than unstable, but still risky. It is not
+ possible to upload packages directly to
+ <em>testing</em>.
+ </p>
+ </item>
+
+ <tag><em>frozen</em></tag>
+ <item>
+ <p>
+ From time to time, the <em>frozen</em>
+ distribution enters a state of `code-freeze' in
+ anticipation of release as a <em>stable</em>
+ version. During this period of testing only
+ fixes for existing or newly-discovered bugs will
+ be allowed. The exact details of this stage are
+ determined by the Release Manager.
+ </p>
+ </item>
+
+ <tag><em>experimental</em></tag>
+ <item>
+ <p>
+ The packages with this distribution value are
+ deemed by their maintainers to be high
+ risk. Oftentimes they represent early beta or
+ developmental packages from various sources that
+ the maintainers want people to try, but are not
+ ready to be a part of the other parts of the
+ Debian distribution tree. Download at your own
+ risk.
+ </p>
+ </item>
+ </taglist>
+
+ You should list <em>all</em> distributions that the
+ package should be installed into.
+ </footnote>
+ </p>
+ </sect1>
+
+
+ </sect>
+ </chapt>
+
+ <chapt id="versions"><heading>Version numbering</heading>
+
+ <p>
+ Every package has a version number recorded in its
+ <tt>Version</tt> control file field.
+ </p>
+
+ <p>
+ The package management system imposes an ordering on version
+ numbers, so that it can tell whether packages are being up- or
+ downgraded and so that package system front end applications
+ can tell whether a package it finds available is newer than
+ the one installed on the system. The version number format
+ has the most significant parts (as far as comparison is
+ concerned) at the beginning.
+ </p>
+
+ <p>
+ The version number format is:
+ &lsqb<var>epoch</var><tt>:</tt>]<var>upstream_version</var>[<tt>-</tt><var>debian_revision</var>]
+ </p>
+
+ <p>
+ The three components here are:
+ <taglist>
+ <tag><var>epoch</var></tag>
+ <item>
+
+ <p>
+ This is a single (generally small) unsigned integer. It
+ may be omitted, in which case zero is assumed. If it is
+ omitted then the <var>upstream_version</var> may not
+ contain any colons.
+ </p>
+
+ <p>
+ It is provided to allow mistakes in the version numbers
+ of older versions of a package, and also a package's
+ previous version numbering schemes, to be left behind.
+ </p>
+
+ </item>
+
+ <tag><var>upstream_version</var></tag>
+ <item>
+
+ <p>
+ This is the main part of the version number. It is
+ usually the version number of the original (`upstream')
+ package from which the <tt>.deb</tt> file has been made,
+ if this is applicable. Usually this will be in the same
+ format as that specified by the upstream author(s);
+ however, it may need to be reformatted to fit into the
+ package management system's format and comparison
+ scheme.
+ </p>
+
+ <p>
+ The comparison behavior of the package management system
+ with respect to the <var>upstream_version</var> is
+ described below. The <var>upstream_version</var>
+ portion of the version number is mandatory.
+ </p>
+
+ <p>
+ The <var>upstream_version</var> may contain only
+ alphanumerics
+ <footnote>
+ <p>Alphanumerics are <tt>A-Za-z0-9</tt> only.</p>
+ </footnote>
+ and the characters <tt>.</tt> <tt>+</tt> <tt>-</tt>
+ <tt>:</tt> (full stop, plus, hyphen, colon) and should
+ start with a digit. If there is no
+ <var>debian_revision</var> then hyphens are not allowed;
+ if there is no <var>epoch</var> then colons are not
+ allowed.</p>
+ </item>
+
+ <tag><var>debian_revision</var></tag>
+ <item>
+
+ <p>
+ This part of the version number specifies the version of
+ the Debian package based on the upstream version. It
+ may contain only alphanumerics and the characters
+ <tt>+</tt> and <tt>.</tt> (plus and full stop) and is
+ compared in the same way as the
+ <var>upstream_version</var> is.
+ </p>
+
+ <p>
+ It is optional; if it isn't present then the
+ <var>upstream_version</var> may not contain a hyphen.
+ This format represents the case where a piece of
+ software was written specifically to be turned into a
+ Debian package, and so there is only one `debianization'
+ of it and therefore no revision indication is required.
+ </p>
+
+ <p>
+ It is conventional to restart the
+ <var>debian_revision</var> at <tt>1</tt> each time the
+ <var>upstream_version</var> is increased.
+ </p>
+
+ <p>
+ The package management system will break the version
+ number apart at the last hyphen in the string (if there
+ is one) to determine the <var>upstream_version</var> and
+ <var>debian_revision</var>. The absence of a
+ <var>debian_revision</var> compares earlier than the
+ presence of one (but note that the
+ <var>debian_revision</var> is the least significant part
+ of the version number).
+ </p>
+ </item>
+ </taglist>
+ The <var>upstream_version</var> and <var>debian_revision</var>
+ parts are compared by the package management system using the
+ same algorithm:
+ </p>
+
+ <p>
+ The strings are compared from left to right.
+ </p>
+
+ <p>
+ First the initial part of each string consisting entirely of
+ non-digit characters is determined. These two parts (one of
+ which may be empty) are compared lexically. If a difference
+ is found it is returned. The lexical comparison is a
+ comparison of ASCII values modified so that all the letters
+ sort earlier than all the non-letters.
+ </p>
+
+ <p>
+ Then the initial part of the remainder of each string which
+ consists entirely of digit characters is determined. The
+ numerical values of these two parts are compared, and any
+ difference found is returned as the result of the comparison.
+ For these purposes an empty string (which can only occur at
+ the end of one or both version strings being compared) counts
+ as zero.
+ </p>
+
+ <p>
+ These two steps (comparing and removing initial non-digit
+ strings and initial digit strings) are repeated until a
+ difference is found or both strings are exhausted.
+ </p>
+
+ <p>
+ Note that the purpose of epochs is to allow us to leave behind
+ mistakes in version numbering, and to cope with situations
+ where the version numbering scheme changes. It is
+ <em>not</em> intended to cope with version numbers containing
+ strings of letters which the package management system cannot
+ interpret (such as <tt>ALPHA</tt> or <tt>pre-</tt>), or with
+ silly orderings (the author of this manual has heard of a
+ package whose versions went <tt>1.1</tt>, <tt>1.2</tt>,
+ <tt>1.3</tt>, <tt>1</tt>, <tt>2.1</tt>, <tt>2.2</tt>,
+ <tt>2</tt> and so forth).
+ </p>
+
+ <p>
+ If an upstream package has problematic version numbers they
+ should be converted to a sane form for use in the
+ <tt>Version</tt> field.
+ </p>
+
+ <sect>
+ <heading>Version numbers based on dates</heading>
+ <p>
+ In general, Debian packages should use the same version
+ numbers as the upstream sources.</p>
+
+ <p>
+ However, in some cases where the upstream version number is
+ based on a date (e.g., a development `snapshot' release) the
+ package management system cannot handle these version
+ numbers without epochs. For example, dpkg will consider
+ `96May01' to be greater than `96Dec24'.</p>
+
+ <p>
+ To prevent having to use epochs for every new upstream
+ version, the version number should be changed to the
+ following format in such cases: `19960501', `19961224'. It
+ is up to the maintainer whether he/she wants to bother the
+ upstream maintainer to change the version numbers upstream,
+ too.</p>
+
+ <p>
+ Note that other version formats based on dates which are
+ parsed correctly by the package management system should
+ <em>not</em> be changed.</p>
+
+ <p>
+ Native Debian packages (i.e., packages which have been
+ written especially for Debian) whose version numbers include
+ dates should always use the `YYYYMMDD' format.</p>
+ </sect>
+ </chapt>
+
+ <chapt id="miscellaneous"><heading>Packaging Considerations</heading>
+
+ <sect id="timestamps"><heading>Time Stamps</heading>
+ <p>
+ Maintainers should preserve the modification times of the
+ upstream source files in a package, as far as is reasonably
+ possible.
+ <footnote>
+ <p>
+ The rationale is that there is some information conveyed
+ by knowing the age of the file, for example, you could
+ recognize that some documentation is very old by looking
+ at the modification time, so it would be nice if the
+ modification time of the upstream source would be
+ preserved.
+ </p>
+ </footnote>
+ </p>
+ </sect>
+
+ <sect id="debianrules"><heading><tt>debian/rules</tt> - the
+ main building script</heading>
+
+ <p>
+ 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.
+ </p>
+
+ <p>
+ It must start with the line <tt>#!/usr/bin/make -f</tt>,
+ so that it can be invoked by saying its name rather than
+ invoking <prgn>make</prgn> explicitly.
+ </p>
+
+ <p>
+ Since an interactive <tt>debian/rules</tt> script makes it
+ impossible to auto-compile that package and also makes it
+ hard for other people to reproduce the same binary
+ package, all <em>required targets</em> MUST be
+ non-interactive. At a minimum, required targets are the
+ ones called by <prgn>dpkg-buildpackage</prgn>, namely,
+ <em>clean</em>, <em>binary</em>, <em>binary-arch</em>,
+ <em>binary-indep</em>, and <em>build</em>. It also follows
+ that any target that these targets depend on must also be
+ non-interactive.
+ </p>
+
+ <p>
+ The required and optional targets are as follows:
+ <taglist>
+ <tag><tt>build</tt></tag>
+ <item>
+ <p>
+ This should perform all non-interactive configuration
+ and compilation of the package. If a package has an
+ interactive pre-build configuration routine, the
+ Debianized source package must either be built after
+ this has taken place (so that the binary package can
+ be built without rerunning the configuration) or the
+ configuration routine modified to become
+ non-interactive. (The latter is preferable if there
+ are architecture-specific features detected by the
+ configuration routine.)
+ </p>
+
+ <p>
+ For some packages, notably ones where the same
+ source tree is compiled in different ways to produce
+ two binary packages, the <prgn>build</prgn> target
+ does not make much sense. For these packages it is
+ good enough to provide two (or more) targets
+ (<tt>build-a</tt> and <tt>build-b</tt> or whatever)
+ for each of the ways of building the package, and a
+ <prgn>build</prgn> target that does nothing. The
+ <prgn>binary</prgn> target will have to build the
+ package in each of the possible ways and make the
+ binary package out of each.
+ </p>
+
+ <p>
+ The <prgn>build</prgn> target must not do anything
+ that might require root privilege.
+ </p>
+
+ <p>
+ The <prgn>build</prgn> target may need to run the
+ <prgn>clean</prgn> target first - see below.
+ </p>
+
+ <p>
+ When a package has a configuration and build routine
+ which takes a long time, or when the makefiles are
+ poorly designed, or when <prgn>build</prgn> needs to
+ run <prgn>clean</prgn> first, it is a good idea to
+ <tt>touch build</tt> when the build process is
+ complete. This will ensure that if <tt>debian/rules
+ build</tt> is run again it will not rebuild the whole
+ program.
+ <footnote>
+ <p>
+ Another common way to do this is for <prgn>build</prgn>
+ to depend on <prgn>build-stamp</prgn> and to do
+ nothing else, and for the <prgn>build-stamp</prgn>
+ target to do the building and to <tt>touch
+ build-stamp</tt> on completion. This is
+ especially useful if the build routine creates a
+ file or directory called <tt>build</tt>; in such a
+ case, <prgn>build</prgn> will need to be listed as
+ a phony target (i.e., as a dependency of the
+ <tt>.PHONY</tt> target). See the documentation of
+ <prgn>make</prgn> for more information on phony
+ targets.
+ </p>
+ </footnote>
+ </p>
+ </item>
+
+ <tag><tt>binary</tt>, <tt>binary-arch</tt>,
+ <tt>binary-indep</tt>
+ </tag>
+ <item>
+ <p>
+ The <prgn>binary</prgn> target must be all that is
+ necessary for the user to build the binary package(s)
+ produced from this source package. All of these
+ targets are required to be non-interactive. It is
+ split into two parts: <prgn>binary-arch</prgn> builds
+ the binary packages which are specific to a particular
+ architecture, and <prgn>binary-indep</prgn> builds
+ those which are not.
+ </p>
+
+ <p>
+ <prgn>binary</prgn> may be (and commonly is) a target
+ with no commands which simply depends on
+ <prgn>binary-arch</prgn> and
+ <prgn>binary-indep</prgn>.
+ </p>
+
+ <p>
+ Each <prgn>binary-*</prgn> target should depend on
+ the <prgn>build</prgn> target, above, so that the
+ package is built if it has not been already. It
+ should then create the relevant binary package(s),
+ using <prgn>dpkg-gencontrol</prgn> to make their
+ control files and <prgn>dpkg-deb</prgn> to build
+ them and place them in the parent of the top level
+ directory.
+ </p>
+
+ <p>
+ Both the <prgn>binary-arch</prgn> and
+ <prgn>binary-indep</prgn> targets <em>must</em> 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.
+ </p>
+
+ <p>
+ The <prgn>binary</prgn> targets must be invoked as
+ root.
+ <footnote>
+ <p>
+ The <prgn>fakeroot</prgn> package often allows one
+ to build a package correctly even without being
+ root.
+ </p>
+ </footnote>
+ </p>
+ </item>
+
+ <tag><tt>clean</tt></tag>
+ <item>
+
+ <p>
+ This must undo any effects that the <prgn>build</prgn>
+ and <prgn>binary</prgn> targets may have had, except
+ that it should leave alone any output files created in
+ the parent directory by a run of a <prgn>binary</prgn>
+ target. This target must be non-interactive.
+ </p>
+
+ <p>
+ If a <prgn>build</prgn> file is touched at the end of
+ the <prgn>build</prgn> target, as suggested above, it
+ should be removed as the first action that
+ <prgn>clean</prgn> performs, so that running
+ <prgn>build</prgn> again after an interrupted
+ <prgn>clean</prgn> doesn't think that everything is
+ already done.
+ </p>
+
+ <p>
+ The <prgn>clean</prgn> target may need to be
+ invoked as root if <prgn>binary</prgn> has been
+ invoked since the last <prgn>clean</prgn>, or if
+ <prgn>build</prgn> has been invoked as root (since
+ <prgn>build</prgn> may create directories, for
+ example).
+ </p>
+ </item>
+
+ <tag><tt>get-orig-source</tt> (optional)</tag>
+ <item>
+
+ <p>
+ This target fetches the most recent version of the
+ original source package from a canonical archive site
+ (via FTP or WWW, for example), does any necessary
+ rearrangement to turn it into the original source
+ tar file format described below, and leaves it in the
+ current directory.
+ </p>
+
+ <p>
+ This target may be invoked in any directory, and
+ should take care to clean up any temporary files it
+ may have left.
+ </p>
+
+ <p>
+ This target is optional, but providing it if
+ possible is a good idea.
+ </p>
+ </item>
+ </taglist>
+
+ <p>
+ The <prgn>build</prgn>, <prgn>binary</prgn> and
+ <prgn>clean</prgn> targets must be invoked with the current
+ directory being the package's top-level directory.
+ </p>
+
+
+ <p>
+ Additional targets may exist in <tt>debian/rules</tt>,
+ either as published or undocumented interfaces or for the
+ package's internal use.
+ </p>
+
+ <p>
+ The architectures we build on and build for are determined
+ by <prgn>make</prgn> variables using the utility
+ <prgn>dpkg-architecture</prgn>. 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 <prgn>make</prgn> variables:
+ <list compact="compact">
+ <item>
+ <p><tt>DEB_*_ARCH</tt> (the Debian architecture)</p>
+ </item>
+ <item>
+ <p><tt>DEB_*_GNU_TYPE</tt> (the GNU style architecture
+ specification string)</p>
+ </item>
+ <item>
+ <p><tt>DEB_*_GNU_CPU</tt> (the CPU part of
+ <tt>DEB_*_GNU_TYPE</tt>)</p>
+ </item>
+ <item>
+ <p><tt>DEB_*_GNU_SYSTEM</tt> (the System part of
+ <tt>DEB_*_GNU_TYPE</tt>)</p>
+ </list>
+ where <tt>*</tt> is either <tt>BUILD</tt> for specification of
+ the build machine or <tt>HOST</tt> for specification of the
+ host machine.
+ </p>
+
+ <p>
+ Backward compatibility can be provided in the rules file
+ by setting the needed variables to suitable default
+ values; please refer to the documentation of
+ <prgn>dpkg-architecture</prgn> for details.
+ </p>
+
+ <p>
+ It is important to understand that the <tt>DEB_*_ARCH</tt>
+ 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.
+ </p>
+ </sect>
+
+ <sect id="dpkgchangelog"><heading><tt>debian/changelog</tt>
+ </heading>
+
+ <p>
+ This file records the changes to the Debian-specific parts of the
+ package
+ <footnote>
+ <p>
+ Though there is nothing stopping an author who is also
+ the Debian maintainer from using it for all their
+ changes, it will have to be renamed if the Debian and
+ upstream maintainers become different people. In such a
+ case, however, it might be better to maintain the
+ package as a non-native package.
+ </p>
+ </footnote>.
+ </p>
+
+ <p>
+ 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.
+ </p>
+
+ <p>
+ That format is a series of entries like this:
+ <example>
+<var>package</var> (<var>version</var>) <var>distribution(s)</var>; urgency=<var>urgency</var>
+
+ * <var>change details</var>
+ <var>more change details</var>
+ * <var>even more change details</var>
+
+ -- <var>maintainer name and email address</var> <var>date</var>
+ </example>
+ </p>
+
+ <p>
+ <var>package</var> and <var>version</var> are the source
+ package name and version number.
+ </p>
+
+ <p>
+ <var>distribution(s)</var> lists the distributions where
+ this version should be installed when it is uploaded - it
+ is copied to the <tt>Distribution</tt> field in the
+ <tt>.changes</tt> file. See <ref id="f-Distribution">.
+ </p>
+
+ <p>
+ <var>urgency</var> is the value for the <tt>Urgency</tt>
+ field in the <tt>.changes</tt> file for the upload. It is
+ not possible to specify an urgency containing commas; commas
+ are used to separate
+ <tt><var>keyword</var>=<var>value</var></tt> settings in the
+ <prgn>dpkg</prgn> changelog format (though there is
+ currently only one useful <var>keyword</var>,
+ <tt>urgency</tt>).
+ <footnote>
+ <p>
+ Usual urgency values are <tt>low</tt>, <tt>medium</tt>,
+ <tt>high</tt> and <tt>critical</tt>. They have an
+ effect on how quickly a package will be considered for
+ inclusion into the <tt>testing</tt> distribution, and
+ give an indication of the importance of any fixes
+ included in this upload.
+ </p>
+ </footnote>
+ </p>
+
+ <p>
+ 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.
+ </p>
+
+ <p>
+ 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: <tt>closes: Bug#<var>nnnnn</var></tt>
+ in the change details.
+ <footnote>
+ <p>
+ To be precise, the string should match the following
+ Perl regular expression (where $pound=<tt>#</tt>;):
+ <example>
+/closes:\s*(?:bug)?${pound}?\s?\d+(?:,\s*(?:bug)?\${pound}?\s?\d+)*/i
+ </example>
+ <footnote>
+ <p>We had to introduce the $pound variable in the
+ regexp above because otherwise the utilities
+ rendering the policy documents gor confused by a
+ backslashed "#" symbol.
+ </p>
+ </footnote>
+ Then all of the bug numbers listed will be closed by the
+ archive maintenance script (<prgn>katie</prgn>), or in
+ the case of an NMU, marked as fixed.
+ </p>
+ </footnote>
+ </p>
+
+ <p>
+ The maintainer name and email address used in the changelog
+ should be the details of the person uploading <em>this</em>
+ version. They are <em>not</em> necessarily those of the
+ usual package maintainer. The information here will be
+ copied to the <tt>Changed-By</tt> field in the
+ <tt>.changes</tt> file, and then later used to send an
+ acknowledgement when the upload has been installed.
+ </p>
+
+ <p>
+ The <var>date</var> should be in RFC822 format
+ <footnote>
+ <p>
+ This is generated by the <prgn>822-date</prgn>
+ program.
+ </p>
+ </footnote>; it should include the time zone specified
+ numerically, with the time zone name or abbreviation
+ optionally present as a comment in parentheses.
+ </p>
+
+ <p>
+ 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.
+ </p>
+
+ <sect1><heading>Defining alternative changelog formats</heading>
+
+ <p>
+ It is possible to use a different format to the standard
+ one, by providing a parser for the format you wish to
+ use.
+ </p>
+ <p>
+ A changelog parser must not interact with the user at
+ all.
+ </p>
+ </sect1>
+ </sect>
+
+ <sect id="srcsubstvars"><heading><tt>debian/substvars</tt>
+ and variable substitutions </heading>
+
+ <p>
+ When <prgn>dpkg-gencontrol</prgn>,
+ <prgn>dpkg-genchanges</prgn> and <prgn>dpkg-source</prgn>
+ generate control files they perform variable substitutions
+ on their output just before writing it. Variable
+ substitutions have the form
+ <tt>${<var>variable-name</var>}</tt>. The optional file
+ <tt>debian/substvars</tt> contains variable substitutions to
+ be used; variables can also be set directly from
+ <tt>debian/rules</tt> using the <tt>-V</tt> option to the
+ source packaging commands, and certain predefined variables
+ are also available.
+ </p>
+
+ <p>
+ The <tt>debian/substvars</tt> file is usually generated and
+ modified dynamically by <tt>debian/rules</tt> targets; in
+ this case it must be removed by the <prgn>clean</prgn>
+ target.
+ </p>
+
+ <p>
+ See <manref name="dpkg-source" section="1"> for full
+ details about source variable substitutions, including the
+ format of <tt>debian/substvars</tt>.</p>
+ </sect>
+
+ <sect id="debianfiles"><heading><tt>debian/files</tt>
+ </heading>
+
+ <p>
+ This file is not a permanent part of the source tree; it
+ is used while building packages to record which files are
+ being generated. <prgn>dpkg-genchanges</prgn> uses it
+ when it generates a <tt>.changes</tt> file.
+ </p>
+
+ <p>
+ It should not exist in a shipped source package, and so it
+ (and any backup files or temporary files such as
+ <tt>files.new</tt>
+ <footnote>
+ <p>
+ <tt>files.new</tt> is used as a temporary file by
+ <prgn>dpkg-gencontrol</prgn> and
+ <prgn>dpkg-distaddfile</prgn> - they write a new
+ version of <tt>files</tt> here before renaming it,
+ to avoid leaving a corrupted copy if an error
+ occurs
+ </p>
+ </footnote>) should be removed by the
+ <prgn>clean</prgn> target. It may also be wise to
+ ensure a fresh start by emptying or removing it at the
+ start of the <prgn>binary</prgn> target.
+ </p>
+
+ <p>
+ When <prgn>dpkg-gencontrol</prgn> is run for a binary
+ package, it adds an entry to <tt>debian/files</tt> for the
+ <tt>.deb</tt> file that will be created when <prgn>dpkg-deb
+ --build</prgn> 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 <prgn>clean</prgn> target.
+ </p>
+
+ <p>
+ If a package upload includes files besides the source
+ package and any binary packages whose control files were
+ made with <prgn>dpkg-gencontrol</prgn> then they should be
+ placed in the parent of the package's top-level directory
+ and <prgn>dpkg-distaddfile</prgn> should be called to add
+ the file to the list in <tt>debian/files</tt>.</p>
+ </sect>
+
+ <sect id="restrictions"><heading>Restrictions on objects in source packages
+ </heading>
+
+ <p>
+ The source package may not contain any hard links
+ <footnote>
+ <p>
+ This is not currently detected when building source
+ packages, but only when extracting
+ them.
+ </p>
+ <p>
+ Hard links may be permitted at some point in the
+ future, but would require a fair amount of
+ work.
+ </p>
+ </footnote>, device special files, sockets or setuid or
+ setgid files.
+ <footnote>
+ <p>
+ Setgid directories are allowed.
+ </p>
+ </footnote>
+ </p>
+ </sect>
+ <sect id="descriptions"><heading>Descriptions of packages - the
+ <tt>Description</tt> field </heading>
+
+ <p>
+ 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.
+ </p>
+
+ <sect1><heading>Notes about writing descriptions
+ </heading>
+
+ <p>
+ The single line synopsis should be kept brief - certainly
+ under 80 characters.
+ </p>
+
+ <p>
+ 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.
+ </p>
+
+ <p>
+ 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.
+ </p>
+
+ <p>
+ 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).
+ </p>
+
+ <p>
+ The description field needs to make sense to anyone, even
+ people who have no idea about any of the things the
+ package deals with.
+ <footnote>
+ <p>
+ The blurb that comes with a program in its
+ announcements and/or <prgn>README</prgn> files is
+ rarely suitable for use in a description. It is
+ usually aimed at people who are already in the
+ community where the package is used.
+ </p>
+ </footnote>
+ </p>
+
+ <p>
+ 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.
+ </p>
+
+ <p>
+ You may include information about dependencies and so forth
+ in the extended description, if you wish.
+ </p>
+
+ <p>
+ Do not use tab characters. Their effect is not predictable.
+ </p>
+
+ </sect1>
+ </sect>
+ </chapt>
+
+
+ <chapt id="maintainerscripts"><heading>Package maintainer scripts
+ and installation procedure
+ </heading>
+
+ <sect><heading>Introduction to package maintainer scripts
+ </heading>
+
+ <p>
+ It is possible to supply scripts as part of a package which
+ the package management system will run for you when your
+ package is installed, upgraded or removed.
+ </p>
+
+ <p>
+ These scripts are the files <tt>preinst</tt>,
+ <tt>postinst</tt>, <tt>prerm</tt> and <tt>postrm</tt> in the
+ control area of the package. They must be proper executable
+ files; if they are scripts (which is recommended), they must
+ start with the usual <tt>#!</tt> convention. They should be
+ readable and executable by anyone, and not world-writable.
+ </p>
+
+ <p>
+ The package management system looks at the exit status from
+ these scripts. It is important that they exit with a
+ non-zero status if there is an error, so that the package
+ management system can stop its processing. For shell
+ scripts this means that you <em>almost always</em> need to
+ use <tt>set -e</tt> (this is usually true when writing shell
+ scripts, in fact). It is also important, of course, that
+ they don't exit with a non-zero status if everything went
+ well.
+ </p>
+
+ <p>
+ When a package is upgraded a combination of the scripts from
+ the old and new packages is called during the upgrade
+ procedure. If your scripts are going to be at all
+ complicated you need to be aware of this, and may need to
+ check the arguments to your scripts.
+ </p>
+
+ <p>
+ Broadly speaking the <prgn>preinst</prgn> is called before
+ (a particular version of) a package is installed, and the
+ <prgn>postinst</prgn> afterwards; the <prgn>prerm</prgn>
+ before (a version of) a package is removed and the
+ <prgn>postrm</prgn> afterwards.
+ </p>
+
+ <p>
+ Programs called from maintainer scripts should not normally
+ have a path prepended to them. Before installation is
+ started, the package management system checks to see if the
+ programs <prgn>ldconfig</prgn>,
+ <prgn>start-stop-daemon</prgn>, <prgn>install-info</prgn>,
+ and <prgn>update-rc.d</prgn> can be found via the
+ <tt>PATH</tt> environment variable. Those programs, and any
+ other program that one would expect to be on the
+ <tt>PATH</tt>, should thus be invoked without an absolute
+ pathname. Maintainer scripts should also not reset the
+ <tt>PATH</tt>, though they might choose to modify it by
+ prepending or appending package-specific directories. These
+ considerations really apply to all shell scripts.</p>
+ </sect>
+
+ <sect>
+ <heading>Maintainer scripts Idempotency</heading>
+
+ <p>
+ It is necessary for the error recovery procedures that the
+ scripts be idempotent. This means that if it is run
+ successfully, and then it is called again, it doesn't bomb
+ out or cause any harm, but just ensures that everything is
+ the way it ought to be. If the first call failed, or
+ aborted half way through for some reason, the second call
+ should merely do the things that were left undone the first
+ time, if any, and exit with a success status if everything
+ is OK.
+ <footnote>
+ <p>
+ This is so that if an error occurs, the user interrupts
+ <prgn>dpkg</prgn> or some other unforeseen circumstance
+ happens you don't leave the user with a badly-broken
+ package when <prgn>dpkg</prgn> attempts to repeat the
+ action.
+ </p>
+ </footnote>
+ </p>
+ </sect>
+
+ <sect>
+ <heading>Controlling terminal for maintainer scripts</heading>
+
+ <p>
+ The maintainer scripts are guaranteed to run with a
+ controlling terminal and can interact with the user.
+ If they need to prompt for passwords, do full-screen
+ interaction or something similar you should do these
+ things to and from <tt>/dev/tty</tt>, since
+ <prgn>dpkg</prgn> will at some point redirect scripts'
+ standard input and output so that it can log the
+ installation process. Likewise, because these scripts
+ may be executed with standard output redirected into a
+ pipe for logging purposes, Perl scripts should set
+ unbuffered output by setting <tt>$|=1</tt> so that the
+ output is printed immediately rather than being
+ buffered.
+ </p>
+
+ <p>
+ Each script should return a zero exit status for
+ success, or a nonzero one for failure.
+ </p>
+ </sect>
+
+ <sect id="mscriptsinstact"><heading>Summary of ways maintainer
+ scripts are called
+ </heading>
+
+ <p>
+ <list compact="compact">
+ <item>
+ <p><var>new-preinst</var> <tt>install</tt></p>
+ </item>
+ <item>
+ <p><var>new-preinst</var> <tt>install</tt>
+ <var>old-version</var></p>
+ </item>
+ <item>
+ <p><var>new-preinst</var> <tt>upgrade</tt>
+ <var>old-version</var></p>
+ </item>
+ <item>
+ <p><var>old-preinst</var> <tt>abort-upgrade</tt>
+ <var>new-version</var>
+ </p>
+ </item>
+ </list>
+
+ <p>
+ <list compact="compact">
+ <item>
+ <p><var>postinst</var> <tt>configure</tt>
+ <var>most-recently-configured-version</var></p>
+ </item>
+ <item>
+ <p><var>old-postinst</var> <tt>abort-upgrade</tt>
+ <var>new-version</var></p>
+ </item>
+ <item>
+ <p><var>conflictor's-postinst</var> <tt>abort-remove</tt>
+ <tt>in-favour</tt> <var>package</var>
+ <var>new-version</var></p>
+ </item>
+ <item>
+ <p>
+ <var>deconfigured's-postinst</var>
+ <tt>abort-deconfigure</tt> <tt>in-favour</tt>
+ <var>failed-install-package</var> <var>version</var>
+ <tt>removing</tt> <var>conflicting-package</var>
+ <var>version</var>
+ </p>
+ </item>
+ </list>
+
+ <p>
+ <list compact="compact">
+ <item>
+ <p><var>prerm</var> <tt>remove</tt></p>
+ </item>
+ <item>
+ <p><var>old-prerm</var> <tt>upgrade</tt>
+ <var>new-version</var></p>
+ </item>
+ <item>
+ <p><var>new-prerm</var> <tt>failed-upgrade</tt>
+ <var>old-version</var></p>
+ </item>
+ <item>
+ <p><var>conflictor's-prerm</var> <tt>remove</tt>
+ <tt>in-favour</tt> <var>package</var>
+ <var>new-version</var></p>
+ </item>
+ <item>
+ <p>
+ <var>deconfigured's-prerm</var> <tt>deconfigure</tt>
+ <tt>in-favour</tt> <var>package-being-installed</var>
+ <var>version</var> <tt>removing</tt>
+ <var>conflicting-package</var>
+ <var>version</var>
+ </p>
+ </item>
+ </list>
+
+ <p>
+ <list compact="compact">
+ <item>
+ <p><var>postrm</var> <tt>remove</tt></p>
+ </item>
+ <item>
+ <p><var>postrm</var> <tt>purge</tt></p>
+ </item>
+ <item>
+ <p>
+ <var>old-postrm</var> <tt>upgrade</tt>
+ <var>new-version</var></p>
+ </item>
+ <item>
+ <p><var>new-postrm</var> <tt>failed-upgrade</tt>
+ <var>old-version</var></p>
+ </item>
+ <item>
+ <p><var>new-postrm</var> <tt>abort-install</tt></p>
+ </item>
+ <item>
+ <p><var>new-postrm</var> <tt>abort-install</tt>
+ <var>old-version</var></p>
+ </item>
+ <item>
+ <p><var>new-postrm</var> <tt>abort-upgrade</tt>
+ <var>old-version</var></p>
+ </item>
+ <item>
+ <p>
+ <var>disappearer's-postrm</var> <tt>disappear</tt>
+ <var>overwriter</var>
+ <var>overwriter-version</var></p></item>
+ </list>
+ </p>
+
+
+ <sect id="unpackphase"><heading>Details of unpack phase of
+ installation or upgrade
+ </heading>
+
+ <p>
+ The procedure on installation/upgrade/overwrite/disappear
+ (i.e., when running <tt>dpkg --unpack</tt>, or the unpack
+ stage of <tt>dpkg --install</tt>) is as follows. In each
+ case, if a major error occurs (unless listed below) the
+ actions are, in general, run backwards - this means that the
+ maintainer scripts are run with different arguments in
+ reverse order. These are the `error unwind' calls listed
+ below.
+
+ <enumlist>
+ <item>
+ <p>
+ <enumlist>
+ <item>
+ <p>If a version of the package is already
+ installed, call
+ <example>
+ <var>old-prerm</var> upgrade <var>new-version</var>
+ </example></p>
+ </item>
+ <item>
+ <p>
+ If the script runs but exits with a non-zero
+ exit status, <prgn>dpkg</prgn> will attempt:
+ <example>
+ <var>new-prerm</var> failed-upgrade <var>old-version</var>
+ </example>
+ Error unwind, for both the above cases:
+ <example>
+ <var>old-postinst</var> abort-upgrade <var>new-version</var>
+ </example>
+ </p>
+ </item>
+ </enumlist>
+ </p>
+ </item>
+ <item>
+ <p>If a `conflicting' package is being removed at the same time:
+ <enumlist>
+ <item>
+ <p>
+ If any packages depended on that conflicting
+ package and <tt>--auto-deconfigure</tt> is
+ specified, call, for each such package:
+ <example>
+ <var>deconfigured's-prerm</var> deconfigure \
+ in-favour <var>package-being-installed</var> <var>version</var> \
+ removing <var>conflicting-package</var> <var>version</var>
+ </example>
+ Error unwind:
+ <example>
+ <var>deconfigured's-postinst</var> abort-deconfigure \
+ in-favour <var>package-being-installed-but-failed</var> <var>version</var> \
+ removing <var>conflicting-package</var> <var>version</var>
+ </example>
+ The deconfigured packages are marked as
+ requiring configuration, so that if
+ <tt>--install</tt> is used they will be
+ configured again if possible.</p>
+ </item>
+ <item>
+ <p>To prepare for removal of the conflicting package, call:
+ <example>
+ <var>conflictor's-prerm</var> remove in-favour <var>package</var> <var>new-version</var>
+ </example>
+ Error unwind:
+ <example>
+ <var>conflictor's-postinst</var> abort-remove \
+ in-favour <var>package</var> <var>new-version</var>
+ </example>
+ </p>
+ </item>
+ </enumlist>
+ </p>
+ </item>
+ <item>
+ <p>
+ <enumlist>
+ <item>
+ <p>If the package is being upgraded, call:
+ <example>
+ <var>new-preinst</var> upgrade <var>old-version</var>
+ </example></p>
+ </item>
+ <item>
+ <p>
+ Otherwise, if the package had some configuration
+ files from a previous version installed (i.e., it
+ is in the `configuration files only' state):
+ <example>
+ <var>new-preinst</var> install <var>old-version</var>
+ </example></p>
+
+ <item>
+ <p>Otherwise (i.e., the package was completely purged):
+ <example>
+ <var>new-preinst</var> install
+ </example>
+ Error unwind actions, respectively:
+ <example>
+ <var>new-postrm</var> abort-upgrade <var>old-version</var>
+ <var>new-postrm</var> abort-install <var>old-version</var>
+ <var>new-postrm</var> abort-install
+ </example>
+ </p>
+ </item>
+ </enumlist>
+ </p>
+ </item>
+ <item>
+
+ <p>
+ The new package's files are unpacked, overwriting any
+ that may be on the system already, for example any
+ from the old version of the same package or from
+ another package. Backups of the old files are kept
+ temporarily, and if anything goes wrong the package
+ management system will attempt to put them back as
+ part of the error unwind.
+ </p>
+
+ <p>
+ It is an error for a package to contains files which
+ are on the system in another package, unless
+ <tt>Replaces</tt> is used (see <ref id="replaces">).
+ <!--
+ The following paragraph is not currently the case:
+ Currently the <tt>- - force-overwrite</tt> flag is
+ enabled, downgrading it to a warning, but this may not
+ always be the case.
+ -->
+ </p>
+
+ <p>
+ It is a more serious error for a package to contain a
+ plain file or other kind of non-directory where another
+ package has a directory (again, unless
+ <tt>Replaces</tt> is used). This error can be
+ overridden if desired using
+ <tt>--force-overwrite-dir</tt>, but this is not
+ advisable.
+ </p>
+
+ <p>
+ Packages which overwrite each other's files produce
+ behavior which, though deterministic, is hard for the
+ system administrator to understand. It can easily
+ lead to `missing' programs if, for example, a package
+ is installed which overwrites a file from another
+ package, and is then removed again.
+ <footnote>
+ <p>
+ Part of the problem is due to what is arguably a
+ bug in <prgn>dpkg</prgn>.
+ </p>
+ </footnote>
+ </p>
+
+ <p>
+ A directory will never be replaced by a symbolic link
+ to a directory or vice versa; instead, the existing
+ state (symlink or not) will be left alone and
+ <prgn>dpkg</prgn> will follow the symlink if there is
+ one.</p>
+ </item>
+
+ <item>
+
+ <p><enumlist>
+ <item>
+ <p>If the package is being upgraded, call
+ <example>
+ <var>old-postrm</var> upgrade <var>new-version</var>
+ </example></p>
+ </item>
+ <item>
+ <p>If this fails, <prgn>dpkg</prgn> will attempt:
+ <example>
+ <var>new-postrm</var> failed-upgrade <var>old-version</var>
+ </example>
+ Error unwind, for both cases:
+ <example>
+ <var>old-preinst</var> abort-upgrade <var>new-version</var>
+ </example>
+ </p>
+ </item>
+ </enumlist>
+ <p>
+ This is the point of no return - if
+ <prgn>dpkg</prgn> gets this far, it won't back off
+ past this point if an error occurs. This will
+ leave the package in a fairly bad state, which
+ will require a successful re-installation to clear
+ up, but it's when <prgn>dpkg</prgn> starts doing
+ things that are irreversible.
+ </p>
+ </item>
+ <item>
+ <p>
+ Any files which were in the old version of the package
+ but not in the new are removed.</p>
+ </item>
+ <item>
+ <p>The new file list replaces the old.</p>
+ </item>
+ <item>
+ <p>The new maintainer scripts replace the old.</p>
+ </item>
+
+ <item>
+ <p>Any packages all of whose files have been overwritten during the
+ installation, and which aren't required for
+ dependencies, are considered to have been removed.
+ For each such package
+ <enumlist>
+ <item>
+ <p><prgn>dpkg</prgn> calls:
+ <example>
+ <var>disappearer's-postrm</var> disappear \
+ <var>overwriter</var> <var>overwriter-version</var>
+ </example>
+ </p>
+ </item>
+ <item>
+ <p>The package's maintainer scripts are removed.
+ </p>
+ </item>
+ <item>
+ <p>
+ It is noted in the status database as being in a
+ sane state, namely not installed (any conffiles
+ it may have are ignored, rather than being
+ removed by <prgn>dpkg</prgn>). Note that
+ disappearing packages do not have their prerm
+ called, because <prgn>dpkg</prgn> doesn't know
+ in advance that the package is going to
+ vanish.
+ </p>
+ </item>
+ </enumlist>
+ </p>
+ </item>
+ <item>
+ <p>
+ Any files in the package we're unpacking that are also
+ listed in the file lists of other packages are removed
+ from those lists. (This will lobotomize the file list
+ of the `conflicting' package if there is one.)
+ </p>
+ </item>
+ <item>
+ <p>
+ The backup files made during installation, above, are
+ deleted.
+ </p>
+ </item>
+
+ <item>
+ <p>
+ The new package's status is now sane, and recorded as
+ `unpacked'.
+ </p>
+
+ <p>
+ Here is another point of no return - if the
+ conflicting package's removal fails we do not unwind
+ the rest of the installation; the conflicting package
+ is left in a half-removed limbo.
+ </p>
+ </item>
+
+ <item>
+ <p>
+ If there was a conflicting package we go and do the
+ removal actions (described below), starting with the
+ removal of the conflicting package's files (any that
+ are also in the package being installed have already
+ been removed from the conflicting package's file list,
+ and so do not get removed now).
+ </p>
+ </item>
+ </enumlist>
+ </p>
+ </sect>
+
+ <sect><heading>Details of configuration</heading>
+
+ <p>
+ When we configure a package (this happens with <tt>dpkg
+ --install</tt>, or with <tt>--configure</tt>), we first
+ update any <tt>conffile</tt>s and then call:
+ <example>
+ <var>postinst</var> configure <var>most-recently-configured-version</var>
+ </example>
+ </p>
+
+ <p>
+ No attempt is made to unwind after errors during
+ configuration.
+ </p>
+
+ <p>
+ If there is no most recently configured version
+ <prgn>dpkg</prgn> will pass a null argument; older versions
+ of dpkg may pass <tt><unknown></tt> (including the
+ angle brackets) in this case. Even older ones do not pass a
+ second argument at all, under any circumstances.
+ </p>
+ </sect>
+
+ <sect><heading>Details of removal and/or configuration purging
+ </heading>
+
+ <p>
+ <enumlist>
+ <item>
+ <p>
+ <example>
+ <var>prerm</var> remove
+ </example>
+ </p>
+ </item>
+ <item>
+ <p>
+ The package's files are removed (except <tt>conffile</tt>s).
+ </p>
+ </item>
+ <item>
+ <p><example>
+ <var>postrm</var> remove
+ </example></p>
+ </item>
+ <item>
+ <p>
+ All the maintainer scripts except the <tt>postrm</tt>
+ are removed.
+ </p>
+
+ <p>
+ If we aren't purging the package we stop here. Note
+ that packages which have no <tt>postrm</tt> and no
+ <tt>conffile</tt>s are automatically purged when
+ removed, as there is no difference except for the
+ <prgn>dpkg</prgn> status.</p>
+ </item>
+ <item>
+ <p>
+ The conffiles and any backup files (<tt>~</tt>-files,
+ <tt>#*#</tt> files, <tt>%</tt>-files,
+ <tt>.dpkg-{old,new,tmp}</tt>, etc.) are removed.</p>
+ </item>
+ <item>
+ <p><example>
+ <var>postrm</var> purge
+ </example></p>
+ </item>
+ <item>
+ <p>The package's file list is removed.</p>
+ </item>
+ </enumlist>
+ No attempt is made to unwind after errors during
+ removal.
+ </p>
+ </sect>
+ </chapt>
+
+
+ <chapt id="relationships"><heading>Declaring relationships between
+ packages </heading>
+
+ <p>
+ Packages can declare in their control file that they have
+ certain relationships to other packages - for example, that
+ they may not be installed at the same time as certain other
+ packages, and/or that they depend on the presence of others,
+ or that they should overwrite files in certain other packages
+ if present.
+ </p>
+
+ <p>
+ This is done using the <tt>Depends</tt>, <tt>Recommends</tt>,
+ <tt>Suggests</tt>, <tt>Enhances</tt>, <tt>Conflicts</tt>,
+ <tt>Provides</tt> and <tt>Replaces</tt> control file fields.
+ </p>
+
+ <p>
+ Source packages may declare relationships to binary packages,
+ saying that they require certain binary packages to be
+ installed or absent at the time of building the package.
+ </p>
+
+ <p>
+ This is done using the <tt>Build-Depends</tt>,
+ <tt>Build-Depends-Indep</tt>, <tt>Build-Conflicts</tt>, and
+ <tt>Build-Conflicts-Indep</tt> control file fields.
+ </p>
+
+ <sect id="depsyntax"><heading>Syntax of relationship fields
+ </heading>
+
+ <p>
+ These fields all have a uniform syntax. They are a list of
+ package names separated by commas.
+ </p>
+
+ <p>
+ In the <tt>Depends</tt>, <tt>Recommends</tt>,
+ <tt>Suggests</tt>, <tt>Pre-Depends</tt>,
+ <tt>Build-Depends</tt> and <tt>Build-Depends-Indep</tt>
+ control file fields of the package, which declare
+ dependencies on other packages, the package names listed may
+ also include lists of alternative package names, separated
+ by vertical bar symbols <tt>|</tt> (pipe symbols). In such
+ a case, the presence of any one of the alternative packages
+ is installed, that part of the dependency is considered to
+ be satisfied.
+ </p>
+
+ <p>
+ All the fields except <tt>Provides</tt> may restrict their
+ applicability to particular versions of each named package.
+ This is done in parentheses after each individual package
+ name; the parentheses should contain a relation from the
+ list below followed by a version number, in the format
+ described in <ref id="versions">.
+ </p>
+
+ <p>
+ The relations allowed are <tt><<</tt>, <tt><=</tt>,
+ <tt>=</tt>, <tt>>=</tt> and <tt>>></tt> for
+ strictly earlier, earlier or equal, exactly equal, later or
+ equal and strictly later, respectively. The forms
+ <tt><</tt> and <tt>></tt> were used to mean
+ earlier/later or equal, rather than strictly earlier/later,
+ so they should not appear in new packages (though
+ <prgn>dpkg</prgn> still supports them).
+ </p>
+
+ <p>
+ Whitespace may appear at any point in the version
+ specification, and must appear where it's necessary to
+ disambiguate; it is not otherwise significant. For
+ consistency and in case of future changes to
+ <prgn>dpkg</prgn> it is recommended that a single space be
+ used after a version relationship and before a version
+ number; it is usual also to put a single space after each
+ comma, on either side of each vertical bar, and before each
+ open parenthesis.
+ </p>
+
+ <p>
+ For example:
+ <example>
+ Package: metamail
+ Version: 2.7-3
+ Depends: libc5 (>= 5.2.18-4), mime-support, csh | tcsh
+ </example>
+ </p>
+
+ <p>
+ All fields that specify build-time relationships
+ (<tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
+ <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>)
+ may be restricted to a certain set of architectures. This
+ is done in brackets after each individual package name and
+ the optional version specification. The brackets enclose a
+ list of Debian architecture names separated by whitespace.
+ Exclamation marks may be prepended to each of the names.
+ (It is not permitted for some names to be prepended with
+ exclamation marks and others not.) If the current Debian
+ host architecture is not in this list and there are no
+ exclamation marks in the list, or it is in the list with a
+ prepended exclamation mark, the package name and the
+ associated version specification are ignored completely for
+ the purposes of defining the relationships.
+ </p>
+
+ <p>
+ For example:
+ <example>
+ Source: glibc
+ Build-Depends-Indep: texinfo
+ Build-Depends: kernel-headers-2.2.10 [!hurd-i386],
+ hurd-dev [hurd-i386], gnumach-dev [hurd-i386]
+ </example>
+ </p>
+ </sect>
+
+ <sect>
+ <heading>Binary Dependencies - <tt>Depends</tt>,
+ <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
+ <tt>Pre-Depends</tt>
+ </heading>
+
+ <p>
+ These five fields are used to declare a dependency
+ relationship by one package on another. They appear in the
+ depending package's control file.
+ </p>
+
+ <p>
+ All but <tt>Pre-Depends</tt> and <tt>Conflicts</tt>
+ (discussed below) take effect <em>only</em> when a package
+ is to be configured. They do not prevent a package being on
+ the system in an unconfigured state while its dependencies
+ are unsatisfied, and it is possible to replace a package
+ whose dependencies are satisfied and which is properly
+ installed with a different version whose dependencies are
+ not and cannot be satisfied; when this is done the depending
+ package will be left unconfigured (since attempts to
+ configure it will give errors) and will not function
+ properly.
+ </p>
+
+ <p>
+ For this reason packages in an installation run are usually
+ all unpacked first and all configured later; this gives
+ later versions of packages with dependencies on later
+ versions of other packages the opportunity to have their
+ dependencies satisfied.
+ </p>
+
+ <p>
+ Thus <tt>Depends</tt> allows package maintainers to impose
+ an order in which packages should be configured.
+ <taglist>
+ <tag><tt>Depends</tt></tag>
+ <item>
+
+ <p>This declares an absolute dependency.
+ </p>
+
+ <p>
+ The <tt>Depends</tt> field should be used if the
+ depended-on package is required for the depending
+ package to provide a significant amount of
+ functionality.</p>
+ </item>
+
+ <tag><tt>Recommends</tt></tag>
+ <item>
+ <p>This declares a strong, but not absolute, dependency.
+ </p>
+
+ <p>
+ The <tt>Recommends</tt> field should list packages
+ that would be found together with this one in all but
+ unusual installations.</p>
+ </item>
+
+ <tag><tt>Suggests</tt></tag>
+ <item>
+
+ <p>
+ This is used to declare that one package may be more
+ useful with one or more others. Using this field
+ tells the packaging system and the user that the
+ listed packages are related to this one and can
+ perhaps enhance its usefulness, but that installing
+ this one without them is perfectly reasonable.
+ </p>
+ </item>
+
+ <tag><tt>Enhances</tt></tag>
+ <item>
+ <p>
+ This field is similar to Suggests but works in the
+ opposite direction. It is used to declare that a
+ package can enhance the functionality of another
+ package.
+ </p>
+ </item>
+
+ <tag><tt>Pre-Depends</tt></tag>
+ <item>
+
+ <p>
+ This field is like <tt>Depends</tt>, except that it
+ also forces <prgn>dpkg</prgn> to complete installation
+ of the packages named before even starting the
+ installation of the package which declares the
+ Pre-dependency.
+ </p>
+
+ <p>
+ <tt>Pre-Depends</tt> should be used sparingly,
+ preferably only by packages whose premature upgrade or
+ installation would hamper the ability of the system to
+ continue with any upgrade that might be in progress.
+ </p>
+
+ <p>
+ When the package declaring it is being configured, a
+ <tt>Pre-Dependency</tt> will be considered satisfied
+ only if the depending package has been correctly
+ configured, just as if an ordinary <tt>Depends</tt>
+ had been used.
+ </p>
+
+ <p>
+ However, when a package declaring a Pre-dependency is
+ being unpacked the predependency can be satisfied even
+ if the depended-on package(s) are only unpacked or
+ half-configured, provided that they have been
+ configured correctly at some point in the past (and
+ not removed or partially removed since). In this case
+ both the previously-configured and currently unpacked
+ or half-configured versions must satisfy any version
+ clause in the <tt>Pre-Depends</tt> field.
+ </p>
+ </item>
+ </taglist>
+ </p>
+ <p>
+ When selecting which level of dependency to use you should
+ consider how important the depended-on package is to the
+ functionality of the one declaring the dependency. Some
+ packages are composed of components of varying degrees of
+ importance. Such a package should list using
+ <tt>Depends</tt> the package(s) which are required by the
+ more important components. The other components'
+ requirements may be mentioned as Suggestions or
+ Recommendations, as appropriate to the components' relative
+ importance.
+ </p>
+
+
+ <sect id="conflicts"><heading>Alternative binary packages -
+ <tt>Conflicts</tt> and <tt>Replaces</tt>
+ </heading>
+
+ <p>
+ When one binary package declares a conflict with another
+ <prgn>dpkg</prgn> will refuse to allow them to be installed
+ on the system at the same time.
+ </p>
+
+ <p>
+ If one package is to be installed, the other must be removed
+ first - if the package being installed is marked as
+ replacing (<ref id="replaces">) the one on the system, or
+ the one on the system is marked as deselected, or both
+ packages are marked <tt>Essential</tt>, then
+ <prgn>dpkg</prgn> will automatically remove the package
+ which is causing the conflict, otherwise it will halt the
+ installation of the new package with an error. This
+ mechanism specifically doesn't work when the installed
+ package is <tt>Essential</tt>, but the new package is not.
+ </p>
+
+
+ <p>
+ A package will not cause a conflict merely because its
+ configuration files are still installed; it must be at least
+ half-installed.
+ </p>
+
+ <p>
+ A special exception is made for packages which declare a
+ conflict with their own package name, or with a virtual
+ package which they provide (see below): this does not
+ prevent their installation, and allows a package to conflict
+ with others providing a replacement for it. You use this
+ feature when you want the package in question to be the only
+ package providing something.
+ </p>
+
+ <p>
+ A <tt>Conflicts</tt> entry should almost never have an
+ `earlier than' version clause. This would prevent
+ <prgn>dpkg</prgn> from upgrading or installing the package
+ which declared such a conflict until the upgrade or removal
+ of the conflicted-with package had been completed.
+ </p>
+ </sect>
+
+ <sect id="virtual"><heading>Virtual packages - <tt>Provides</tt>
+ </heading>
+
+ <p>
+ As well as the names of actual (`concrete') packages, the
+ package relationship fields <tt>Depends</tt>,
+ <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
+ <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Conflicts</tt>,
+ <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt> may
+ mention virtual packages.
+ </p>
+
+ <p>
+ A virtual package is one which appears in the
+ <tt>Provides</tt> control file field of another package.
+ The effect is as if the package(s) which provide a
+ particular virtual package name had been listed by name
+ everywhere the virtual package name appears.
+ </p>
+
+ <p>
+ If there are both a real and a virtual package of the same
+ name then the dependency may be satisfied (or the conflict
+ caused) by either the real package or any of the virtual
+ packages which provide it. This is so that, for example,
+ supposing we have
+ <example>
+ Package: vm
+ Depends: emacs
+ </example>
+ and someone else releases an xemacs package they can say
+ <example>
+ Package: xemacs
+ Provides: emacs
+ </example> and all will work in the interim (until a purely
+ virtual package name is decided on and the <tt>emacs</tt>
+ and <tt>vm</tt> packages are changed to use it).
+ </p>
+
+ <p>
+ If a dependency or a conflict has a version number attached
+ then only real packages will be considered to see whether
+ the relationship is satisfied (or the prohibition violated,
+ for a conflict) - it is assumed that a real package which
+ provides the virtual package is not of the `right' version.
+ So, a <tt>Provides</tt> field may not contain version
+ numbers, and the version number of the concrete package
+ which provides a particular virtual package will not be
+ looked at when considering a dependency on or conflict with
+ the virtual package name.
+ </p>
+
+ <p>
+ It is likely that the ability will be added in a future
+ release of <prgn>dpkg</prgn> to specify a version number for
+ each virtual package it provides. This feature is not yet
+ present, however, and is expected to be used only
+ infrequently.
+ </p>
+
+ <p>
+ If you want to specify which of a set of real packages should be the
+ default to satisfy a particular dependency on a virtual package, you
+ should list the real package as an alternative before the virtual.
+ </p>
+ </sect>
+
+
+ <sect id="replaces"><heading><tt>Replaces</tt> - overwriting
+ files and replacing packages
+ </heading>
+
+ <p>
+ The <tt>Replaces</tt> control file field has two purposes,
+ which come into play in different situations.
+ </p>
+
+ <p>
+ Virtual packages (<ref id="virtual">) are not considered
+ when looking at a <tt>Replaces</tt> field - the packages
+ declared as being replaced must be mentioned by their real
+ names.
+ </p>
+
+ <sect1><heading>Overwriting files in other packages
+ </heading>
+
+ <p>
+ Firstly, as mentioned before, it is usually an error for a
+ package to contain files which are on the system in
+ another package, though currently the
+ <tt>--force-overwrite</tt> flag is enabled by default,
+ downgrading the error to a warning,
+ </p>
+
+ <p>
+ If the overwriting package declares that it replaces the
+ one containing the file being overwritten then
+ <prgn>dpkg</prgn> will proceed, and replace the file from
+ the old package with that from the new. The file will no
+ longer be listed as `owned' by the old package.
+ </p>
+
+ <p>
+ If a package is completely replaced in this way, so that
+ <prgn>dpkg</prgn> does not know of any files it still
+ contains, it is considered to have disappeared. It will
+ be marked as not wanted on the system (selected for
+ removal) and not installed. Any conffiles details noted
+ in the package will be ignored, as they will have been
+ taken over by the replacing package(s). The package's
+ <prgn>postrm</prgn> script will be run to allow the
+ package to do any final cleanup required. See <ref
+ id="mscriptsinstact">.
+ </p>
+
+ <p>
+ In the future <prgn>dpkg</prgn> will discard files which
+ would overwrite those from an already installed package
+ which declares that it replaces the package being
+ installed. This is so that you can install an older
+ version of a package without problems.
+ </p>
+
+ <p>
+ This usage of <tt>Replaces</tt> only takes effect when
+ both packages are at least partially on the system at
+ once, so that it can only happen if they do not conflict
+ or if the conflict has been overridden.</p>
+ </sect1>
+
+ <sect1><heading>Replacing whole packages, forcing their
+ removal
+ </heading>
+
+ <p>
+ Secondly, <tt>Replaces</tt> allows the packaging system to
+ resolve which package should be removed when there is a
+ conflict - see <ref id="conflicts">. This usage only
+ takes effect when the two packages <em>do</em> conflict,
+ so that the two effects do not interfere with each other.
+ </p>
+ </sect1>
+ </sect>
+
+ <sect><heading>Relationships between source and binary packages -
+ <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
+ <tt>Build-Conflicts</tt>, <tt>Build-Conflicts-Indep</tt>
+ </heading>
+
+ <p>
+ A source package may declare a dependency or a conflict on a
+ binary package. This is done with the control file fields
+ <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
+ <tt>Build-Conflicts</tt>, and
+ <tt>Build-Conflicts-Indep</tt>. Their semantics are that
+ the dependencies and conflicts they define must be satisfied
+ (as defined earlier for binary packages), when one of the
+ targets in <tt>debian/rules</tt> that the particular field
+ applies to is invoked.
+
+ <taglist>
+ <tag><tt>Build-Depends</tt>, <tt>Build-Conflicts</tt></tag>
+ <item>
+ <p>
+ The <tt>Build-Depends</tt> and
+ <tt>Build-Conflicts</tt> fields apply to the targets
+ <tt>build</tt>, <tt>binary</tt>, <tt>binary-arch</tt>
+ and <tt>binary-indep</tt>.
+ </p>
+ </item>
+ <tag><tt>Build-Depends-Indep</tt>, <tt>Build-Conflicts-Indep</tt></tag>
+ <item>
+ <p>
+ The <tt>Build-Depends-Indep</tt> and
+ <tt>Build-Conflicts-Indep</tt> fields apply to the
+ targets <tt>binary</tt> and <tt>binary-indep</tt>.
+ </p>
+ </item>
+ </taglist>
+
+ </p>
+
+ </sect>
+ </chapt>
+
+
+ <chapt id="conffiles"><heading>Configuration file handling
+ </heading>
+
+ <p>
+ <prgn>dpkg</prgn> can do a certain amount of automatic
+ handling of package configuration files.
+ </p>
+
+ <p>
+ Whether this mechanism is appropriate depends on a number of
+ factors, but basically there are two approaches to any
+ particular configuration file.
+ </p>
+
+ <p>
+ The easy method is to ship a best-effort configuration in the
+ package, and use <prgn>dpkg</prgn>'s conffile mechanism to
+ handle updates. If the user is unlikely to want to edit the
+ file, but you need them to be able to without losing their
+ changes, and a new package with a changed version of the file
+ is only released infrequently, this is a good approach.
+ </p>
+
+ <p>
+ The hard method is to build the configuration file from
+ scratch in the <prgn>postinst</prgn> script, and to take the
+ responsibility for fixing any mistakes made in earlier
+ versions of the package automatically. This will be
+ appropriate if the file is likely to need to be different on
+ each system.
+ </p>
+
+
+ <chapt id="sharedlibs"><heading>Shared libraries
+ </heading>
+
+ <p>
+ Packages containing shared libraries must be constructed with
+ a little care to make sure that the shared library is always
+ available. This is especially important for packages whose
+ shared libraries are vitally important, such as the libc.
+ </p>
+
+ <p>
+ Firstly, your package should install the shared libraries
+ under their normal names. For example, the
+ <prgn>libgdbm1</prgn> package should install
+ <tt>libgdbm.so.1.7.3</tt> as
+ <tt>/usr/lib/libgdbm.so.1.7.3</tt>. The files should not be
+ renamed or re-linked by any prerm or postrm scripts;
+ <prgn>dpkg</prgn> will take care of renaming things safely
+ without affecting running programs, and attempts to interfere
+ with this are likely to lead to problems.
+ </p>
+
+ <p>
+ Secondly, your package should include the symlink that
+ <prgn>ldconfig</prgn> would create for the shared libraries.
+ For example, the <prgn>libgdbm1</prgn> package should include
+ a symlink from <tt>/usr/lib/libgdbm.so.1</tt> to
+ <tt>libgdbm.so.1.7.3</tt>. This is needed so that
+ <prgn>ld.so</prgn> can find the library in between the time
+ <prgn>dpkg</prgn> installs it and <prgn>ldconfig</prgn> is run
+ in the <prgn>postinst</prgn> script. Furthermore, older
+ versions of the package management system required the library
+ must be placed before the symlink pointing to it in the
+ <tt>.deb</tt> file. This is so that by the time
+ <prgn>dpkg</prgn> comes to install the symlink (overwriting
+ the previous symlink pointing at an older version of the
+ library) the new shared library is already in place.
+ Unfortunately, this was not not always possible, since it
+ highly depends on the behavior of the file system. Some
+ file systems (such as reiserfs) will reorder the files so it
+ doesn't matter in what order you create them. Starting with
+ release <tt>1.7.0</tt> <prgn>dpkg</prgn> will reorder the
+ files itself when building a package.
+ </p>
+
+ <p>
+ Thirdly, the development package should contain a symlink for
+ the shared library without a version number. For example, the
+ <tt>libgdbm1-dev</tt> package should include a symlink from
+ <tt>/usr/lib/libgdm.so</tt> to <tt>libgdm.so.1.7.3</tt>. This
+ symlink is needed by <prgn>ld</prgn> when compiling packages
+ as it will only look for <tt>libgdm.so</tt> and
+ <tt>libgdm.a</tt> when compiling dynamically or statically,
+ respectively.
+ </p>
+
+ <p>
+ Any package installing shared libraries in a directory that's listed
+ in <tt>/etc/ld.so.conf</tt> or in one of the default library
+ directories of <prgn>ld.so</prgn> (currently, these are <tt>/usr/lib</tt>
+ and <tt>/lib</tt>) must call <prgn>ldconfig</prgn> in its <prgn>postinst</prgn>
+ script if and only if the first argument is `configure'. However, it
+ is important not to call <prgn>ldconfig</prgn> in the postrm or preinst
+ scripts in the case where the package is being upgraded (see <ref
+ id="unpackphase">), as <prgn>ldconfig</prgn> will see the temporary names
+ that <prgn>dpkg</prgn> uses for the files while it is
+ installing them and will make the shared library links point
+ to them, just before <prgn>dpkg</prgn> continues the
+ installation and removes the links!
+ </p>
+
+ <sect id="shlibs"><heading>The <tt>shlibs</tt> File Format
+ </heading>
+
+ <p>
+ This file is for use by <prgn>dpkg-shlibdeps</prgn> and is
+ required when your package provides shared libraries.
+ </p>
+
+ <p>
+ Each line is of the form:
+ <example>
+ <var>library-name</var> <var>version-or-soname</var> <var>dependencies ...</var>
+ </example>
+ </p>
+
+ <p>
+ <var>library-name</var> is the name of the shared library,
+ for example <tt>libc5</tt>.
+ </p>
+
+ <p>
+ <var>version-or-soname</var> is the soname of the library -
+ i.e., the thing that must exactly match for the library to be
+ recognized by <prgn>ld.so</prgn>. Usually this is the major
+ version number of the library.
+ </p>
+
+ <p>
+ <var>dependencies</var> has the same syntax as a dependency
+ field in a binary package control file. It should give
+ details of which package(s) are required to satisfy a binary
+ built against the version of the library contained in the
+ package. See <ref id="depsyntax">.
+ </p>
+
+ <p>
+ For example, if the package <tt>foo</tt> contains
+ <tt>libfoo.so.1.2.3</tt>, where the soname of the library is
+ <tt>libfoo.so.1</tt>, and the first version of the package
+ which contained a minor number of at least <tt>2.3</tt> was
+ <var>1.2.3-1</var>, then the package's <var>shlibs</var>
+ could say:
+ <example>
+ libfoo 1 foo (>= 1.2.3-1)
+ </example>
+ </p>
+
+ <p>
+ The version-specific dependency is to avoid warnings from
+ <prgn>ld.so</prgn> about using older shared libraries with
+ newer binaries.</p>
+ </sect>
+
+ <sect><heading>Further Technical information on
+ <tt>shlibs</tt></heading>
+
+ <sect1><heading><em>What</em> are the <tt>shlibs</tt> files?
+ </heading>
+