Initial revision

[debian/debian-policy.git] / packaging.sgml

<!doctype debiandoc system>

<!--
 Debian GNU/Linux Packaging Manual.
 Copyright (C)1996 Ian Jackson; released under the terms of the GNU
 General Public License, version 2 or (at your option) any later.
 Revised: David A. Morris (bweaver@debian.org)
 Maintainer since 1998, Christian Schwarz <schwarz@debian.org>
 -->

<book>

<title>Debian Packaging Manual
<author>Ian Jackson <email/ijackson@gnu.ai.mit.edu/
<author>Revised: David A. Morris <email/bweaver@debian.org/
<author>Maintainer: Christian Schwarz <email/schwarz@debian.org/
<version>version 2.4.1.0, 14 April 1998

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

A copy of the GNU General Public License is available as
<tt>/usr/doc/copyright/GPL</tt> in the Debian GNU/Linux
distribution or on the World Wide Web at
<tt>http://www.gnu.org/copyleft/gpl.html</tt>. You can also obtain it
by writing to the Free Software Foundation, Inc., 59 Temple Place -
Suite 330, Boston, MA 02111-1307, USA.
<p>

<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.  Unfortunately this manual
does not yet exist.
<p>

The Debian version of the FSF's GNU hello program is provided as an
example for people wishing to create Debian packages. The Debian
<prgn/debmake/ package is recommended as a very helpful tool in
creating and maintaining Debian packages. However, while the tools and
examples are helpful, they do not replace the need to read and follow
the Policy and Programmer's Manual.

<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 containing the files and directories to
be installed. 
<p>

In the future binary packages may also contain other components, such
as checksums and digital signatures. The format for the archive is
described in full in the <tt>deb(5)</> manpage.


<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
dpkg --contents <var/filename/.deb
</example>
To view the copyright file for a package you could use this command:
<example>
dpkg --fsys-tarfile <var/filename/.deb | tar xof usr/doc/<var/\*/copyright | less
</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">.
<p>

It is usually generated automatically from information in the source
package by the <prgn/dpkg-gencontrol/ program, and with assistance
from <prgn/dpkg-shlibdeps/.  See <ref id="sourcetools">.

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

<tag><tt/shlibs/
<item>

This file contains a list of the shared libraries supplied by the
package, with dependency details for each.  This is used by
<prgn/dpkg-shlibdeps/ when it determines what dependencies are
required in a package control file. The <tt/shlibs/ file format is 
described on <ref id="shlibs">.
<p>

</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/</>
<item><qref id="f-Installed-Size"><tt/Installed-Size/</>

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

There was a previous version of the Debian source format, which is now
being phased out.  Instructions for converting an old-style package
are given in the Debian policy manual.

<sect id="sourcetools">Tools for processing source packages
<p>

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

They are introduced and typical uses described here; see <manref
name=dpkg-source section=1> for full documentation about their
arguments and operation.
<p>

For examples of how to construct a Debian source package, and how to
use those utilities that are used by Debian source packages, please
see the <prgn/hello/ example package.

<sect1><prgn/dpkg-source/ - packs and unpacks Debian source packages
<p>

This program is frequently used by hand, and is also called from
package-independent automated building scripts such as
<prgn/dpkg-buildpackage/.
<p>

To unpack a package it is typically invoked with
<example>
dpkg-source -x <var>.../path/to/filename</>.dsc
</example>
with the <tt/<var/filename/.tar.gz/ and
<tt/<var/filename/.diff.gz/ (if applicable) in the same directory.  It
unpacks into <tt/<var/package/-<var/version//, and if applicable
<tt/<var/package/-<var/version/.orig/, in the current directory.
<p>

To create a packed source archive it is typically invoked:
<example>
dpkg-source -b <var/package/-<var/version/
</example>
This will create the <tt/.dsc/, <tt/.tar.gz/ and <tt/.diff.gz/ (if
appropriate) in the current directory.  <prgn/dpkg-source/ does not
clean the source tree first - this must be done separately if it is
required.
<p>

