dpkg/doc/programmer.sgml

<!doctype debiandoc system>

<!--
 Debian Linux dpkg package installation tool.
 programmers' manual.
 Copyright (C)1996 Ian Jackson; released under the terms of the GNU
 General Public License, version 2 or (at your option) any later.
 -->

<book>

<title><prgn/dpkg/ programmers' manual
<author>Ian Jackson <email/ijackson@gnu.ai.mit.edu/
<version><date>

<abstract>
This manual describes the technical aspects of creating Debian binary
and source packages.  It also documents the interface between
<prgn/dselect/ and its access method scripts.  It does not deal with
the Debian Project policy requirements, and it assumes familiarity
with <prgn/dpkg/'s functions from the system administrator's
perspective.

<copyright>Copyright &copy;1996 Ian Jackson.
<p>

This manual is free software; you may redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2, or (at your option) any
later version.
<p>

This is distributed in the hope that it will be useful, but
<em>without any warranty</em>; without even the implied warranty of
merchantability or fitness for a particular purpose.  See the GNU
General Public License for more details.
<p>

You should have received a copy of the GNU General Public License with
your Debian GNU/Linux system, in <tt>/usr/doc/copyright/GPL</tt>, or
with the <prgn/dpkg/ source package as the file <tt>COPYING</tt>.  If
not, write to the Free Software Foundation, Inc., 675 Mass Ave,
Cambridge, MA 02139, USA.

<toc sect>

<!-- Describes the technical interface between a package and dpkg.

How to safely put shared libraries in a package.  Details of dpkg's
handling of individual files.  Sections on when to use which feature
(eg Replaces vs. Replaces/Conflicts vs. update-alternatives
vs. diversions) Cross-references to the policy document (see below)
where appropriate.  Description of the interface between dselect and
its access methods.  Hints on where to start with a new package (ie,
the hello package).  What to do about file aliasing.

file aliasing

Manpages are required for: update-rc.d, diversions,
update-alternatives, install-info in a package.

-->

<chapt id="scope">Introduction and scope of this manual
<p>

<prgn/dpkg/ is a suite of programs for creating binary package files
and installing and removing them on Unix systems.<footnote><prgn/dpkg/
is targetted primarily at Debian GNU/Linux, but may work on or be
ported to other systems.</footnote>
<p>

The binary packages are designed for the management of installed
executable programs (usually compiled binaries) and their associated
data, though source code examples and documentation are provided as
part of some packages.
<p>

This manual describes the technical aspects of creating Debian binary
packages (<tt/.deb/ files).  It documents the behaviour of the
package management programs <prgn/dpkg/, <prgn/dselect/ et al. and and the
way they interact with packages.
<p>

It also documents the interaction between <prgn/dselect/'s core and the
access method scripts it uses to actually install the selected
packages, and describes how to create a new access method.
<p>

This manual does not go into detail about the options and usage of the
package building and installation tools.  It should therefore be read
in conjuction with those programs' manpages.
<p>

The utility programs which are provided with <prgn/dpkg/ for managing
various system configuration and similar issues, such as
<prgn/update-rc.d/ and <prgn/install-info/, are not described in
detail here - please see their manpages.
<p>

It does <em/not/ describe the policy requirements imposed on Debian
packages, such as the permissions on files and directories,
documentation requirements, upload procedure, and so on.  You should
see the Debian packaging policy manual for these details.  (Many of
them will probably turn out to be helpful even if you don't plan to
upload your package and make it available as part of the
distribution.)
<p>

It is assumed that the reader is reasonably familiar with the
<prgn/dpkg/ System Administrators' manual.
<p>

The Debian version of the FSF's GNU hello program is provided as an
example for people wishing to create Debian packages.
<p>

<em>Note that this document is still a draft!</em>

<chapt id="binarypkg">Binary packages
<p>

The binary package has two main sections.  The first part consists of
various control information files and scripts used by <prgn/dpkg/ when
installing and removing.  See <ref id="controlarea">.
<p>

The second part is an archive (currently a <prgn/tar/ archive)
containing files and directories to be installed.
<p>

In the future binary packages may also contain other components, such
as checksums and digital signatures.


<sect id="bincreating">Creating package files - <prgn/dpkg-deb/
<p>

All manipulation of binary package files is done by <prgn/dpkg-deb/;
it's the only program that has knowledge of the format.
(<prgn/dpkg-deb/ may be invoked by calling <prgn/dpkg/, as <prgn/dpkg/ will
spot that the options requested are appropriate to <prgn/dpkg-deb/ and
invoke that instead with the same arguments.)
<p>

In order to create a binary package you must make a directory tree
which contains all the files and directories you want to have in the
filesystem data part of the package.  In Debian-format source packages
this directory is usually <tt>debian/tmp</tt>, relative to the top of
the package's source tree.
<p>