See also <ref id="sourcearchives">.


<sect1><prgn/dpkg-buildpackage/ - overall package-building control
script
<p>

<prgn/dpkg-buildpackage/ is a script which invokes <prgn/dpkg-source/,
the <tt>debian/rules</> targets <prgn/clean/, <prgn/build/ and
<prgn/binary/, <prgn/dpkg-genchanges/ and <prgn/pgp/ to build a signed
source and binary package upload.
<p>

It is usually invoked by hand from the top level of the built or
unbuilt source directory.  It may be invoked with no arguments; useful
arguments include:
<taglist compact>
<tag><tt/-uc/, <tt/-us/
<item>Do not PGP-sign the <tt/.changes/ file or the source package
<tt/.dsc/ file, respectively.

<tag><tt/-p<var/pgp-command//
<item>Invoke <var/pgp-command/ instead of finding <tt/pgp/ on the
<prgn/PATH/.  <var/pgp-command/ must behave just like <prgn/pgp/.

<tag><tt/-r<var/root-command//
<item>When root privilege is required, invoke the command
<var/root-command/.  <var/root-command/ should invoke its first
argument as a command, from the <prgn/PATH/ if necessary, and pass its
second and subsequent arguments to the command it calls.  If no
<var/root-command/ is supplied then <var/dpkg-buildpackage/ will take
no special action to gain root privilege, so that for most packages it
will have to be invoked as root to start with.

<tag><tt/-b/, <tt/-B/
<item>Two types of binary-only build and upload - see <manref
name=dpkg-source section=1>.
</taglist>


<sect1><prgn/dpkg-gencontrol/ - generates binary package control files
<p>

This program is usually called from <tt>debian/rules</> (see <ref
id="sourcetree">) in the top level of the source tree.
<p>

This is usually done just before the files and directories in the
temporary directory tree where the package is being built have their
permissions and ownerships set and the package is constructed using
<prgn/dpkg-deb/<footnote>This is so that the control file which is
produced has the right permissions</footnote>.
<p>

<prgn/dpkg-gencontrol/ must be called after all the files which are to
go into the package have been placed in the temporary build directory,
so that its calculation of the installed size of a package is correct.
<p>

It is also necessary for <prgn/dpkg-gencontrol/ to be run after
<prgn/dpkg-shlibdeps/ so that the variable substitutions created by
<prgn/dpkg-shlibdeps/ in <tt>debian/substvars</> are available.
<p>

For a package which generates only one binary package, and which
builds it in <tt>debian/tmp</> relative to the top of the source
package, it is usually sufficient to call:
<example>
dpkg-gencontrol
</example>
<p>

Sources which build several binaries will typically need something
like:
<example>
dpkg-gencontrol -Pdebian/tmp-<var/pkg/ -p<var/package/
</example>
The <tt/-P/ tells <prgn/dpkg-gencontrol/ that the package is being
built in a non-default directory, and the <tt/-p/ tells it which
package's control file should be generated.
<p>

<prgn/dpkg-gencontrol/ also adds information to the list of files in
<tt>debian/files</>, for the benefit of (for example) a future
invocation of <prgn/dpkg-genchanges/.


<sect1><prgn/dpkg-shlibdeps/ - calculates shared library dependencies
<p>

This program is usually called from <tt>debian/rules</> just before
<prgn/dpkg-gencontrol/ (see <ref id="sourcetree">), in the top level
of the source tree.
<p>

Its arguments are executables<footnote>They may be specified either
in the locations in the source tree where they are created or in the
locations in the temporary build tree where they are installed prior
to binary package creation.</footnote> for which shared library
dependencies should be included in the binary package's control file.
<p>

If some of the executable(s) shared libraries should only warrant a
<tt/Recommends/ or <tt/Suggests/, or if some warrant a
<tt/Pre-Depends/, this can be achieved by using the
<tt/-d<var/dependency-field// option before those executable(s).
(Each <tt/-d/ option takes effect until the next <tt/-d/.)
<p>

<prgn/dpkg-shlibdeps/ does not directly cause the output control file
to be modified.  Instead by default it adds to the
<tt>debian/substvars</> file variable settings like
<tt/shlibs:Depends/.  These variable settings must be referenced in
dependency fields in the appropriate per-binary-package sections of
the source control file.
<p>

For example, the <prgn/procps/ package generates two kinds of
binaries, simple C binaries like <prgn/ps/ which require a
predependency and full-screen ncurses binaries like <prgn/top/ which
require only a recommendation.  It can say in its <tt>debian/rules</>:
<example>
dpkg-shlibdeps -dPre-Depends ps -dRecommends top
</example>
and then in its main control file <tt>debian/control</>:
<example>
<var/.../
Package: procps
Pre-Depends: ${shlibs:Pre-Depends}
Recommends: ${shlibs:Recommends}
<var/.../
</example>
<p>

Sources which produce several binary packages with different shared
library dependency requirements can use the <tt/-p<var/varnameprefix//
option to override the default <tt/shlib:/ prefix (one invocation of
<prgn/dpkg-shlibdeps/ per setting of this option).  They can thus
produce several sets of dependency variables, each of the form
<tt/<var/varnameprefix/:<var/dependencyfield//, which can be referred
to in the appropriate parts of the binary package control files.


<sect1><prgn/dpkg-distaddfile/ - adds a file to <tt>debian/files</>
<p>

Some packages' uploads need to include files other than the source and
binary package files.
<p>

<prgn/dpkg-distaddfile/ adds a file to the <tt>debian/files</> file so
that it will be included in the <tt/.changes/ file when
<prgn/dpkg-genchanges/ is run.
<p>

It is usually invoked from the <prgn/binary/ target of
<tt>debian/rules</>:
<example>
dpkg-distaddfile <var/filename/ <var/section/ <var/priority/
</example>
The <var/filename/ is relative to the directory where
<prgn/dpkg-genchanges/ will expect to find it - this is usually the
directory above the top level of the source tree.  The
<tt>debian/rules</> target should put the file there just before or
just after calling <prgn/dpkg-distaddfile/.
<p>

The <var/section/ and <var/priority/ are passed unchanged into the
resulting <tt/.changes/ file.  See <ref id="f-classification">.


<sect1><prgn/dpkg-genchanges/ - generates a <tt/.changes/ upload
control file
<p>

This program is usually called by package-independent automatic
building scripts such as <prgn/dpkg-buildpackage/, but it may also be
called by hand.
<p>

It is usually called in the top level of a built source tree, and when
invoked with no arguments will print out a straightforward
<tt/.changes/ file based on the information in the source package's
changelog and control file and the binary and source packages which
should have been built.


<sect1><prgn/dpkg-parsechangelog/ - produces parsed representation of
a changelog
<p>

This program is used internally by <prgn/dpkg-source/ et al.  It may
also occasionally be useful in <tt>debian/rules</> and elsewhere.  It
parses a changelog, <tt>debian/changelog</> by default, and prints a
control-file format representation of the information in it to
standard output.

<sect id="sourcetree">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/, <tt/binary-arch/, <tt/binary-indep/
<item>

The <prgn/binary/ target should be all that is necessary for the user
to build the binary package.  It is split into two parts:
<prgn/binary-arch/ builds the packages' output files which are
specific to a particular architecture, and <prgn/binary-indep/
builds those which are not.
<p>

<prgn/binary/ should usually be a target with no commands which simply
depends on <prgn/binary-arch/ and <prgn/binary-indep/.
<p>

Both <prgn/binary-*/ targets 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 relevant 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>

If one of the <prgn/binary-*/ targets has nothing to do (this will be
always be the case if the source generates only a single binary
package, whether architecture-dependent or not) it <em/must/ still
exist, but should always succeed.
<p>

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