They should have the locations (relative to the root of the directory
tree you're constructing) ownerships and permissions which you want
them to have on the system when they are installed.
<p>

With current versions of <prgn/dpkg/ the uid/username and gid/groupname
mappings for the users and groups being used should be the same on the
system where the package is built and the one where it is installed.
<p>

You need to add one special directory to the root of the miniature
filesystem tree you're creating: <prgn/DEBIAN/.  It should contain the
control information files, notably the binary package control file
(see <ref id="controlfile">).
<p>

The <prgn/DEBIAN/ directory will not appear in the filesystem archive of
the package, and so won't be installed by <prgn/dpkg/ when the package
is installed.
<p>

When you've prepared the package, you should invoke:
<example>
dpkg --build <var/directory/
</example>
<p>

This will build the package in <tt/<var/directory/.deb/.
(<prgn/dpkg/ knows that <tt/--build/ is a <prgn/dpkg-deb/ option, so it
invokes <prgn/dpkg-deb/ with the same arguments to build the package.)
<p>

See the manpage <manref name="dpkg-deb" section=8> for details of how
to examine the contents of this newly-created file.  You may find the
output of following commands enlightening:
<example>
dpkg-deb --info <var/filename/.deb
dpkg-deb --contents <var/filename/.deb
</example>

<sect id="controlarea">Package control information files
<p>

The control information portion of a binary package is a collection of
files with names known to <prgn/dpkg/.  It will treat the contents of
these files specially - some of them contain information used by
<prgn/dpkg/ when installing or removing the package; others are scripts
which the package maintainer wants <prgn/dpkg/ to run.
<p>

It is possible to put other files in the package control area, but
this is not generally a good idea (though they will largely be
ignored).
<p>

Here is a brief list of the control info files supported by <prgn/dpkg/
and a summary of what they're used for.
<p>

<taglist>
<tag><tt/control/
<item>

This is the key description file used by <prgn/dpkg/.  It specifies the
package's name and version, gives its description for the user, states
its relationships with other packages, and so forth.
See <ref id="controlfile">.

<tag><tt/postinst/, <tt/preinst/, <tt/postrm/, <tt/prerm/
<item>

These are exectuable files (usually scripts) which <prgn/dpkg/ runs
during installation, upgrade and removal of packages.  They allow the
package to deal with matters which are particular to that package or
require more complicated processing than that provided by <prgn/dpkg/.
Details of when and how they are called are in
<ref id="maintainerscripts">.
<p>

It is very important to make these scripts itempotent.<footnote>That
means that if it runs successfully or fails and then you call it again
it doesn't bomb out, but just ensures that everything is the way it
ought to be.</footnote>  This is so that if an error occurs, the user
interrupts <prgn/dpkg/ or some other unforeseen circumstance happens you
don't leave the user with a badly-broken package.
<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</>, since <prgn/dpkg/ 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/ so that the output is printed immediately rather than being
buffered.
<p>

Each script should return a zero exit status for success, or a nonzero
one for failure.

<tag><tt/conffiles/
<item>

This file contains a list of configuration files which are to be
handled automatically by <prgn/dpkg/ (see <ref id="conffiles">).  Note
that not necessarily every configuration file should be listed here.

</taglist>

<sect id="controlfile">The main control information file: <tt/control/
<p>

The most important control information file used by <prgn/dpkg/ when it
installs a package is <tt/control/.  It contains all the package's
`vital statistics'.
<p>

The binary package control files of packages built from Debian sources
are made by a special tool, <prgn/dpkg-gencontrol/, which reads
<tt>debian/control</> and <tt>debian/changelog</> to find the
information it needs.  See <ref id="sourcepkg"> for more details.
<p>

The fields in binary package control files are:
<list compact>

<item><qref id="f-Package"><tt/Package/</> (mandatory)
<item><qref id="versions"><tt/Version/</> (mandatory)

<item><qref id="f-Architecture"><tt/Architecture/</>
(mandatory)<footnote>This field should appear in all packages, though
<prgn/dpkg/ doesn't require it yet so that old packages can still be
installed.</footnote>

<item><qref id="relationships"><tt/Depends/, <tt/Provides/ et al.</>
<item><qref id="f-Essential"><tt/Essential/</>
<item><qref id="f-Maintainer"><tt/Maintainer/</>
<item><qref id="f-classification"><tt/Section/, <tt/Priority/</>
<item><qref id="f-Source"><tt/Source/</>
<item><qref id="descriptions"><tt/Description/</>

</list>
<p>

A description of the syntax of control files and the purpose of these
fields is available in <ref id="controlfields">.


<chapt id="sourcepkg">Source packages
<p>

The Debian binary packages in the distribution are generated from
Debian sources, which are in a special format to assist the easy and
automatic building of binaries.
<p>

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 <manref name=dpkg-source section=1>
for details.

<sect>The Debianised source tree
<p>

The source archive scheme described later is intended to allow a
Debianised source tree with some associated control information to be
reproduced and transported easily.  The Debianised source tree is a
version of the original program with certain files added for the
benefit of the Debianisation process, and with any other changes
required made to the rest of the source code and installation scripts.
<p>

The extra files created for Debian are in the subdirectory <tt/debian/
of the top level of the Debianised source tree.  They are described
below.

<sect1><tt>debian/rules</tt> - the main building script
<p>

This file is an executable makefile, and contains the package-specific
recipies for compiling the package and building binary package(s) out
of the source.
<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/
explicitly.
<p>

The targets which are required to be present are:

<taglist>
<tag/<tt/build//
<item>

This should perform all non-interactive configuration and compilation
of the package.  If a package has an interactive pre-build
configuration routine, the Debianised source package should be built
after this has taken place, so that it can be built without rerunning
the configuration.
<p>

For some packages, notably ones where the same source tree is compiled
in different ways to produce two binary packages, the <prgn/build/
target does not make much sense.  For these packages it is good enough
to provide two (or more) targets (<tt/build-a/ and <tt/build-b/ or
whatever) for each of the ways of building the package, and a
<prgn/build/ target that does nothing.  The <prgn/binary/ target will have
to build the package in each of the possible ways and make the binary
package out of each.
<p>

The <prgn/build/ target must not do anything that might require root
privilege.
<p>

The <prgn/build/ target may need to run <prgn/clean/ first - see below.
<p>

When a package has a configuration routine that takes a long time, or
when the makefiles are poorly designed, or when <prgn/build/ needs to
run <prgn/clean/ first, it is a good idea to <tt/touch build/ 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.

<tag/<tt/binary//
<item>

This target should be all that is necessary for the user to build the
binary package.  It should depend on the <prgn/build/ target, above,
so that the package is built if it has not been already.  It should
then create the binary package(s), using <prgn/dpkg-gencontrol/ to
make their control files and <prgn/dpkg-deb/ to build them and place
them in the parent of the top level directory.
<p>

<ref id="binarypkg"> describes how to construct binary packages.
<p>

The <prgn/binary/ target must be invoked as root.

<tag/<tt/clean//
<item>

This should undo any effects that the <prgn/build/ and <prgn/binary/
targets may have had, except that it should leave alone any output
files created in the parent directory by a run of <prgn/binary/.
<p>

If a <prgn/build/ file is touched at the end of the <prgn/build/ target,
as suggested above, it must be removed as the first thing that
<prgn/clean/ does, so that running <prgn/build/ again after an interrupted
<prgn/clean/ doesn't think that everything is already done.
<p>

The <prgn/clean/ target must be invoked as root if <prgn/binary/ has
been invoked since the last <prgn/clean/, or if <prgn/build/ has been
invoked as root (since <prgn/build/ may create directories, for
example).

<tag/<tt/get-orig-source//
<item>

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
tarfile format described below, and leaves it in the current directory.
<p>

This target may be invoked in any directory, and should take care to
clean up any temporary files it may have left.
<p>

This target is optional, but providing it if possible is a good idea.

</taglist>

The <prgn/build/, <prgn/binary/ and <prgn/clean/ targets must be
invoked with a current directory of the package's top-level
directory.

<p>

Additional targets may exist in <tt>debian/rules</tt>, either as
published or undocumented interfaces or for the package's internal
use.


<sect1><tt>debian/control</tt>
<p>

This file contains version-independent details about the source
package and about the binary packages it creates.
<p>

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.
<p>

The syntax and semantics of the fields are described below in
<ref id="controlfields">.
<p>

The general (binary-package-independent) fields are:
<list compact>
<item><qref id="f-Source"><tt/Source/</> (mandatory)
<item><qref id="f-Maintainer"><tt/Maintainer/</>
<item><qref id="f-classification"><tt/Section/ and <tt/Priority/</>
(classification, mandatory)
<item><qref id="f-Standards-Version"><tt/Standards-Version/</>
</list>
<p>

The per-binary-package fields are:
<list compact>
<item><qref id="f-Package"><tt/Package/</> (mandatory)
<item><qref id="f-Architecture"><tt/Architecture/</> (mandatory)
<item><qref id="descriptions"><tt/Description/</>
<item><qref id="f-classification"><tt/Section/ and <tt/Priority/</> (classification)
<item><qref id="f-Essential"><tt/Essential/</>
<item><qref id="relationships"><tt/Depends/ et al.</> (package interrelationships)
</list>
<p>

These fields are used by <prgn/dpkg-gencontrol/ to generate control
files for binary packages (see below), by <prgn/dpkg-genchanges/ to
generate the <tt/.changes/ file to accompany the upload, and by
<prgn/dpkg-source/ when it creates the <tt/.dsc/ source control file as
part of a source archive.
<p>

The fields here may contain variable references - their values will be
substituted by <prgn/dpkg-gencontrol/, <prgn/dpkg-genchanges/ or
<prgn/dpkg-source/ when they generate output control files.  See <ref
id="srcsubstvars"> for details.
<p>

<sect2>User-defined fields
<p>

Additional user-defined fields may be added to the source package
control file.  Such fields will be ignored, and not copied to (for
example) binary or source package control files or upload control
files.
<p>

If you wish to add additional unsupported fields to these output files
you should use the mechanism described here.
<p>

Fields in the main source control information file with names starting
<tt/X/, followed by one or more of the letters <tt/BCS/ and a hyphen
<tt/-/, 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 <tt/B/ is used the field will appear in binary package
control files, where the letter <tt/S/ is used in source package
control files and where <tt/C/ is used in upload control
(<tt/.changes/) files.
<p>

For example, if the main source information control file contains the
field
<example>
XBS-Comment: I stand between the candle and the star.
</example>
then the binary and source package control files will contain the
field
<example>
Comment: I stand between the candle and the star.
</example>

<sect1 id="dpkgchangelog"><tt>debian/changelog</>
<p>

This file records the changes to the Debian-specific parts of the
package<footnote>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.</footnote>.
<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>

That format is a series of entries like this:
<example>
<var/package/ (<var/version/) <var/distribution(s)/; urgency=<var/urgency/

  * <var/change details/
    <var/more change details/
  * <var/even more change details/

 -- <var/maintainer name and email address/  <var/date/
</example>
<p>

<var/package/ and <var/version/ are the source package name and
version number.  <var/distribution(s)/ lists the distributions where
this version should be installed when it is uploaded - it is copied to
the <tt/Distribution/ field in the <tt/.changes/ file.  See <ref
id="f-Distribution">.
<p>

<var/urgency/ is the value for the <tt/Urgency/ field in the
<tt/.changes/ file for the upload.  See <ref id="f-Urgency">.  It is
not possible to specify an urgency containing commas; commas are used
to separate <tt/<var/keyword/=<var/value// settings in the <prgn/dpkg/
changelog format (though there is currently only one useful
<var/keyword/, <tt/urgency/).
<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>

The maintainer name and email address should <em/not/ necessarily be
those of the usual package maintainer.  They should be the details of
the person doing <em/this/ version.  The information here will be
copied to the <tt/.changes/ file, and then later used to send an
acknowledgement when the upload has been installed.
<p>

The <var/date/ should be in RFC822 format; it should include the
timezone specified numerically, with the timezone name or abbreviation
optionally present as a comment.
<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>

An Emacs mode for editing this format is available: it is called
<tt/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.

<sect2>Defining alternative changelog formats
<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>

In order to have <tt/dpkg-parsechangelog/ run your parser, you must
include a line within the last 40 lines of your file matching the Perl
regular expression:
<example>
\schangelog-format:\s+([0-9a-z]+)\W
</example>
The part in parentheses should be the name of the format.
<p>

If such a line exists then <tt/dpkg-parsechangelog/ will look for the
parser as <tt>/usr/lib/dpkg/parsechangelog/<var/format-name/</> or
<tt>/usr/local/lib/dpkg/parsechangelog/<var/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 <tt/dpkg/, and a parser for
it is provided with the <tt/dpkg/ package.
<p>

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 <tt/-v<var/version// option to return changes
information from all versions present <em/strictly after/
<var/version/, and it should then be an error for <var/version/ not to
be present in the changelog.
<p>

The fields are:
<list compact>
<item><qref id="f-Source"><tt/Source/</>
<item><qref id="versions"><tt/Version/</> (mandatory)
<item><qref id="f-Distribution"><tt/Distribution/</> (mandatory)
<item><qref id="f-Urgency"><tt/Urgency/</> (mandatory)
<item><qref id="f-Maintainer"><tt/Maintainer/</> (mandatory)
<item><qref id="f-Date"><tt/Date/</>
<item><qref id="f-Changes"><tt/Changes/</> (mandatory)
</list>
<p>

If several versions are being returned (due to the use of <tt/-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.
<p>

For the format of the <tt/Changes/ field see <ref id="f-Changes">.
<p>

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.
<p>

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.
<p>

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.
<p>

A changelog parser may not interact with the user at all.

<sect1 id="srcsubstvars"><tt>debian/substvars</> and variable substitutions
<p>

When <prgn/dpkg-gencontrol/, <prgn/dpkg-genchanges/ and
<prgn/dpkg-source/ generate control files they do variable
substitutions on their output just before writing it.  Variable
substitutions have the form <tt/${<var/variable-name/}/.  The optional
file <tt>debian/substvars</> contains variable substitutions to be
used; variables can also be set directly from <tt>debian/rules</>
using the <tt/-V/ option to the source packaging commands, and certain
predefined variables are available.
<p>

The file may be a static part of the source archive, or generated and
modified dynamically by <tt>debian/rules</> targets.  In the latter
case it must be removed by the <prgn/clean/ target.
<p>

See <manref name=dpkg-source section=1> for full details about source
variable substitutions, including the format of
<tt>debian/substvars</>.

<sect1><tt>debian/files</>
<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/ uses it when it generates a <tt/.changes/ file.
<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/<footnote><tt/files.new/ is used as a temporary file by
<prgn/dpkg-gencontrol/ and <prgn/dpkg-distaddfile/ - they write a new
version of <tt/files/ here before renaming it, to avoid leaving a
corrupted copy if an error occurs</footnote>) should be removed by the
<prgn/clean/ target.  It may also be wise to ensure a fresh start by
emptying or removing it at the start of the <prgn/binary/ target.
<p>

<prgn/dpkg-gencontrol/ adds an entry to this file for the <tt/.deb/
file that will be created by <prgn/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 <prgn/clean/.
<p>

If a package upload includes files besides the source package and any
binary packages whose control files were made with
<prgn/dpkg-gencontrol/ then they should be placed in the parent of the
package's top-level directory and <prgn/dpkg-distaddfile/ should be
called to add the file to the list in <tt>debian/files</>.

<sect1><tt>debian/tmp</>
<p>

This is the canonical temporary location for the construction of
binary packages by the <prgn/binary/ target.  The directory <tt/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
<tt/DEBIAN/ subdirectory.  See <ref id="bincreating">.
<p>

If several binary packages are generated from the same source tree it
is usual to use several <tt>debian/tmp<var/something/</> directories,
for example <tt/tmp-a/ or <tt/tmp-doc/.
<p>

Whatever <tt>tmp</> directories are created and used by <prgn/binary/
must of course be removed by the <prgn/clean/ target.


<sect id="sourcearchives">Source packages as archives
<p>

As it exists on the FTP site, a Debian source package consists of
three related files.  You must have the right versions of all three to
be able to use them.
<p>

<taglist>
<tag/Debian source control file - <tt/.dsc//
<item>

This file contains a series of fields, identified and separated just
like the fields in the control file of a binary package.  The fields
are listed below; their syntax is described above, in
<ref id="controlfields">.
<list compact>
<item><qref id="f-Source"><tt/Source/</>
<item><qref id="versions"><tt/Version/</>
<item><qref id="f-Maintainer"><tt/Maintainer/</>
<item><qref id="f-Binary"><tt/Binary/</>
<item><qref id="f-Architecture"><tt/Architecture/</>
<item><qref id="f-Standards-Version"><tt/Standards-Version/</>
<item><qref id="f-Files"><tt/Files/</>
</list>
<p>

The source package control file is generated by <prgn/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.

<tag/Original source archive - <tt/<var/package/_<var/upstream-version/.orig.tar.gz//
<item>

This is a compressed (with <tt/gzip -9/) <prgn/tar/ file containing
the source code from the upstream authors of the program.  The tarfile
unpacks into a directory
<tt/<var/package/-<var/upstream-version/.orig/, and does not contain
files anywhere other than in there or in its subdirectories.

<tag/Debianisation diff - <tt/<var/package/_<var/version-revision/.diff.gz//
<item>

This is a unified context diff (<tt/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.
<p>

All the directories in the diff must exist, except the <tt/debian/
subdirectory of the top of the source tree, which will be created by
<prgn/dpkg-source/ if necessary when unpacking.
<p>

The <prgn/dpkg-source/ program will automatically make the
<tt>debian/rules</tt> file executable (see below).

</taglist>
<p>

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
<tt/<var/package/_<var/version/.tar.gz</> and contains a directory
<tt/<var/package/-<var/version/</>.

<sect>Unpacking a Debian source package without <prgn/dpkg-source/
<p>

<tt/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:

<enumlist compact>
<item>Untar the tarfile, which will create a <tt/.orig/ directory.
<item>Rename the <tt/.orig/ directory to
<tt/<var/package/-<var/version//.
<item>Create the subdirectory <tt/debian/ at the top of the source
tree.
<item>Apply the diff using <tt/patch -p0/.
<item>Untar the tarfile again if you want a copy of the original
source code alongside the Debianised version.
</enumlist>
<p>

It is not possible to generate a valid Debian source archive without
using <prgn/dpkg-source/.  In particular, attempting to use
<prgn/diff/ directly to generate the <tt/.diff.gz/ file will not work.

<sect1>Restrictions on objects in source packages
<p>

The source package may not contain any device special files, sockets
or setuid or setgid files.<footnote>Setgid directories are
allowed.</footnote>
<p>

The source packaging tools manage the changes between the original and
Debianised source using <prgn/diff/ and <prgn/patch/.  Turning the
original source tree as included in the <tt/.orig.tar.gz/ into the
debianised source must not involve any changes which cannot be handled
by these tools.  Problematic changes which cause <prgn/dpkg-source/ to
halt with an error when building the source package are:
<list compact>
<item>Adding or removing symbolic links, sockets or pipes.
<item>Changing the targets of symbolic links.
<item>Creating directories, other than <tt/debian/.
<item>Changes to the contents of binary files.
</list>
Changes which cause <prgn/dpkg-source/ to print a warning but continue
anyway are:
<list compact>
<item>Removing files, directories or symlinks.  <footnote>Renaming a
file is not treated specially - it is seen as the removal of the old
file (which generates a warning, but is otherwise ignored), and the
creation of the new one.</footnote>
</list>
Changes which are not represented, but which are not detected by
<prgn/dpkg-source/, are:
<list compact>
<item>Changing the permissions of files (other than
<tt>debian/rules</>) and directories.
</list>
<p>

The <tt/debian/ directory and <tt>debian/rules</> are handled
specially by <prgn/dpkg-source/ - before applying the changes it will
create the <tt/debian/ directory, and afterwards it will make
<tt>debian/rules</> world-exectuable.

<chapt id="controlfields">Control files and their fields
<p>

Many of the tools in the <prgn/dpkg/ suite manipulate data in a common
format, known as control files.  Binary and source packages have
control data as do the <tt/.changes/ files which control the
installation of uploaded files, and <prgn/dpkg/'s internal databases
are in a similar format.

<sect>Syntax of control files
<p>

A file consists of one or more paragraphs of fields.  The paragraphs
are separated by blank lines.  Some control files only allow one
paragraph; others allow several, in which case each paragraph often
refers to a different package.
<p>

Each paragraph is a series of fields and values; each field consists
of a name, followed by a colon and the value.  It ends at the end of
the line.  Horizontal whitespace (spaces and tabs) may occur before or
after the value and is ignored there; it is conventional to put a
single space after the colon.
<p>

Some fields' values may span several lines; in this case each
continuation line <em/must/ start with a space or tab.  Any trailing
spaces or tabs at the end of individual lines of a field value are
ignored.
<p>

Except where otherwise stated only a single line of data is allowed
and whitespace is not significant in a field body.  Whitespace may
never appear inside names (of packages, architectures, files or
anything else), version numbers or in between the characters of
multi-character version relationships.
<p>

Field names are not case-sensitive, but it is usual to capitalise the
fields using mixed case as shown below.
<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>

It is important to note that there are several fields which are
optional as far as <prgn/dpkg/ and the related tools are concerned,
but which must appear in every Debian package, or whose omission may
cause problems.  When writing the control files for Debian packages
you <em/must/ read the Debian policy manual in conjuction with the
details below and the list of fields for the particular file.

<sect>List of fields

<sect1 id="f-Package"><tt/Package/
<p>

The name of the binary package.  Package names consist of the
alphanumerics and <tt/+/ <tt/-/ <tt/./ (plus, minus and full
stop).<footnote>The characters <tt/@/ <tt/:/ <tt/=/ <tt/%/ <tt/_/ (at,
colon, equals, percent and underscore) used to be legal and are still
accepted when found in a package file, but may not be used in new
packages</footnote>
<p>

They must be at least two characters and must start with an
alphanumeric.  In current versions of dpkg they are sort of
case-sensitive<footnote>This is a bug.</footnote>; use lowercase
package names unless the package you're building (or referring to, in
other fields) is already using uppercase.

<sect1 id="f-Version"><tt/Version/
<p>

This lists the source or binary package's version number - see <ref
id="versions">.

<sect1 id="f-Architecture"><tt/Architecture/
<p>

This is the architecture string; it is a single word for the CPU
architecture.
<p>

<prgn/dpkg/ will check the declared architecture of a binary package
against its own compiled-in value before it installs it.
<p>

The special value <tt/all/ indicates that the package is
architecture-independent.
<p>

In the main <tt>debian/control</> file in the source package, or in
the source package control file <tt/.dsc/, a list of architectures
(separated by spaces) is also allowed, as is the special value
<tt/any/.  A list indicates that the source will build an
architecture-dependent package, and will only work correctly on the
listed architectures.  <tt/any/ indicates that though the source
package isn't dependent on any particular architecture and should
compile fine on any one, the binary package(s) produced are not
architecture-independent but will instead be specific to whatever the
current build architecture is.
<p>

In a <tt/.changes/ file the <tt/Architecture/ field lists the
architecture(s) of the package(s) currently being uploaded.  This will
be a list; if the source for the package is being uploaded too the
special entry <tt/source/ is also present.
<p>

The current build architecture can be determined using <tt/dpkg
--print-architecture/.<footnote>This actually invokes
<example>
gcc --print-libgcc-file-name
</example>
and parses and decomposes the output and looks the CPU type from the
GCC configuration in a table in <prgn/dpkg/.  This is so that it will
work if you're cross-compiling.
</footnote>
This value is automatically used by <prgn/dpkg-gencontrol/ when
building the control file for a binary package for which the source
control information doesn't specify architecture <tt/all/.
<p>

There is a separate option, <tt/--print-installation-architecture/,
for finding out what architecture <prgn/dpkg/ is willing to install.
This information is also in the output of <tt/dpkg --version/.

<sect1 id="f-Maintainer"><tt/Maintainer/
<p>

The package maintainer's name and email address.  The name should come
first, then the email address inside angle brackets <tt/&lt;&gt/ (in
RFC822 format).
<p>

If the maintainer's name contains a full stop then the whole field
will not work directly as an email address due to a misfeature in the
syntax specified in RFC822; a program using this field as an address
must check for this and correct the problem if necessary (for example
by putting the name in round brackets and moving it to the end, and
bringing the email address forward).
<p>

In a <tt/.changes/ file or parsed changelog data this contains the
name and email address of the person responsible for the particular
version in question - this may not be the package's usual maintainer.
<p>

This field is usually optional in as far as the <prgn/dpkg/ are
concerned, but its absence when building packages usually generates a
warning.

<sect1 id="f-Source"><tt/Source/
<p>

This field identifies the source package name.
<p>

In a main source control information or a <tt/.changes/ or <tt/.dsc/
file or parsed changelog data this may contain only the name of the
source package.
<p>

In the control file of a binary package (or in a <tt/Packages/ file)
it may be followed by a version number in parentheses.<footnote>It is
usual to leave a space after the package name if a version number is
specified.</footnote> This version number may be omitted (and is, by
<prgn/dpkg-gencontrol/) if it has the same value as the <tt/Version/
field of the binary package in question.  The field itself may be
omitted from a binary package control file when the source package has
the same name and version as the binary package.

<sect1>Package interrelationship fields:
<tt/Depends/, <tt/Pre-Depends/, <tt/Recommends/
<tt/Suggests/, <tt/Conflicts/, <tt/Provides/, <tt/Replaces/
<p>

These fields describe the package's relationships with other packages.
Their syntax and semantics are described in <ref id="relationships">.

<sect1 id="f-Description"><tt/Description/
<p>

In a binary package <tt/Packages/ file or main source control file
this field contains a description of the binary package, in a special
format.  See <ref id="descriptions"> for details.
<p>

In a <tt/.changes/ file it contains a summary of the descriptions for
the packages being uploaded.  The part of the field before the first
newline is empty; thereafter each line has the name of a binary
package and the summary description line from that binary package.
Each line is indented by one space.

<sect1 id="f-Essential"><tt/Essential/
<p>

This is a boolean field which may occur only in the control file of a
binary package (or in the <tt/Packages/ file) or in a per-package
fields paragraph of a main source control data file.
<p>

If set to <tt/yes/ then <prgn/dpkg/ and <prgn/dselect/ will refuse to
remove the package (though it can be upgraded and/or replaced).  The
other possible value is <tt/no/, which is the same as not having the
field at all.

<sect1 id="f-classification"><tt/Section/ and <tt/Priority/
<p>

These two fields classify the package.  The <tt/Priority/ represents
how important that it is that the user have it installed; the
<tt/Section/ represents an application area into which the package has
been classified.
<p>

When they appear in the <tt>debian/control</> file these fields give
values for the section and priority subfields of the <tt/Files/ field
of the <tt/.changes/ file, and give defaults for the section and
priority of the binary packages.
<p>

The section and priority are represented, though not as separate
fields, in the information for each file in the <qref
id="f-Files"><tt/Files/</> field of a <tt/.changes/ file.  The
section value in a <tt/.changes/ file is used to decide where to
install a package in the FTP archive.
<p>

These fields are not used by by <prgn/dpkg/ proper, but by
<prgn/dselect/ when it sorts packages and selects defaults.  See the
Debian policy manual for the priorities in use and the criteria for
selecting the priority for a Debian package, and look at the Debian
FTP archive for a list of currently in-use priorities.
<p>

These fields may appear in binary package control files, in which case
they provide a default value in case the <tt/Packages/ files are
missing the information.  <prgn/dpkg/ and <prgn/dselect/ will only use
the value from a <tt/.deb/ file if they have no other information; a
value listed in a <tt/Packages/ file will always take precedence.  By
default <prgn/dpkg-genchanges/ does not include the section and
priority in the control file of a binary package - use the <tt/-isp/,
<tt/-is/ or <tt/-ip/ options to achieve this effect.

<sect1 id="f-Binary"><tt/Binary/
<p>

This field is a list of binary packages.
<p>

When it appears in the <tt/.dsc/ file it is the list of binary
packages which a source package can produce.  It does not necessarily
produce all of these binary packages for every architecture.  The
source control file doesn't contain details of which architectures are
appropriate for which of the binary packages.
<p>

When it appears in a <tt/.changes/ file it lists the names of the
binary packages actually being uploaded.
<p>

The syntax is a list of binary packages separated by
commas.<footnote>A space after each comma is conventional.</footnote>
Currently the packages must be separated using only spaces in the
<tt/.changes/ file.

<sect1 id="f-Files"><tt/Files/
<p>

This field contains a list of files with information about each one.
The exact information and syntax varies with the context.  In all
cases the the part of the field contents on the same line as the field
name is empty.  The remainder of the field is one line per file, each
line being indented by one space and containing a number of sub-fields
separated by spaces.
<p>

In the <tt/.dsc/ (Debian source control) file each line contains the
MD5 checksum, size and filename of the tarfile and (optionally) diff
file which make up the remainder of the source package.<footnote>That
is, the parts which are not the <tt/.dsc/.</footnote> The exact forms
of the filenames are described in <ref id="sourcearchives">.
<p>

In the <tt/.changes/ file this contains one line per file being
uploaded.  Each line contains the MD5 checksum, size, section and
priority and the filename.  The section and priority are the values of
the corresponding fields in the main source control file - see <ref
id="f-classification">.  If no section or priority is specified then
<tt/-/ should be used, though section and priority values must be
specified for new packages to be installed properly.
<p>

The special value <tt/byhand/ for the section indicates that the file
in question is not an ordinary package file and must by installed by
hand by the distribution maintainers.  If the section is <tt/byhand/
the priority should be <tt/-/.


<sect1 id="f-Standards-Version"><tt/Standards-Version/
<p>

The most recent version of the standards (the <prgn/dpkg/ programmers'
and policy manuals 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.
<p>

Its format is the same as that of a version number except that no
epoch or Debian revision is allowed - see <ref id="versions">.

<sect1 id="f-Distribution"><tt/Distribution/
<p>

In a <tt/.changes/ file or parsed changelog output this contains the
(space-separated) name(s) of the distribution(s) where this version of
the package should be or was installed.  Distribution names follow the
rules for package names.  (See <ref id="f-Package">).
<p>

Current distribution values are <tt/stable/, <tt/unstable/,
<tt/contrib/, <tt/non-free/ and <tt/experimental/.

<sect1 id="f-Urgency"><tt/Urgency/
<p>

This is a description of how important it is to upgrade to this
version from previous ones.  It consists of a single keyword usually
taking one of the values <tt/LOW/, <tt/MEDIUM/ or <tt/HIGH/) followed
by an optional commentary (separated by a space) which is usually in
parentheses.  For example:
<example>
Urgency: LOW (HIGH for diversions users)
</example>
<p>

This field appears in the <tt/.changes/ file and in parsed changelogs;
its value appears as the value of the <tt/urgency/ attribute in a
<prgn/dpkg/-style changelog (see <ref id="dpkgchangelog">).
<p>

Urgency keywords are not case-sensitive.

<sect1 id="f-Date"><tt/Date/
<p>

In <tt/.changes/ files and parsed changelogs, this gives the date the
package was built or last edited.

<sect1 id="f-Format"><tt/Format/
<p>

This field occurs in <tt/.changes/ files, and specifies a format
revision for the file.  The format described here is version <tt/1.5/.
The syntax of the format value is the same as that of a package
version number except that no epoch or Debian revision is allowed -
see <ref id="versions">.

<sect1 id="f-Changes"><tt/Changes/
<p>

In a <tt/.changes/ file or parsed changelog this field contains the
human-readable changes data, describing the differences between the
last version and the current one.
<p>

There should be nothing in this field before the first newline; all
the subsequent lines must be indented by at least one space; blank
lines must be represented by a line consiting only of a space and a
full stop.
<p>

Each version's change information should be preceded by a `title' line
giving at least the version, distribution(s) and urgency, in a
human-readable way.
<p>

If data from several versions is being returned the entry for the most
recent version should be returned first, and entries should be
separated by the representation of a blank line (the `title' line may
also be followed by the representation of blank line).

<sect1 id="f-Filename"><tt/Filename/ and <tt/MSDOS-Filename/
<p>

These fields in <tt/Packages/ files give the filename(s) of (the parts
of) a package in the distribution directories, relative to the root of
the Debian hierarchy.  If the package has been split into several
parts the parts are all listed in order, separated by spaces.

<sect1 id="f-Size"><tt/Size/ and <tt/MD5sum/
<p>

These fields in <tt/Packages/ files give the size (in bytes, expressed
in decimal) and MD5 checksum of the file(s) which make(s) up a binary
package in the distribution.  If the package is split into several
parts the values for the parts are listed in order, separated by
spaces.

<sect1 id="f-Status"><tt/Status/
<p>

This field in <prgn/dpkg/'s status file records whether the user wants a
package installed, removed or left alone, whether it is broken
(requiring reinstallation) or not and what its current state on the
system is.  Each of these pieces of information is a single word.

<sect1 id="f-Config-Version"><tt/Config-Version/
<p>

If a package is not installed or not configured, this field in
<prgn/dpkg/'s status file records the last version of the package which
was successfully configured.

<sect1 id="f-Conffiles"><tt/Conffiles/
<p>

This field in <prgn/dpkg/'s status file contains information about the
automatically-managed configuration files held by a package.  This
field should <em/not/ appear anywhere in a package!

<sect1>Obsolete fields
<p>

These are still recognised by <prgn/dpkg/ but should not appear anywhere
any more.

<taglist compact>

<tag><tt/Revision/
<tag><tt/Package-Revision/
<tag><tt/Package_Revision/
<item>
The Debian revision part of the package version was at one point in a
separate control file field.  This field went through several names.

<tag><tt/Recommended/
<item>Old name for <tt/Recommends/

<tag><tt/Optional/
<item>Old name for <tt/Suggests/.

<tag><tt/Class/
<item>Old name for <tt/Priority/.

</taglist>

<chapt id="versions">Version numbering
<p>

Every package has a version number, in its <tt/Version/ control file
field.
<p>

<prgn/dpkg/ imposes an ordering on version numbers, so that it can tell
whether packages are being up- or downgraded and so that <prgn/dselect/
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>

The version number format is:
&lsqb<var/epoch/<tt/:/&rsqb;<var/upstream-version/&lsqb;<tt/-/<var/debian-revision/&rsqb;.
<p>

The three components here are:

<taglist>

<tag><var/epoch/
<item>

This is a single unsigned integer, which should usually be small.  It
may be omitted, in which case zero is assumed.  If it is omitted then
the <var/upstream-version/ may not contain any colons.
<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>

<prgn/dpkg/ will not usually display the epoch unless it is essential
(non-zero, or if the <var/upstream-version/ contains a colon);
<prgn/dselect/ does not display epochs at all in the main part of the
package selection display.

<tag><var/upstream-version/
<item>

This is the main part of the version.  It is usually version number of
the original (`upstream') package of which the <tt/.deb/ 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 <prgn/dpkg/'s format and comparison scheme.
<p>

The comparison behaviour of <prgn/dpkg/ with respect to the
<var/upstream-version/ is described below.  The <var/upstream-version/
portion of the version number is mandatory.
<p>

The <var/upstream-version/ may contain only alphanumerics and the
characters <tt/+/ <tt/./ <tt/-/ <tt/:/ (full stop, plus, hyphen,
colon) and should start with a digit.  If there is no
<var/debian-revision/ then hyphens are not allowed; if there is no
<var/epoch/ then colons are not allowed.

<tag><var/debian-revision/
<item>

This part of the version represents the version of the modifications
that were made to the package to make it a Debian binary package.  It
is in the same format as the <var/upstream-version/ and <prgn/dpkg/
compares it in the same way.
<p>

It is optional; if it isn't present then the <var/upstream-version/
may not contain a hyphen.  This format represents the case where a
piece of software was written specifically to be turned into a Debian
binary package, and so there is only one `debianization' of it and
therefore no revision indication is required.
<p>

It is conventional to restart the <var/debian-revision/ at <tt/1/ each
time the <var/upstream-version/ is increased.
<p>

<prgn/dpkg/ will break the <var/upstream-version/ and
<var/debian-revision/ apart at the last hyphen in the string.  The
absence of a <var/debian-revision/ compares earlier than the presence
of one (but note that the <var/debian-revision/ is the least
significant part of the version number).
<p>

The <var/debian-revision/ may contain only alphanumerics and the
characters <tt/+/ and <tt/./ (plus and full stop).

</taglist>

The <var/upstream-version/ and <var/debian-revision/ parts are
compared by <prgn/dpkg/ using the same algorithm:
<p>

The strings are compared from left to right.
<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>

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>

These two steps are repeated (chopping initial non-digit strings and
initial digit strings off from the start) until a difference is found
or both strings are exhausted.
<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 changes.  It is <em/not/ there to cope with version
numbers containing strings of letters which <prgn/dpkg/ cannot interpret
(such as <tt/ALPHA/ or <tt/pre-/), or with silly orderings (the author
of this manual has heard of a package whose versions went <tt/1.1/,
<tt/1.2/, <tt/1.3/, <tt/1/, <tt/2.1/, <tt/2.2/, <tt/2/ and so forth).
<p>

If an upstream package has problematic version numbers they should be
converted to a sane form for use in the <tt/Version/ field.


<chapt id="maintainerscripts">Package maintainer scripts
and installation procedure
<sect>Introduction to package maintainer scripts
<p>

It is possible supply scripts as part of a package which <prgn/dpkg/
will run for you when your package is installed, upgraded or removed.
<p>

These scripts should be the files <tt/preinst/, <tt/postinst/,
<tt/prerm/ and <tt/postrm/ in the control area of the package.  They
must be proper exectuable files; if they are scripts (which is
recommended) they must start with the usual <tt/#!/ convention.  They
should be readable and executable to anyone, and not world-writeable.
<p>

<prgn/dpkg/ 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 <prgn/dpkg/ can stop its processing.  For shell scripts this
means that you <em/almost always/ need to use <tt/set -e/ (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>

It is necessary for the error recovery procedures that the scripts be
idempotent: ie, invoking the same script several times in the same
situation should do no harm.  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.
<p>

When a package is upgraded a combination of the scripts from the old
and new packages is called in amongst the other steps of 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>

Broadly speaking the <prgn/preinst/ is called before (a particular
version of) a package is installed, and the <prgn/postinst/ afterwards;
the <prgn/prerm/ before (a version of) a package is removed and the
<prgn/postrm/ afterwards.


<sect id="mscriptsinstact">Summary of ways maintainer scripts are called
<p>

<list compact>
<item><var/new-preinst/ <tt/install/
<item><var/new-preinst/ <tt/install/ <var/old-version/
<item><var/new-preinst/ <tt/upgrade/ <var/old-version/
<item><var/old-preinst/ <tt/abort-upgrade/ <var/new-version/
</list>
<p>

<list compact>
<item><var/postinst/ <tt/configure/ <var/most-recently-configured-version/
<item><var/old-postinst/ <tt/abort-upgrade/ <var/new version/
<item><var/conflictor's-postinst/ <tt/abort-remove/
    <tt/in-favour/ <var/package/ <var/new-version/
<item><var/deconfigured's-postinst/ <tt/abort-deconfigure/
    <tt/in-favour/ <var/failed-install-package/ <var/version/
    <tt/removing/ <var/conflicting-package/ <var/version/
</list>
<p>

<list compact>
<item><var/prerm/ <tt/remove/
<item><var/old-prerm/ <tt/upgrade/ <var/new-version/
<item><var/new-prerm/ <tt/failed-upgrade/ <var/old-version/
<item><var/conflictor's-prerm/ <tt/remove/ <tt/in-favour/
    <var/package/ <var/new-version/
<item><var/deconfigured's-prerm/ <tt/deconfigure/
    <tt/in-favour/ <var/package-being-installed/ <var/version/
    <tt/removing/ <var/conflicting-package/ <var/version/
</list>
<p>

<list compact>
<item><var/postrm/ <tt/remove/
<item><var/postrm/ <tt/purge/
<item><var/old-postrm/ <tt/upgrade/ <var/new-version/
<item><var/new-postrm/ <tt/failed-upgrade/ <var/old-version/
<item><var/new-postrm/ <tt/abort-install/
<item><var/new-postrm/ <tt/abort-install/ <var/old-version/
<item><var/new-postrm/ <tt/abort-upgrade/ <var/old-version/
<item><var/disappearer's-postrm/ <tt/disappear/ <var/overwriter/ <var/new-version/
</list>


<sect>Details of unpack phase of installation or upgrade
<p>

The procedure on installation/upgrade/overwrite/disappear (ie, when
running <tt/dpkg --unpack/, or the unpack stage of <tt/dpkg
--install/) is as follows.  In each case if an error occurs the
actions in are 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>

<enumlist>
<item>
If a version the package is already
installed, call
<example>
<var/old-prerm/ upgrade <var/new-version/
</example>

<item>
If this gives an error (ie, a non-zero exit status), dpkg will
attempt instead:
<example>
<var/new-prerm/ failed-upgrade <var/old-version/
</example>
Error unwind, for both the above cases:
<example>
<var/old-postinst/ abort-upgrade <var/new-version/
</example>

</enumlist>

<item>
If a `conflicting' package is being removed at the same time:
<enumlist>

<item>
If any packages depended on that conflicting package and
<tt/--auto-deconfigure/ is specified, call, for each such package:
<example>
<var/deconfigured's-prerm/ deconfigure \
    in-favour <var/package-being-installed/ <var/version/ \
    removing <var/conflicting-package/ <var/version/
</example>
Error unwind:
<example>
<var/deconfigured's-postinst/ abort-deconfigure \
    in-favour <var/package-being-installed-but-failed/ <var/version/ \
    removing <var/conflicting-package/ <var/version/
</example>
The deconfigured packages are marked as requiring configuration, so
that if <tt/--install/ is used they will be configured again if
possible.

<item>
To prepare for removal of the conflicting package, call:
<example>
<var/conflictor's-prerm/ remove in-favour <var/package/ <var/new-version/
</example>
Error unwind:
<example>
<var/conflictor's-postinst/ abort-remove \
    in-favour <var/package/ <var/new-version/
</example>

</enumlist>

<item>
<enumlist>
<item>
If the package is being upgraded, call:
<example>
<var/new-preinst/ upgrade <var/old-version/
</example>

<item>
Otherwise, if the package had some configuration files from a previous
version installed (ie, it is in the `configuration files only' state):
<example>
<var/new-preinst/ install <var/old-version/
</example>

<item>
Otherwise (ie, the package was completely purged):
<example>
<var/new-preinst/ install
</example>
Error unwind versions, respectively:
<example>
<var/new-postrm/ abort-upgrade <var/old-version/
<var/new-postrm/ abort-install <var/old-version/
<var/new-postrm/ abort-install
</example>

</enumlist>

<item>
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 left
around, and if anything goes wrong dpkg will attempt to put them back
as part of the error unwind).
<p>

It is an error for a package to contains files which are on the system
in another package, unless <tt/Replaces/ is used (see
<ref id="replaces">).  Currently the <tt/--force-overwrite/ flag is
enabled, downgrading it to a warning, but this may not always be the
case.
<p>

Packages which overwrite each other's files produce behaviour 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>Part of the problem is due to what
is arguably a bug in <prgn/dpkg/.</footnote>

<item>

<enumlist>
<item>
If the package is being upgraded, call
<example>
<var/old-postrm/ upgrade <var/new-version/
</example>

<item>
If this fails, <prgn/dpkg/ will attempt:
<example>
<var/new-postrm/ failed-upgrade <var/old-version/
</example>
Error unwind, for both cases:
<example>
<var/old-preinst/ abort-upgrade <var/new-version/
</example>

</enumlist>

This is the point of no return - if <prgn/dpkg/ 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
reinstallation to clear up, but it's when <prgn/dpkg/ starts doing
things that are irreversible.

<item>
Any files which were in the old version of the package but not in the
new are removed.

<item>
The new file list replaces the old.

<item>
The new maintainer scripts replace the old.

<item>
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>
<prgn/dpkg/ calls:
<example>
<var/disappearer's-postrm/ disappear \
    <var/overwriter/ <var/overwriter-version/
</example>

<item>
The package's maintainer scripts are removed.

<item>
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/).  Note that disappearing packages do not
have their prerm called, because <prgn/dpkg/ doesn't know in advance
that the package is going to vanish.

</enumlist>

<item>
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
lobotomise the file list of the `conflicting' package if there is one.)

<item>
The backup files made during installation, above, are deleted.

<item>
The new package's status is now sane, and recorded as `unpacked'.  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.

<item>
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).

</enumlist>

<sect>Details of configuration
<p>

When we configure a package (this happens with <tt/dpkg --install/, or
with <tt/--configure/), we first update the conffiles and then call:
<example>
<var/postinst/ configure <var/most-recently-configured-version/
</example>
<p>

No attempt is made to unwind after errors during configuration.
<p>

If there is no most recently configured version <prgn/dpkg/ will pass a
null argument; older versions of dpkg may pass
<tt>&lt;unknown&gt;</tt> (including the angle brackets) in this case.
Even older ones do not pass a second argument at all, under any
circumstances.

<sect>Details of removal and/or configuration purging
<p>

<enumlist>
<item>
<example>
<var/prerm/ remove
</example>

<item>
The package's files are removed (except conffiles).

<item>
<example>
<var/postrm/ remove
</example>

<item>
All the maintainer scripts except the postrm are removed.
<p>

If we aren't purging the package we stop here.  Note that packages
which have no postrm and no conffiles are automatically purged when
removed, as there is no difference except for the <prgn/dpkg/ status.

<item>
The conffiles and any backup files (<tt/~/-files, <tt/#*#/ files,
<tt/%/-files, <tt/.dpkg-{old,new,tmp}/, etc.) are removed.

<item>
<example>
<var/postrm/ purge
</example>

<item>
The package's file list is removed.

</enumlist>

No attempt is made to unwind after errors during removal.


<chapt id="descriptions">Descriptions of packages - the
<tt/Description/ field
<p>

The <tt/Description/ control file field is used by <prgn/dselect/ when
the user is selecting which packages to install and by <prgn/dpkg/
when it displays information about the status of packages and so
forth.  It is included on the FTP site in the <prgn/Packages/ files,
and may also be used by the Debian WWW pages.
<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>

The field's format is as follows:
<example>
Description: <var/single line synopsis/
 <var/extended description over several lines/
</example>
<p>

The synopsis is often printed in lists of packages and so forth, and
should be as informative as possible.  Every package should also have
an extended description.
<p>

<sect>Types of formatting line in the extended description
<p>

<list>
<item>
Those starting with a single space are part of a paragraph.
Successive lines of this form will be word-wrapped when displayed.
The leading space will usually be stripped off.

<item>
Those starting with two or more spaces.  These will be displayed
verbatim.  If the display cannot be panned horizontally the
displaying program will linewrap them `hard' (ie, without taking
account of word breaks).  If it can they will be allowed to trail
off to the right.  None, one or two initial spaces may be deleted,
but the number of spaces deleted from each line will be the same
(so that you can have indenting work correctly, for example).

<item>
Those containing a single space followed by a single full stop
character.  These are rendered as blank lines.  This is the <em/only/
way to get a blank line - see below.

<item>
Those containing a space, a full stop and some more characters.  These
are for future expansion.  Do not use them.
</list>

<sect>Notes about writing descriptions
<p>

<em/Always/ start extended description lines with at least one
whitespace character.  Fields in the control file and in the Packages
file are separated by field names starting in the first column, just
as message header fields are in RFC822.  Forgetting the whitespace
will cause <prgn/dpkg-deb/<footnote>Version 0.93.23 or
later.</footnote> to produce a syntax error when trying to build the
package.  If you force it to build anyway <prgn/dpkg/ will refuse to
install the resulting mess.
<p>

<em/Do not/ include any completely <em/empty/ lines. These separate
different records in the Packages file and different packages in the
<tt>debian/control</> file, and are forbidden in package control
files.  See the previous paragraph for what happens if you get this
wrong.
<p>

The single line synopsis should be kept brief - certainly under 80
characters.  <prgn/dselect/ displays between 25 and 49 characters
without panning if you're using an 80-column terminal, depending on
what display options are in effect.
<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>

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>

The blurb that comes with a program in its announcements and/or
<prgn/README/ 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.  The description field needs to make sense to anyone,
even people who have no idea about any of the
things the package deals with.
<p>

Put important information first, both in the synopis 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>

You may include information about dependencies and so forth in the
extended description, if you wish.
<p>

Do not use tab characters.  Their effect is not predictable.
<p>

Do not try to linewrap the summary (the part on the same line as the
field name <tt/Description/) into the extended description.  This will
not work correctly when the full description is displayed, and makes
no sense where only the summary is available.

<sect>Example description in control file for Smail
<p>

<example>
Package: smail
Version: 3.1.29.1-13
Maintainer: Ian Jackson &lt;iwj10@cus.cam.ac.uk&gt;
Recommends: pine | mailx | elm | emacs | mail-user-agent
Suggests: metamail
Depends: cron, libc5
Conflicts: sendmail
Provides: mail-transport-agent
Description: Electronic mail transport system.
 Smail is the recommended mail transport agent (MTA) for Debian.
 .
 An MTA is the innards of the mail system - it takes messages from
 user-friendly mailer programs and arranges for them to be delivered
 locally or passed on to other systems as required.
 .
 In order to make use of it you must have one or more user level
 mailreader programs such as elm, pine, mailx or Emacs (which has Rmail
 and VM as mailreaders) installed.  If you wish to send messages other
 than just to other users of your system you must also have appropriate
 and VM as mailreaders) installed.  If you wish to send messages other
 than just to other users of your system you must also have appropriate
 networking support, in the form of IP or UUCP.
</example>

<chapt id="relationships">Declaring relationships between packages
<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>

This is done using the <tt/Depends/, <tt/Recommends/, <tt/Suggests/,
<tt/Conflicts/, <tt/Provides/ and <tt/Replaces/ control file fields.
<p>

<sect>Syntax of relationship fields
<p>

These fields all have a uniform syntax.  They are a list of package
names separated by commas.
<p>

In <tt/Depends/, <tt/Recommends/, <tt/Suggests/ and <tt/Pre-Depends/
(the fields which declare dependencies of the package in which they
occur on other packages) these package names may also be lists of
alternative package names, separated by vertical bar symbols <tt/|/
(pipe symbols).
<p>

All the fields except <tt/Provides/ 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>

The relations allowed are
<tt/&lt;&lt;/,
<tt/&lt;=/,
<tt/=/,
<tt/&gt;=/ and
<tt/&gt;&gt;/
for strictly earlier, earlier or equal, exactly equal, later or equal
and strictly later, respectively.  The forms <tt/&lt;/ and <tt/&gt;/
were used to mean earlier/later or equal, rather than strictly
earlier/later, so they should not appear in new packages (though
<prgn/dpkg/ still supports them).
<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/ 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>

For example:
<example>
Package: metamail
Version: 2.7-3
Depends: libc5 (>= 5.2.18-4), mime-support, csh | tcsh
</example>

<sect>Dependencies - <tt/Depends/, <tt/Recommends/, <tt/Suggests/, <tt/Pre-Depends/
<p>

These four fields are used to declare a dependency by one package on
another.  They appear in the depending package's control file.
<p>

All but <tt/Pre-Depends/ (discussed below) take effect <em/only/ 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>

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>

Thus <tt/Depends/ allows package maintainers to impose an order in
which packages should be configured.

<taglist>
<tag><tt/Depends/
<item>

This declares an absolute dependency.
<p>

<prgn/dpkg/ will not configure
packages whose dependencies aren't satisfied.  If it is asked to make
an installation which would cause an installed package's dependencies
to become unsatisfied it will complain<footnote>Current versions
(1.2.4) of <prgn/dpkg/ have a bug in this area which will cause some of
these problems to be ignored.</footnote>, unless
<tt/--auto-deconfigure/ is specified, in which case those packages
will be deconfigured before the installation proceeds.
<p>

<prgn/dselect/ makes it hard for the user to select packages for
installation, removal or upgrade in a way that would mean that
packages' <prgn/Depends/ fields would be unsatisfied.  The user can
override this if they wish, for example if they know that <prgn/dselect/
has an out-of-date view of the real package relationships.
<p>

The <tt/Depends/ field should be used if the depended-on package is
required for the depending package to provide a significant amount of
functionality.

<tag><tt/Recommends/
<item>
This declares a strong, but not absolute, dependency.
<p>

<tt/Recommends/ is ignored by <prgn/dpkg/, so that users using the
command-line (who are presumed to know what they're doing) will not be
impeded.
<p>

It is treated by <prgn/dselect/ exactly as <tt/Depends/ is; this makes
it hard for the user to select things so as to leave <tt/Recommends/
fields unsatisfied, but they are able to do so by being persistent.
<p>

The <tt/Recommends/ field should list packages that would be found
together with this one in all but unusual installations.

<tag><tt/Suggests/
<item>

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 be related to this one and can
perhaps enhance its usefulness, but that installing this one without
them is perfectly reasonable.
<p>

<prgn/dselect/ will offer suggsted packages to the system administrator
when they select the suggesting package, but the default is not to
install the suggested package.

<tag><tt/Pre-Depends/
<item>

This field is like <tt/Depends/, except that it also forces <prgn/dpkg/
to complete installation of the packages named before even starting
the installation of the package which declares the predependency.
<p>

<prgn/dselect/ checks for predependencies when it is doing an
installation run, and will attempt to find the packages which are
required to be installed first and do so in the right order.
<p>

However, this process is slow (because it requires repeated
invocations of <prgn/dpkg/) and troublesome (because it requires
guessing where to find the appropriate files).
<p>

For these reasons, and because this field imposes restrictions on the
order in which packages may be unpacked (which can be difficult for
installations from multipart media, for example), <tt/Pre-Depends/
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>

When the package declaring it is being configured, a
<tt/Pre-Dependency/ will be considered satisfied only if the depending
package has been correctly configured, just as if an ordinary
<tt/Depends/ had been used.
<p>

However, when a package declaring a predependency 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/ field.

</taglist>

<sect1>Deconfiguration due to removal during bulk installations
<p>

If <prgn/dpkg/ would like to remove a package due to a conflict, as
described above, but this would violate a dependency of some other
package on the system, <prgn/dpkg/ will usually not remove the
conflicting package and halt with an error.
<p>

However, if the <tt/--auto-deconfigure/ (<tt/-B/) option is used
<prgn/dpkg/ will automatically `deconfigure' the package with the
problematic dependency, so that the conflicting package can be removed
and the package we're trying to install can be installed.  If
<prgn/dpkg/ is being asked to install packages (rather than just
unpacking them) it will try to reconfigure the package when it has
unpacked all its arguments, in the hope that one of the other packages
it is installing will satisfy the problematic dependency.
<p>

<prgn/dselect/ supplies this argument to <prgn/dpkg/ when it invokes it,
so that bulk installations proceed smoothly.

<sect id="conflicts">Alternative packages - <tt/Conflicts/ and <tt/Replaces/
<p>

When one package declares a conflict with another <prgn/dpkg/ will
refuse to allow them to be installed on the system at the same time.
<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/, then
<prgn/dpkg/ will automatically remove the package which is causing the
conflict, otherwise it will halt the installation of the new package
with an error.
<p>

<prgn/dselect/ makes it hard to select conflicting packages, though the
user can override this if they wish.  If they do not override it then
<prgn/dselect/ will select one of the packages for removal, and the user
must make sure it is the right one.  In the future <prgn/dselect/ will
look for the presence of a <tt/Replaces/ field to help decide which
package should be installed and which removed.
<p>

A package will not cause a conflict merely because its configuration
files are still installed; it must be at least half-installed.
<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>

A <tt/Conflicts/ entry should almost never have an `earlier than'
version clause.  This would prevent <prgn/dpkg/ from upgrading or
installing the package which declared such a conflict until the
upgrade or removal of the conflicted-with package had been completed.
This aspect of installation ordering is not handled by <prgn/dselect/,
so that the use <tt/Conflicts/ in this way is likely to cause problems
for `bulk run' upgrades and installations.
<p>


<sect id="virtual">Virtual packages - <tt/Provides/
<p>

As well as the names of actual (`concrete') packages, the package
relationship fields <tt/Depends/, <tt/Recommends/, <tt/Suggests/ and
<tt/Conflicts/ may mention virtual packages.
<p>

A virtual package is one which appears in the <tt/Provides/ 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 were the virtual package name appears.
<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/ and <tt/vm/ packages are changed to
use it).
<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 virtual package is not of
the `right' version.  So, a <tt/Provides/ 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>

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 alternative before the virtual.
<p>


<sect id="replaces"><tt/Replaces/ - overwriting files and replacing packages
<p>

The <tt/Replaces/ control file field has two purposes, which come into
play in different situations.
<p>

Virtual packages (<ref id="virtual">) are not considered when looking
at a <tt/Replaces/ field - the packages declared as being replaced
must be mentioned by their real names.

<sect1>Overwriting files in other packages
<p>

Firstly, as mentioned before, it is usually an error for a package to
contains files which are on the system in another package, though
currently the <tt/--force-overwrite/ flag is enabled by default,
downgrading the error to a warning,
<p>

If the overwriting package declares that it replaces the one
containing the file being overwritten then <prgn/dpkg/ 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>

If a package is completely replaced in this way, so that <prgn/dpkg/
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/ script will be run to
allow the package to do any final cleanup required.
See <ref id="mscriptsinstact">.
<p>

In the future <prgn/dpkg/ will discard files which overwrite those from
another package which declares that it replaces the one being
installed (so that you can install an older version of a package
without problems).
<p>

This usage of <tt/Replaces/ 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.

<sect1>Replacing whole packages, forcing their removal
<p>

Secondly, <tt/Replaces/ allows <prgn/dpkg/ and <prgn/dselect/ to resolve
which package should be removed when a conflict - see
<ref id="conflicts">.  This usage only takes effect when the two
packages <em/do/ conflict, so that the two effects do not interfere
with each other.
<p>

<sect>Defaults for satisfying dependencies - ordering
<p>

Ordering is significant in dependency fields.
<p>

Usually dselect will suggest to the user that they select the package
with the most `fundamental' class (eg, it will prefer Base packages to
Optional ones), or the one that they `most wanted' to select in some
sense.
<p>

In the absence of other information <prgn/dselect/ will offer a
default selection of the first named package in a list of
alternatives.
<p>

However, there is no way to specify the `order' of several packages
which all provide the same thing, when that thing is listed as a
dependency.
<p>

Therefore a dependency on a virtual package should contain a concrete
package name as the first alternative, so that this is the default.
<p>

For example, consider the set of packages:

<example>
Package: glibcdoc
Recommends: info-browser

Package: info
Provides: info-browser

Package: emacs
Provides: info-browser
</example>
<p>

If <prgn/emacs/ and <prgn/info/ both have the same priority then
<prgn/dselect/'s choice is essentially random.  Better would be
<example>
Package: glibcdoc
Recommends: info | info-browser
</example>
so that <prgn/dselect/ defaults to selecting the lightweight standalone
info browser.



<chapt id="conffiles">Configuration file handling
<p>

<prgn/dpkg/ can do a certain amount of automatic handling of package
configuration files.
<p>

Whether this mechanism is appropriate depends on a number of factors,
but basically there are two approaches to any particular configuration
file.
<p>

The easy method is to ship a best-effort configuration in the package,
and use <prgn/dpkg/'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>

The hard method is to build the configuration file from scratch in the
<prgn/postinst/ 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.

<sect>Automatic handling of configuration files by <prgn/dpkg/
<p>

A package may contain a control area file called <tt/conffiles/.  This
file should be a list of filenames of configuration files needing
automatic handling, separated by newlines.  The filenames should be
absolute pathnames, and the files referred to should actually exist in
the package.
<p>

When a package is upgraded <prgn/dpkg/ will process the configuration
files during the configuration stage, shortly before it runs the
package's <prgn/postinst/ script,
<p>

For each file it checks to see whether the version of the file
included in the package is the same as the one that was included in
the last version of the package (the one that is being upgraded
from); it also compares the version currently installed on the system
with the one shipped with the last version.
<p>

If neither the user nor the package maintainer has changed the file,
it is left alone.  If one or the other has changed their version, then
the changed version is preferred - ie, if the user edits their file,
but the package maintainer doesn't ship a different version, the
user's changes will stay, silently, but if the maintainer ships a new
version and the user hasn't edited it the new version will be
installed (with an informative message).  If both have changed their
version the user is prompted about the problem and must resolve the
differences themselves.
<p>

The comparisons are done by calculating the MD5 message digests of the
files, and storing the MD5 of the file as it was included in the most
recent version of the package.
<p>

When a package is installed for the first time <prgn/dpkg/ will install
the file that comes with it, unless that would mean overwriting a file
already on the filesystem.
<p>

However, note that <prgn/dpkg/ will <em/not/ replace a conffile that
was removed by the user (or by a script).  This is necessary because
with some programs a missing file produces an effect hard or
impossible to achieve in another way, so that a missing file needs to
be kept that way if the user did it.
<p>

Note that a package should <em/not/ modify a <prgn/dpkg/-handled
conffile in its maintainer scripts.  Doing this will lead to
<prgn/dpkg/ giving the user confusing and possibly dangerous options
for conffile update when the package is upgraded.

<sect>Fully-featured maintainer script configuration handling
<p>

For files which contain site-specific information such as the hostname
and networking details and so forth, it is better to create the file
in the package's <prgn/postinst/ script.
<p>

This will typically involve examining the state of the rest of the
system to determine values and other information, and may involve
prompting the user for some information which can't be obtained some
other way.
<p>

When using this method there are a couple of important issues which
should be considered:
<p>

If you discover a bug in the program which generates the configuration
file, or if the format of the file changes from one version to the
next, you will have to arrange for the postinst script to do something
sensible - usually this will mean editing the installed configuration
file to remove the problem or change the syntax.  You will have to do
this very carefully, since the user may have changed the file, perhaps
to fix the very problem that your script is trying to deal with - you
will have to detect these situations and deal with them correctly.
<p>

If you do go down this route it's probably a good idea to make the
program that generates the configuration file(s) a separate program in
<tt>/usr/sbin</>, by convention called <tt/<var/package/config/ and
then run that if appropriate from the post-installation script.  The
<tt/<var/package/config/ program should not unquestioningly overwrite
an existing configuration - if its mode of operation is geared towards
setting up a package for the first time (rather than any arbitrary
reconfiguration later) you should have it check whether the
configuration already exists, and require a <tt/--force/ flag to
overwrite it.



<chapt id="alternatives">Alternative versions of an interface -
<prgn/update-alternatives/
<p>

When several packages all provide different versions of the same
program or file it is useful to have the system select a default, but
to allow the system administrator to change it and have their
decisions respected.
<p>

For example, there are several versions of the <prgn/vi/ editor, and
there is no reason to prevent all of them from being installed at
once, each under their own name (<prgn/nvi/, <prgn/vim/ or whatever).
Nevertheless it is desirable to have the name <tt/vi/ refer to
something, at least by default.
<p>

If all the packages involved cooperate, this can be done with
<prgn/update-alternatives/.
<p>

Each package provides its own version under its own name, and calls
<prgn/update-alternatives/ in its postinst to register its version
(and again in its prerm to deregister it).
<p>

See the manpage <manref name=update-alternatives section=8> for
details.
<p>

If <prgn/update-alternatives/ does not seem appropriate you may wish
to consider using diversions instead.


<chapt id="diversions">Diversions - overriding a package's version of a file
<p>

It is possible to have <prgn/dpkg/ not overwrite a file when it
reinstalls the package it belongs to, and to have it put the file from
the package somewhere else instead.
<p>

This can be used locally to override a package's version of a file, or
by one package to override another's version (or provide a wrapper for
it).
<p>

Before deciding to use a diversion, read <ref id="alternatives"> to
see if you really want a diversion rather than several alternative
versions of a program.
<p>

There is a diversion list, which is read by <prgn/dpkg/, and updated
by a special program <prgn/dpkg-divert/.  Please see <manref
name=dpkg-divert section=8> for full details of its operation.
<p>

When a package wishes to divert a file from another, it should call
<prgn/dpkg-divert/ in its preinst to add the diversion and rename the
existing file.  For example, supposing that a <prgn/smailwrapper/
package wishes to install a wrapper around <tt>/usr/sbin/smail</>:
<example>
if [ install = "$1" ]; then
    dpkg-divert --package smailwrapper --add --rename \
		--divert /usr/sbin/smail.real /usr/sbin/smail
fi
</example>
Testing <tt/$1/ is necessary so that the script doesn't try to add the
diversion again when <prgn/smailwrapper/ is upgraded.  The
<tt/--package smailwrapper/ ensures that <prgn/smailwrapper/'s copy of
<tt>/usr/sbin/smail</> can bypass the diversion and get installed as
the true version.
<p>

The postrm has to do the reverse:
<example>
if [ remove = "$1" ]; then
    dpkg-divert --package smailwrapper --remove --rename \
                --divert /usr/sbin/smail.real /usr/sbin/smail
fi
</example>
<p>

Do not attempt to divert a file which is vitally important for the
system's operation - when using <prgn/dpkg-divert/ there is a time,
after it has been diverted but before <prgn/dpkg/ has installed the
new version, when the file does not exist.


<chapt id="sharedlibs">Shared libraries
<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>

Firstly, your package should install the shared libraries under their
normal names.  For example, the <prgn/libgdbm1/ package should install
<tt/libgdbm.so.1.7.3/ as <tt>/usr/lib/libgdbm.so.1.7.3</tt>.  The
files should not be renamed or relinked by any prerm or postrm
scripts; <prgn/dpkg/ will take care of renaming things safely without
affecting running programs, and attempts to interfere with this are
likely to lead to problems.
<p>

Secondly, your package should include the symlink that <prgn/ldconfig/
would create for the shared libraries.  For example, the <prgn/libgdbm1/
package should include a symlink from <tt>/usr/lib/libgdbm.so.1</tt>
to <tt/libgdbm.so.1.7.3/.  This is needed so that <prgn/ld.so/ can find
the library in between the time <prgn/dpkg/ installs it and
<prgn/ldconfig/ is run in the <prgn/postinst/ script.  Futhermore, and <em/this
is very important/, the symlink must be placed before the library it
points to in the <tt/.deb/ file.  Currently the way to ensure the
ordering is done properly is to create the symlink in the appropriate
<tt>debian/tmp/.../lib</tt> directory before installing the library
when you build the package.
<p>

If you do the above your package does not need to call <prgn/ldconfig/
in its maintainer scripts.  It is especially important not to call
<prgn/ldconfig/ in the postrm or preinst scripts in the case where the
package is being upgraded (see the programmer's manual), as
<prgn/ldconfig/ will see the temporary names that <prgn/dpkg/ uses for the
files while it is installing them and will make the shared library
links point to them, just before <prgn/dpkg/ continues the installation
and removes the links!



<chapt id="sysvinit">Configuration of <prgn/init/
<p>

<sect>Introduction to the <tt/init.d/ scheme
<p>

The <tt>/etc/init.d</> directory contains the scripts executed by
<prgn/init/ when init state (or `runlevel') is changed (see <manref
name=init section=8>).
<p>

These scripts are be referenced by symbolic links in the
<tt>/etc/rc<var/n/.d</> directories.  When changing runlevels, init
looks in the directory <tt>/etc/rc<var/n/.d</> for the scripts it
should execute, where <var/n/ is the runlevel that is being changed
to.
<p>

The names of the links all have the form <tt/S<var/mm/<var/script// or
<tt/K<var/mm/<var/script// where <var/mm/ is a two-digit number and
<var/script/ is the name of the script (this should be the same as the
name of the actual script in <tt>/etc/init.d</>.

When <prgn/init/ changes runlevel first the targets of the links whose
names starting with a <tt/K/ are executed, each with the single
argument <tt/stop/, followed by the scripts prefixed with an <tt/S/,
each with the single argument <tt/start/.  The <tt/K/ links are
responsible for killing services and the <tt/S/ link for starting
services upon entering the runlevel.
<p>

For example, if we are changing from runlevel 2 to runlevel 3, init
will first execute all of the <tt/K/ prefixed scripts it finds in
<tt>/etc/rc3.d</>, and then all of the <tt/S/ prefixed scripts.  The
links starting with <tt/K/ will cause the referred-to file to be
executed with an argument of <tt/stop/, and the <tt/S/ links with an
argument of <tt/start/.
<p>

The two-digit number <var/mm/ is used to decide which order to start
and stop things in - low-numbered links have their scripts run first.
For example, the <tt/K20/ scripts will be executed before the <tt/K30/
scripts.  This is used when a certain service must be started before
another.  For example, the name server <prgn/bind/ might need to be
started before the news server <prgn/inn/ so that <prgn/inn/ can set
up its access lists.  In this case, the script that starts <prgn/bind/
should have a lower number than the script that starts <prgn/inn/ so
that it runs first:
<example>
/etc/rc2.d/S17bind
/etc/rc2.d/S70inn
</example>

<sect>Writing <tt/init.d/ scripts
<p>

Packages can and should place scripts in <tt>/etc/init.d</> to start
or stop services at boot time or during a change of runlevel.  These
scripts should be named <tt>/etc/init.d/<var/package/</>, and they
should accept one argument, saying what to do: <tt/start/, meaning to
starts the service, or <tt/stop/, to stop the service.  Optionally
they can support <tt/reload/ which causes the configuration to be
reloaded.
<p>

The <tt/init.d/ scripts should ensure that they will behave sensibly
if invoked with <tt/start/ when the service is already running, or
with <tt/stop/ when it isn't, and that they don't kill
unfortunately-named user processes.  The best way to achieve this is
usually to use <prgn/start-stop-daemon/.
<p>

These scripts should not fail obscurely when the configuration files
remain but the package has been removed, as the default in <prgn/dpkg/
is to leave configuration files on the system after the package has
been removed.  Only when it is executed with the <tt/--purge/ option
will dpkg remove configuration files.  Therefore, you should include a
<tt/test/ statement at the top of the script, like this:
<example>
test -f <var/program-executed-later-in-script/ || exit 0
</example>

<sect>Managing the <tt/rc<var/n/.d/ links - <prgn/update-rc.d/
<p>

A program is provided, <prgn/update-rc.d/, to make it easier for
package maintainers to arrange for the proper creation and removal of
<tt>/etc/rc<var/n/.d</> symbolic links from their postinst and postrm
scripts.
<p>

You should use this script to make changes to <tt>/etc/rc<var/n/.d</>
and <em/never/ include any <tt>/etc/rc<var/n/.d</> symbolic links in
the actual archive.
<p>

By default <prgn/update-rc.d/ will start services in each of the
multi-user state runlevels (2, 3, 4, and 5) and stop them in the halt
runlevel (0), the single-user runlevel (1) and the reboot runlevel
(6).  The system administrator will have the opportunity to customize
runlevels by simply adding, moving, or removing the symbolic links in
<tt>/etc/rc<var/n/.d</>.
<p>

To get the default behaviour for your package, put in your postinst
script
<example>
update-rc.d <var/package/ default &gt;/dev/null
</example>
and in your postrm
<example>
if [ purge = "$1" ]; then
    update-rc.d <var/package/ remove &gt;/dev/null
fi
</example>
<p>

This will use a default sequence number of 20.  If it does not matter
when or in which order the script is run, use this default.  If it
does, then you should talk to the maintainer of the <prgn/sysvinit/
package or post to <tt>debian-devel</>, and they will help you choose
a number.
<p>

For more information about using <tt/update-rc.d/, please consult its
manpage <manref name=update-rc.d section=8>.

<sect>Boot-time initialisation - <tt/rc.boot/
<p>

There is another directory, <tt>/etc/rc.boot</>, which contains
scripts which are run once per machine boot.  This facility is
provided for initialisation of hardware devices, cleaning up of
leftover files, and so forth.
<p>

For example, the <prgn/kbd/ package provides a script here for
initialising the keyboard layout and console font and mode.
<p>

The files in <tt>/etc/rc.boot</> should <em/not/ be links into
<tt>/etc/init.d</> - they should be the scripts themselves.
<p>

<tt/rc.boot/ should <em/not/ be used for starting general-purpose
daemons and similar activities.  This should be done using the
<tt/rc<var/n/.d/ scheme, above, so that the services can be started
and stopped cleanly when the runlevel changes or the machine is to be
shut down or rebooted.

<sect>Notes
<p>

<em/Do not/ include the <tt>/etc/rc<var/n/.d/*</> symbolic links in
the <tt/.deb/ filesystem archive!  <em/This will cause problems!/
You should create them with <prgn/update-rc.d/, as above.
<p>

<em/Do not/ include the <tt>/etc/rc<var/n/.d/*</> symbolic links in
<prgn/dpkg/'s conffiles list!  <em/This will cause problems!/
<em/Do/, however, include the <tt>/etc/init.d</> scripts in conffiles.

<sect>Example
<p>

The <prgn/bind/ DNS (nameserver) package wants to make sure that the
nameserver is running in multiuser runlevels, and is properly shut
down with the system.  It puts a script in <tt>/etc/init.d</>, naming
the script appropriately <tt/bind/.  As you can see, the script
interprets the argument <tt/reload/ to send the nameserver a <tt/HUP/
signal (causing it to reload its configuration); this way the user can
say <tt>/etc/init.d/bind reload</> to reload the nameserver.
<p>

<example>
#!/bin/sh
# Original version by Robert Leslie &lt;rob@mars.org&gt;, edited by iwj
test -x /usr/sbin/named || exit 0
case "$1" in
  start)
    test -f /etc/named.boot -a -f /var/named/boot.options || exit 0
    start-stop-daemon --start --verbose --exec /usr/sbin/named
    ;;
  stop)
    start-stop-daemon --stop --verbose  \
        --pidfile /var/run/named.pid --exec /usr/sbin/named
    ;;
  reload)
    start-stop-daemon --stop --signal 1 --verbose  \
        --pidfile /var/run/named.pid --exec /usr/sbin/named
    ;;
  *)
    echo "Usage: /etc/init.d/bind {start|stop|reload}" >&2
    exit 1
    ;;
esac
exit 0
</example>
<p>

Another example on which to base your <tt>/etc/init.d</> scripts is in
<tt>/etc/init.d/skeleton</>.
<p>

If this package is happy with the default setup from
<prgn/update-rc.d/, namely an ordering number of 20 and having named
running in all runlevels, it can say in its postinst:
<example>
update-rc.d bind default >/dev/null
</example>
And in its postrm, to remove the links when the package is purged:
<example>
if [ purge = "$1" ]; then
     update-rc.d acct remove >/dev/null
fi
</example>



<chapt id="methif"><prgn/dselect/'s interface to its installation methods
<p>

<prgn/dselect/ calls scripts from its installation methods when it
needs to actually access data from the distribution.  The core program
<prgn/dselect/ itself just calls these scripts and provides the
package and access method selection interfaces.  The installation
methods are responsible for invoking <prgn/dpkg/ as appropriate.
<p>

Each installation method has three scripts:
<list compact>
<item>Setup installation parameters.
<item>Update list of available packages.
<item>Install.
</list>
<p>

<prgn/dselect/ searches for methods in <tt>/usr/lib/dpkg/methods</>
and <tt>/usr/local/lib/dpkg/methods</>.

<sect>Functions of the method scripts
<p>

The setup script is run just after the user has chosen an installation
method.  It should prompt the user for parameters like the site to
NFS-mount or FTP from, the directory to use, or the directory or
filesystem where the <tt/.deb/ files can be found, or the tape or
floppy device to install from.  It should store the responses under
<tt>/var/lib/dpkg/methods</> - see below.  If no available
packages list is available it should perhaps offer to scan the
available packages.
<p>

The update script should obtain a list of available packages if
possible, and run <tt/dpkg --update-avail/, <tt/dpkg --merge-avail/
and/or <tt/dpkg --forget-old-unavail/ to load it into <prgn/dpkg/ and
<prgn/dselect/'s database of available packages.  If no packages list
was available and the user was offered and accepted the option of
scanning the actual files available this scan should be done here,
using <tt/dpkg --record-avail/.
<p>

The install script should feed all the available <tt/.deb/ files to
<tt/dpkg --iGOEB/ (this is equivalent to <tt/dpkg --install
--refuse-downgrade --selected-only --skip-same-version
--auto-deconfigure/).  The <tt/-R/ (<tt/--recursive/) option for
traversing subdirectories may also be useful here).
<p>

If any of these scripts needs to display a message for the user, it
should wait for the user to hit `return' before exiting so that
dselect doesn't immediately rewrite the screen.
<p>

If a method script succeeds (returns a zero exit status)
<prgn/dselect/ will return immediately to the main menu, with the
`next' option highlighted ready for the user to select it.  If it
fails <prgn/dselect/ will display a message and wait for the user to
hit return.

<sect>Location and arguments of the method scripts
<p>

A set of scripts (henceforth known as a group) may provide several
methods on the `main menu' with different behaviour.  For example,
there might be a generic get-packages-by-FTP group which might provide
methods in the main menu for installation directly from one of the
Debian mirror sites as well as for installation from a user-specified
site.
<p>

Each group of methods implemented by the same set of scripts should
have a subdirectory <tt>/usr/lib/dpkg/methods/<var/group/</> or
<tt>/usr/local/lib/dpkg/methods/<var/group/</>, containing:
<taglist compact>
<tag><tt/names/
<item>a list of user-visible methods provided by these scripts.
<tag><tt/setup/
<tag><tt/update/
<tag><tt/install/
<item>executable programs, the scripts themselves.
<tag><tt/desc.<var/option//
<item>description file.
</taglist>
<p>

<tt/names/ will be formatted as a list of lines, each containing:
<example>
<var/sequence/ <var/method/ <var/summary/
</example>
<p>

<var/sequence/ is a two-digit number that will be used much like
<tt/rc.d/ prefixes to control the order in the main menu.  If in doubt
use 50.
<p>

<var/method/ is a name which is displayed by <prgn/dselect/ as the
name of the method, and which will be passed to <tt/setup/,
<tt/update/ and <tt/unpack/ as their first argument.
<p>

<var/summary/ is the brief description string for <prgn/dselect/'s menu.
<p>

Each of the three scripts gets the same three arguments: <var/vardir/,
<var/group/ and <var/method/.  <var/vardir/ is the base directory for
storing <prgn/dpkg/ and <prgn/dselect/'s state, usually
<tt>/var/lib/dpkg</>; this is passed in so that the <tt/--admindir/
option to <prgn/dselect/ is honoured).
<p>

Each option may have an extended description in
<tt/desc.<var/option//.  This should be formatted like the extended
description part of a <tt/Description/ field entry <em/shifted one
character to the left/.
<p>

<tt><var/vardir//methods</> will exist, and a method group may use a
<tt><var/vardir//methods/<var/group/</> directory to store its state.
<p>

The group name and method name must follow the rules for C identifiers.

</book>