The <prgn/binary/ targets 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/ (optional)/
<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:
<p>
<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. 
<p> 
<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<footnote>This is generated
by the <prgn/822-date/ program.</footnote>; 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:
<tt>\schangelog-format:\s+([0-9a-z]+)\W</tt>
The part in parentheses should be the name of the format.  For
example, you might say:
<example>
@@@ changelog-format: joebloggs @@@
</example>
Changelog format names are non-empty strings of alphanumerics.
<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 is usually generated and modified dynamically by
<tt>debian/rules</> targets; in this 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/upstream_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 hard links<footnote>This is not
currently detected when building source packages, but only when
extracting them.</footnote><footnote>Hard links may be permitted at
some point in the future, but would require a fair amount of
work.</footnote>, 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>
<item>Changed text files which are missing the usual final newline
(either in the original or the modified source tree).
</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-Installed-Size"><tt/Installed-Size/
<p>

This field appears in the control files of binary packages, and in the
<tt/Packages/ files.  It gives the total amount of disk space
required to install the named package.
<p>

The disk space is represented in kilobytes as a simple decimal number.

<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 (if applicable)
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 in a <tt/.changes/ file
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/-/.
<p>

If a new Debian revision of a package is being shipped and no new
original source archive is being distributed the <tt/.dsc/ must still
contain the <tt/Files/ field entry for the original source archive
<tt/<var/package/-<var/upstream-version/.orig.tar.gz/, but the
<tt/.changes/ file should leave it out.  In this case the original
source archive on the distribution site must match exactly,
byte-for-byte, the original source archive which was used to generate
the <tt/.dsc/ file and diff which are being uploaded.


<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:
<taglist>
<tag/<em/stable//
<item>
This is the current `released' version of Debian GNU/Linux.  A new
version is released approximately every 3 months after the
<em/development/ code has been <em/frozen/ for a month of testing.
Once the distribution is <em/stable/ only major bug fixes are
allowed. When changes are made to this distribution, the minor version
number is increased (for example: 1.2 becomes 1.2.1 then 1.2.2, etc).

<tag/<em/unstable//
<item>
This distribution value refers to the <em/developmental/ part of the Debian
distribution tree. New packages, new upstream versions of packages and
bug fixes go into the <em/unstable/ directory tree. Download
from this distribution at your own risk.

<tag/<em/contrib//
<item>
The packages with this distribution value do not meet the criteria for
inclusion in the main Debian distribution as defined by the Policy
Manual, but meet the criteria for the <em/contrib/ Distribution. There
is currently no distinction between stable and unstable packages in
the <em/contrib/ or <em/non-free/ distributions. Use your best
judgement in downloading from this Distribution.

<tag/<em/non-free//
<item>
Like the packages in the <em/contrib/ seciton, the packages in
<em/non-free/ do not meet the criteria for inclusion in the main
Debian distribution as defined by the Policy Manual. Again, use your
best judgement in downloading from this Distribution.

<tag/<em/experimental//
<item>
The packages with this distribution value are deemed by their
maintainers to be high risk. Oftentimes they represent early beta or
developmental packages from various sources that the maintainers want
people to try, but are not ready to be a part of the other parts of
the Debian distribution tree. Download at your own risk.

<tag/<em/frozen//
<item>
From time to time, (currently, every 3 months) the <em/unstable/
distribution enters a state of `code-freeze' in anticipation of
release as a <em/stable/ version. During this period of testing
(usually 4 weeks) only fixes for existing or newly-discovered bugs
will be allowed.

</taglist>
<p>
You should list <em/all/ distributions that the package should be
installed into. Except in unusual circumstances, installations to
<em/stable/ should also go into <em/frozen/ (if it exists) and
<em/unstable/. Likewise, installations into <em/frozen/ should also go
into <em/unstable/.

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

If you need to compare version numbers ina script, you may use
<tt>dpkg --compare-versions ...</>. Type <tt>dpkg --help</> -->
--for details on arguments.

<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.
<p>
<!--
 next paragraph by Guy Maor to close bug #2481
 --> 

Programs called from maintainer scripts should not normally have a
path prepended to them. Before installation is started <prgn/dpkg/
checks to see if the programs <prgn/ldconfig/,
<prgn/start-stop-daemon/, <prgn/install-info/, and <prgn/update-rc.d/
can be found via the <tt/PATH/ environment variable. Those programs,
and any other program that one would expect to on the <tt/PATH/,
should thus be invoked without an absolute pathname. Maintainer
scripts should also not reset the <tt/PATH/, though they might choose
to modify it by pre- or appending package-specific directories. These
considerations really apply to all shell scripts.

<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 id="unpackphase">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>

It is a more serious error for a package to contain a plain file or
other kind of nondirectory where another package has a directory
(again, unless <tt/Replaces/ is used).  This error can be overridden
if desired using <tt/--force-overwrite-dir/, but this is not advisable.
<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>
<p>

A directory will never be replaced by a symbolic links to a directory
or vice versa; instead, the existing state (symlink or not) will be
left alone and <prgn/dpkg/ will follow the symlink if there is one.

<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
 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 id="depsyntax">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>

When selecting which level of dependency to use you should consider
how important the depended-on package is to the functionality of the
one declaring the dependency.  Some packages are composed of
components of varying degrees of importance.  Such a package should
list using <tt/Depends/ the package(s) which are required by the more
important components.  The other components' requirements may be
mentioned as Suggestions or Recommendations, as appropriate to the
components' relative importance.

<sect1>Dependencies on shared libraries
<p>

The dependency fields listed above are used by packages which need
shared libraries to declare dependencies on the appropriate packages.
<p>

These dependencies are usually determined automatically using
<prgn/dpkg-shlibdeps/ and inserted in the package control file using
the control file substitution variables mechanism; see <ref
id="srcsubstvars"> and <ref id="sourcetools">.

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

It is likely that the ability will be added in a future release of
<prgn/dpkg/ to specify a version number for each virtual package it
provides.  This feature is not yet present, however, and is expected
to be used only infrequently.
<p>

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 library must be placed before the symlink pointing to it in the
<tt/.deb/ file.  This is so that by the time <prgn/dpkg/ comes to
install the symlink (overwriting the previous symlink pointing at an
older version of the library) the new shared library is already in
place.  Currently the way to ensure the ordering is done properly is
to install the library in the appropriate <tt>debian/tmp/.../lib</>
directory before creating the symlink, by putting the commands in the
<tt>debian/rules</> in the appropriate order.
<p>

<!--
 next Paragraph added to close Bug #5299, Guy Maor
 -->

Thirdly, the development package should contain a symlink for the
shared library without a version number.  For example, the
<tt/libgdbm1-dev/ package should include a symlink from
<tt>/usr/lib/libgdm.so</> to <tt/libgdm.so.1.7.3/.  This symlink is
needed by <prgn/ld/ when compiling packages as it will only look for
<tt/libgdm.so/ and <tt/libgdm.a/ when compiling dynamically or
statically, respectively.
<p>

<!--
 next paragraph changed by Christian Schwarz (see policy weekly #6)
 -->

Any package installing shared libraries in a directory that's listed
in <tt>/etc/ld.so.conf</tt> or in one of the default library
directories of <prgn/ld.so/ (currently, these are <tt>/usr/lib</tt>
and <tt>/lib</tt>) must call <prgn/ldconfig/ in its <prgn/postinst/
script if and only if the first argument is `configure'. However, it
is important not to call <prgn/ldconfig/ in the postrm or preinst
scripts in the case where the package is being upgraded (see <ref
id="unpackphase">), 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!
<p>

<!-- 
 moved from section 2.2 , DMorris 
 -->

<sect id="shlibs">The <tt/shlibs/ File Format
<p>

This file is for use by <prgn/dpkg-shlibdeps/ and is required when
your package provides shared libraries.
<p>

Each line is of the form:
<example>
<var/library-name/ <var/version-or-soname/ <var/dependencies .../
</example>
<p>

<var/library-name/ is the name of the shared library, for example
<tt/libc5/.
<p>

<var/version-or-soname/ is the soname of the library - ie, the thing
that must exactly match for the library to be recognised by
<prgn/ld.so/.  Usually this is major version number of the library.
<p>

<var/dependencies/ has the same syntax as a dependency field in a
binary package control file.  It should give details of which
package(s) are required to satisfy a binary built against the version
of the library contained in the package.  See <ref id="depsyntax">.
<p>

For example, if the package <tt/foo/ contains <tt/libfoo.so.1.2.3/,
where the soname of the library is <tt/libfoo.so.1/, and the first
version of the package which contained a minor number of at least
<tt/2.3/ was <var/1.2.3-1/, then the package's <var/shlibs/ could
say:
<example>
libfoo 1        foo (>= 1.2.3-1)
</example>
<p>

The version-specific dependency is to avoid warnings from <prgn/ld.so/
about using older shared libraries with newer binaries.

<sect>Further Technical information on <tt/shlibs/</>

<!-- 
  following section mostly provided by Heiko Schlittermann
  edited by DMorris
 -->

<sect1><em/What/ are the <tt/shlibs/ files?
<p>

The <tt>debian/shlibs</> file provides a way of checking
for shared library dependencies on packaged binaries.  They are
intended to be used by package maintainers to make their lives easier.
<p>

Other <tt/shlibs/ files that exist on a Debian system are
<list>
<item> <tt>/etc/dpkg/shlibs.default</>
<item> <tt>/etc/dpkg/shlibs.override</>
<item> <tt>/var/lib/dpkg/info/*.shlibs</>
<item> <tt>debian/shlibs.local</>
</list>

These files are used by <prgn/dpkg-shlibdeps/ when creating a binary
package.

<sect1><em/How/ does <prgn/dpkg-shlibdeps/ work?
<p>

<prgn/dpkg-shlibdeps/ calls <prgn/ldd/ to determine the shared libraries
used by the compiled binaries passed through its command line.
<p>

For each shared library, <prgn/dpkg-shlibdeps/ needs to know 
<list compact>
<item>the package containing the library, and
<item>the library version number,
</list>
<p>
it scans the following files in this order.
<enumlist compact>
<item><tt>debian/shlibs.local</>
<item><tt>/etc/dpkg/shlibs.override</>
<item><tt>/var/lib/dpkg/info/*.shlibs</>
<item><tt>/etc/dpkg/shlibs.default</>
</enumlist>

<sect1><em/Who/ maintains the various <tt/shlibs/ files?
<p>

<list compact>
<item><tt>/etc/dpkg/shlibs.default</> - the maintainer of dpkg
<item><tt>/var/lib/dpkg/info/<var/package/.shlibs</> - the maintainer of each 
package
<item><tt>/etc/dpkg/shlibs.override</> - the local system administrator
<item><tt>debian/shlibs.local</> - the maintainer of the package
</list>

The <tt/shlibs.default/ file is managed by <prgn/dpkg/. The entries in
<tt/shlibs.default/ that are provided by <prgn/dpkg/ are just there to
fix things until the shared library packages all have <tt/shlibs/
files.

<sect1><em/How/ to use <prgn/dpkg-shlibdeps/ and the <tt/shlibs/ files?

<sect2>If your package doesn't provide a shared library
<p>

Put a call to <prgn/dpkg-shlibs/ into your <tt>debian/rules</> file.
If your package contains only binaries (e.g. no scripts) use:
<example>
dpkg-shlibdeps debian/tmp/usr/{bin,sbin}/*
</example>

If <prgn/dpkg-shlibdeps/ doesn't complain, you're done. If it does
complain you might need to create your own <tt>debian/shlibs.local</>
file.

<sect2>If your package provides a shared library
<p>

Create a <tt>debian/shlibs</> file and let <tt>debian/rules</> install
it in the control area:

<example>
install -m644 debian/shlibs debian/tmp/DEBIAN
</example>

If your package contains additional binaries see above.

<sect1><em/How/ to write <tt>debian/shlibs.local</>
<p>

This file is intended only as a <em/temporary/ fix if your binaries
depend on a library which doesn't provide its own
<tt>/var/lib/dpkg/*.shlibs</> file yet.
<p>

Let's assume you are packaging a binary <tt/foo/. Your output in
building the package might look like this.

<example>
$ ldd foo
libbar.so.1 => /usr/X11R6/lib/libbar.so.1.0
libc.so.5 => /lib/libc.so.5.2.18
libX11.so.6 => /usr/X11R6/lib/libX11.so.6.0
</example>

And when you ran <prgn/dpkg-shlibdeps/

<example>
$ dpkg-shlibdeps -o foo
dpkg-shlibdeps: warning: unable to find dependency information 
for shared library libbar 
(soname 1, path /usr/X11R6/lib/libbar.so.1.0, dependency field Depends)
shlibs:Depends=elf-x11r6lib, libc5 (>= 5.2.18)
</example>

The <prgn/foo/ binary depends on the <prgn/libbar/ shared library, but
no package seems to provide a <tt/*.shlibs/ file in
<tt//var/lib/dpkg/info/.  Let's determine the package responsible:
<p>

<example>
$ dpkg -S /usr/X11R6/lib/libbar.so.1.0
bar1: /usr/X11R6/lib/libbar.so.1.0
$ dpkg -s bar1 | grep Version
Version: 1.0-1
</example>

This tells us that the <prgn/bar1/ package, version 1.0-1 is the one
we are using. Now we can create our own <tt>debian/shlibs.local</> to
temporarly fix the above problem. Include the following line into your
<tt>debian/shlibs.local</> file.

<example>
    libbar 1 bar1 (>= 1.0-1)
</example>

Now your package build should work. As soon as the maintainer of
<prgn/libbar1/ provides a <tt/shlibs/ file, you can remove your
<tt>debian/shlibs.local</> file.

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

<chapt id="conversion">Conversion procedure from old source packages
<p>

This is a brief summary of the procedure for converting a
pre-2.0.0.0-format source package into the new format.
<p>

You are strongly advised to download and examine the <prgn/hello/
package, and to read the section in the <prgn/dpkg/ programmers'
manual describing the source packaging tools.  More detail about the
exact functionality of these tools is available in <manref
name=dpkg-source section=1>.
<p>

<list>

<item>
Download the original source code from wherever it can be found and do
any rearrangement required to make it look like the original tree of
the Debian source.  Put it in
<tt><var/package/-<var/upstream-version/.orig/</> or
<tt/<var/package/_<var/upstream-version/.orig.tar.gz/.

<item>
Rename all files <tt/debian.*/ to <tt>debian/*</>.  There may be some
exceptions to this, but this is a good start.

<item>
Edit the <tt>debian/changelog</> - create or rename it if necessary.
Add a new revision to the top with the appropriate details, and a
local variables entry to the bottom to set Emacs to the right mode:
<example>
Local variables:
mode: debian-changelog
End:
</example>

<item>
Edit/create <tt>debian/control</>:
<list compact>
<item>
Remove the <tt/Version/ field.  If it is generated unusually (not
equal to the source version) you must use the -v option to
dpkg-gencontrol (see below).  <tt/Section/, <tt/Priority/,
<tt/Maintainer/ go above the first blank line, most of the rest below.

<item>
Reorder the fields and add a blank line at an appropriate point,
separating the source package fields from the binary package
fields.

<item>
Add the <tt/Source/ field.

<item>
Add the <tt/Standards-Version/ field.  (Please check out the Debian
Policy Manual for details about this field.)

<item>
Change the <tt/Architecture/ field for each package to <tt/any/,
<tt/all/ or whatever.  If there isn't an <tt/Architecture/ field add
one.

<item>
If any other use of sed or things used to happen to make the binary
control files use <prgn/dpkg-gencontrol/'s variable substitution
features to achieve the same effect.  Use <tt>debian/substvars</> if
you need to put unusally-generated information (apart from details of
<tt/.deb/ files) in the <tt/.changes/ file too.
</list>

<item>
Edit the <tt>debian/rules</>:
<list compact>
<item>
Remove the <prgn/source/ and <prgn/diff/ and any <prgn/changes/ and
<prgn/dist/ targets.  These things now happen in a package-independent
way and are not done by <tt>debian/rules</>.
<item>
Split the <prgn/binary/ target into <prgn/binary-arch/ and
<prgn/binary-indep/; in many cases all of <prgn/binary/ should go into
<prgn/binary-arch/.  Create the <prgn/binary/ target and the unused of
the two other <prgn/binary-*/ targets if there is one - you can copy
the ones from the <prgn/hello/ package.
<item>
Change the <prgn/binary/ target to use <prgn/dpkg-gencontrol/ to make
the package control file(s).  Move it to after all the files have been
installed but just before the last <prgn/chown/ and <prgn/chmod/ in
the target.
<item>
Change occurrences of <tt/debian-tmp/ to <tt>debian/tmp</>.
<item>
Change occurrences of <tt/debian.{post,pre}{inst,rm}/ to
<tt>debian/*</>.
<item>
Remove the version number setting at the top, if there is one.
<item>
Ensure that the package's Debian-specific and upstream changelogs are
installed.
</list>

<item>
Change the package to use <prgn/dpkg-shlibdeps/ to determine its
shared library dependencies and substitute them in.  Shared library
dependencies should no longer be hardwired in the source package.

<item>
Check that the <tt>debian/README</> is really the copyright file, and
if so rename it to <tt>debian/copyright</> and edit
<tt>debian/rules</> to cope with this and to change the installation
of the copyright file from <tt>/usr/doc/<var/package//copyright</>
to <tt>/usr/doc/copyright/<var/package/</>.  If it isn't then
find <tt>debian/copyright</> and decide what to do with the
<tt>README</>.

<item>
Check for various other anachronisms and problems:
<list compact>
<item>
Remove any <tt/Package_Revision/, <tt/Package-Revision/ or
<tt/Revision/ fields.
<item>
Rename <tt/Optional/ to <tt/Suggests/, <tt/Recommended/ to
<tt/Recommends/.
<item>
Change <tt>/usr/doc/examples/<var/package/</> to
<tt>/usr/doc/<var/package//examples</>.
<item>
Make sure that manpages are installed compressed.
<item>
Check that the description has an extended description, is
well-formatted and meaningful and helpful to people wanting to know
whether to install a package.
</list>

<item>
Look everything over.

<item>
Do a test build using <tt/dpkg-buildpackage -us -uc -sa
-r<var/whatever//.  Check the permissions and locations of files in
the resulting package by examining the output of <tt/dpkg-deb
--contents/, and check that the source build happened OK.  Test
install the binary package(s) and test extract the source package(s).

<item>
Sign the release: either rebuild everything with <tt/dpkg-buildpackage
-sa/, or PGP-sign the <tt/.dsc/, rebuild the <tt/.changes/ using
<tt/dpkg-genchanges -sa/, and then PGP-sign the <tt/.changes/.

</list>
<p>

The use of <tt/-sa/ on <prgn/dpkg-buildpackage/ and
<prgn/dpkg-genchanges/ is important when doing the first
build/uploading of a new-format source package.  Unless this happens
to be Debian revision <tt/0/ or <tt/1/ by default the original source
tarfile will not be included in the uploaded files listed in the
<tt/.changes/ file, and so it won't be installed on the FTP site.
<tt/-sa/ requests that the original source be included regardless.

</book>