-<!doctype debiandoc system>
+<!doctype debiandoc system[
+<!-- include version information so we don't have to hard code it
+ within the document -->
+<!entity % versiondata SYSTEM "version.ent"> %versiondata;
+]>
<!--
Debian GNU/Linux Packaging Manual.
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 ©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/<>/ (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/:/]<var/upstream-version/[<tt/-/<var/debian-revision/].
-<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/
+<debiandoc>
+ <book>
+
+ <titlepag><title>Debian Packaging Manual</title>
+ <author>
+ <name>Ian Jackson </name>
+ <email>ijackson@gnu.ai.mit.edu</email>
+ </author>
+ <author>
+ <name>Revised: David A. Morris</name>
+ <email>bweaver@debian.org</email>
+ </author>
+ <author>
+ <name>Maintainer: Christian Schwarz </name>
+ <email>schwarz@debian.org</email>
+ </author>
+ <author>
+ <name>Maintainer: Manoj Srivastava </name>
+ <email>srivasta@debian.org</email>
+ </author>
+ <author>
+ <name>Maintainer: The Debian Policy group </name>
+ <email>debian-policy@lists.debian.org</email>
+ </author>
+ <version>version &version;, &date;</version>
+
+ <abstract>
+ This manual describes the technical aspects of creating Debian
+ binary and source packages. It also documents the interface
+ between <prgn>dselect</prgn> and its access method scripts.
+ It does not deal with the Debian Project policy requirements,
+ and it assumes familiarity with <prgn>dpkg</prgn>'s functions
+ from the system administrator's perspective.
+
+ <copyright>
+ <copyrightsummary>Copyright ©1996 Ian Jackson.</copyrightsummary>
+ <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>
+
+ <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>
+
+ <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>
+ </copyright>
+
+ <toc detail="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">
+ <heading>Introduction and scope of this manual</heading>
+
+ <p>
+ <prgn>dpkg</prgn> is a suite of programs for creating binary
+ package files and installing and removing them on Unix
+ systems.<footnote>
+ <p>
+ <prgn>dpkg</prgn> is targetted primarily at Debian
+ GNU/Linux, but may work on or be ported to other
+ systems.
+ </p>
+ </footnote>
+ </p>
+
+ <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>
+
+ <p>
+ This manual describes the technical aspects of creating Debian
+ binary packages (<tt>.deb</tt> files). It documents the
+ behaviour of the package management programs
+ <prgn>dpkg</prgn>, <prgn>dselect</prgn> et al. and and the way
+ they interact with packages.</p>
+
+ <p>
+ It also documents the interaction between
+ <prgn>dselect</prgn>'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>
+
+ <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>
+
+ <p>
+ The utility programs which are provided with <prgn>dpkg</prgn>
+ for managing various system configuration and similar issues,
+ such as <prgn>update-rc.d</prgn> and
+ <prgn>install-info</prgn>, are not described in detail here -
+ please see their manpages.
+ </p>
+
+ <p>
+ It does <em>not</em> 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>
+
+ <p>
+ It is assumed that the reader is reasonably familiar with the
+ <prgn>dpkg</prgn> System Administrators' manual.
+ Unfortunately this manual does not yet exist.
+ </p>
+
+ <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</prgn> 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.</p>
+ </chapt>
+
+ <chapt id="binarypkg"><heading>Binary packages
+ </heading>
+
+ <p>
+ The binary package has two main sections. The first part
+ consists of various control information files and scripts used
+ by <prgn>dpkg</prgn> when installing and removing. See <ref
+ id="controlarea">.
+ </p>
+
+ <p>
+ The second part is an archive containing the files and
+ directories to be installed.
+ </p>
+
+ <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)</tt> manpage.
+ </p>
+
+
+ <sect id="bincreating"><heading>Creating package files -
+ <prgn>dpkg-deb</prgn>
+ </heading>
+
+ <p>
+ All manipulation of binary package files is done by
+ <prgn>dpkg-deb</prgn>; it's the only program that has
+ knowledge of the format. (<prgn>dpkg-deb</prgn> may be
+ invoked by calling <prgn>dpkg</prgn>, as <prgn>dpkg</prgn>
+ will spot that the options requested are appropriate to
+ <prgn>dpkg-deb</prgn> and invoke that instead with the same
+ arguments.)
+ </p>
+
+ <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>
+
+ <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>
+
+ <p>
+ With current versions of <prgn>dpkg</prgn> 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>
+
+ <p>
+ You need to add one special directory to the root of the
+ miniature filesystem tree you're creating:
+ <prgn>DEBIAN</prgn>. It should contain the control
+ information files, notably the binary package control file
+ (see <ref id="controlfile">).
+ </p>
+
+ <p>
+ The <prgn>DEBIAN</prgn> directory will not appear in the
+ filesystem archive of the package, and so won't be installed
+ by <prgn>dpkg</prgn> when the package is installed.
+ </p>
+
+ <p>
+ When you've prepared the package, you should invoke:
+ <example>
+ dpkg --build <var>directory</var>
+ </example>
+ </p>
+
+ <p>
+ This will build the package in
+ <tt><var>directory</var>.deb</tt>. (<prgn>dpkg</prgn> knows
+ that <tt>--build</tt> is a <prgn>dpkg-deb</prgn> option, so
+ it invokes <prgn>dpkg-deb</prgn> with the same arguments to
+ build the package.)
+ </p>
+
+ <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</var>.deb
+dpkg-deb --contents <var>filename</var>.deb
+dpkg --contents <var>filename</var>.deb
</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><unknown></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>
+ To view the copyright file for a package you could use this command:
<example>
-<var/prerm/ remove
-</example>
+dpkg --fsys-tarfile <var>filename</var>.deb | tar xof usr/doc/<var>\*</var>copyright | less
+</example></p>
+
+ <sect id="controlarea">
+ <heading>
+ Package control information files
+ </heading>
+
+ <p>
+ The control information portion of a binary package is a
+ collection of files with names known to <prgn>dpkg</prgn>.
+ It will treat the contents of these files specially - some
+ of them contain information used by <prgn>dpkg</prgn> when
+ installing or removing the package; others are scripts which
+ the package maintainer wants <prgn>dpkg</prgn> to run.
+ </p>
+
+ <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>
+
+ <p>
+ Here is a brief list of the control info files supported by
+ <prgn>dpkg</prgn> and a summary of what they're used for.
+ </p>
+
+ <p>
+ <taglist>
+ <tag><tt>control</tt>
+ <item>
+
+ <p>
+ This is the key description file used by
+ <prgn>dpkg</prgn>. 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>
+
+ <p>
+ It is usually generated automatically from information
+ in the source package by the
+ <prgn>dpkg-gencontrol</prgn> program, and with
+ assistance from <prgn>dpkg-shlibdeps</prgn>. See <ref
+ id="sourcetools">.</p>
+ </item>
+
+ <tag><tt>postinst</tt>, <tt>preinst</tt>, <tt>postrm</tt>,
+ <tt>prerm</tt>
+ </tag>
+ <item>
+
+ <p>
+ These are exectuable files (usually scripts) which
+ <prgn>dpkg</prgn> 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</prgn>. Details of when and
+ how they are called are in <ref
+ id="maintainerscripts">.
+ </p>
+
+ <p>
+ It is very important to make these scripts
+ idempotent.
+ <footnote>
+ <p>
+ 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.
+ </p>
+ </footnote> This is so that if an error occurs, the
+ user interrupts <prgn>dpkg</prgn> or some other
+ unforeseen circumstance happens you don't leave the
+ user with a badly-broken package.
+ </p>
+
+ <p>
+ The maintainer scripts are guaranteed to run with a
+ controlling terminal and can interact with the user.
+ If they need to prompt for passwords, do full-screen
+ interaction or something similar you should do these
+ things to and from <tt>/dev/tty</tt>, since
+ <prgn>dpkg</prgn> will at some point redirect scripts'
+ standard input and output so that it can log the
+ installation process. Likewise, because these scripts
+ may be executed with standard output redirected into a
+ pipe for logging purposes, Perl scripts should set
+ unbuffered output by setting <tt>$|=1</tt> so that the
+ output is printed immediately rather than being
+ buffered.
+ </p>
+
+ <p>
+ Each script should return a zero exit status for
+ success, or a nonzero one for failure.</p>
+ </item>
+
+ <tag><tt>conffiles</tt>
+ </tag>
+ <item>
+
+ <p>
+ This file contains a list of configuration files which
+ are to be handled automatically by <prgn>dpkg</prgn>
+ (see <ref id="conffiles">). Note that not necessarily
+ every configuration file should be listed here.</p>
+ </item>
+
+ <tag><tt>shlibs</tt>
+ </tag>
+ <item>
+
+ <p>
+ 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</prgn>
+ when it determines what dependencies are required in a
+ package control file. The <tt>shlibs</tt> file format
+ is described on <ref id="shlibs">.
+ </p>
+ </item>
+ </taglist>
+ </p>
+
+ <sect id="controlfile">
+ <heading>
+ The main control information file: <tt>control</tt>
+ </heading>
+ <p>
+ The most important control information file used by
+ <prgn>dpkg</prgn> when it installs a package is
+ <tt>control</tt>. It contains all the package's `vital
+ statistics'.
+ </p>
+
+ <p>
+ The binary package control files of packages built from
+ Debian sources are made by a special tool,
+ <prgn>dpkg-gencontrol</prgn>, which reads
+ <tt>debian/control</tt> and <tt>debian/changelog</tt> to
+ find the information it needs. See <ref id="sourcepkg"> for
+ more details.
+ </p>
+
+ <p>
+ The fields in binary package control files are:
+ <list compact="compact">
+ <item>
+ <p><qref id="f-Package"><tt>Package</tt></qref> (mandatory)</p>
+ </item>
+ <item>
+ <p><qref id="versions"><tt>Version</tt></qref> (mandatory)</p>
+ </item>
+ <item><p><qref id="f-Architecture"><tt>Architecture</tt></qref>
+ (mandatory)
+ <footnote>
+ <p>
+ This field should appear in all packages, though
+ <prgn>dpkg</prgn> doesn't require it yet so that
+ old packages can still be installed.
+ </p>
+ </footnote>
+ </p>
+ </item>
+ <item>
+ <p><qref id="relationships"><tt>Depends</tt>,
+ <tt>Provides</tt> et al.</qref></p>
+ </item>
+ <item>
+ <p><qref id="f-Essential"><tt>Essential</tt></qref></p>
+ </item>
+ <item>
+ <p><qref id="f-Maintainer"><tt>Maintainer</tt></qref></p>
+ </item>
+ <item>
+ <p><qref id="f-classification"><tt>Section</tt>,
+ <tt>Priority</tt></qref></p>
+ </item>
+ <item>
+ <p><qref id="f-Source"><tt>Source</tt></qref></p>
+ </item>
+ <item>
+ <p><qref id="descriptions"><tt>Description</tt></qref></p>
+ </item>
+ <item>
+ <p>
+ <qref id="f-Installed-Size"><tt>Installed-Size</tt></qref>
+ </p>
+ </item>
+ </list>
+
+ <p>
+ A description of the syntax of control files and the purpose
+ of these fields is available in <ref id="controlfields">.
+ </p>
+ </sect>
+ <sect>
+ <heading>Time Stamps</heading>
+ <p>
+ Maintainers are encouraged to preserve the modification
+ times of the upstream source files in a package, as far as
+ is reasonably possible.
+ <footnote>
+ <p>
+ The rationale is that there is some information conveyed
+ by knowing the age of the file, for example, you could
+ recognize that some documentation is very old by looking
+ at the modification time, so it would be nice if the
+ modification time of the upstream source would be
+ preserved.
+ </p>
+ </footnote>
+ </p>
+ </sect>
+
+ <chapt id="sourcepkg">
+ <heading>Source packages</heading>
+
+ <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>
+
+ <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.
+ </p>
+
+ <sect id="sourcetools">
+ <heading>Tools for processing source packages</heading>
+
+ <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>
+
+ <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>
+
+ <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</prgn> example
+ package.
+ </p>
+
+ <sect1>
+ <heading>
+ <prgn>dpkg-source</prgn> - packs and unpacks Debian source
+ packages
+ </heading>
+
+ <p>
+ This program is frequently used by hand, and is also
+ called from package-independent automated building scripts
+ such as <prgn>dpkg-buildpackage</prgn>.
+ </p>
+
+ <p>
+ To unpack a package it is typically invoked with
+ <example>
+ dpkg-source -x <var>.../path/to/filename</var>.dsc
+ </example>
+ </p>
+
+ <p>
+ with the <tt><var>filename</var>.tar.gz</tt> and
+ <tt><var>filename</var>.diff.gz</tt> (if applicable) in
+ the same directory. It unpacks into
+ <tt><var>package</var>-<var>version</var></tt>, and if
+ applicable
+ <tt><var>package</var>-<var>version</var>.orig</tt>, in
+ the current directory.
+ </p>
+
+ <p>
+ To create a packed source archive it is typically invoked:
+ <example>
+ dpkg-source -b <var>package</var>-<var>version</var>
+ </example>
+ </p>
+
+ <p>
+ This will create the <tt>.dsc</tt>, <tt>.tar.gz</tt> and
+ <tt>.diff.gz</tt> (if appropriate) in the current
+ directory. <prgn>dpkg-source</prgn> does not clean the
+ source tree first - this must be done separately if it is
+ required.
+ </p>
+
+ <p>
+ See also <ref id="sourcearchives">.</p>
+ </sect1>
+
+
+ <sect1>
+ <heading>
+ <prgn>dpkg-buildpackage</prgn> - overall package-building
+ control script
+ </heading>
+
+ <p>
+ <prgn>dpkg-buildpackage</prgn> is a script which invokes
+ <prgn>dpkg-source</prgn>, the <tt>debian/rules</tt>
+ targets <prgn>clean</prgn>, <prgn>build</prgn> and
+ <prgn>binary</prgn>, <prgn>dpkg-genchanges</prgn> and
+ <prgn>pgp</prgn> to build a signed source and binary
+ package upload.
+ </p>
+
+ <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="compact">
+ <tag><tt>-uc</tt>, <tt>-us</tt></tag>
+ <item>
+ <p>
+ Do not PGP-sign the <tt>.changes</tt> file or the
+ source package <tt>.dsc</tt> file, respectively.</p>
+ </item>
+ <tag><tt>-p<var>pgp-command</var></tt></tag>
+ <item>
+ <p>
+ Invoke <var>pgp-command</var> instead of finding
+ <tt>pgp</tt> on the <prgn>PATH</prgn>.
+ <var>pgp-command</var> must behave just like
+ <prgn>pgp</prgn>.</p>
+ </item>
+ <tag><tt>-r<var>root-command</var></tt></tag>
+ <item>
+ <p>
+ When root privilege is required, invoke the command
+ <var>root-command</var>. <var>root-command</var>
+ should invoke its first argument as a command, from
+ the <prgn>PATH</prgn> if necessary, and pass its
+ second and subsequent arguments to the command it
+ calls. If no <var>root-command</var> is supplied
+ then <var>dpkg-buildpackage</var> 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.</p>
+ </item>
+ <tag><tt>-b</tt>, <tt>-B</tt></tag>
+ <item>
+ <p>
+ Two types of binary-only build and upload - see
+ <manref name="dpkg-source" section="1">.
+ </p>
+ </item>
+ </taglist>
+ </p>
+ </sect1>
+
+ <sect1>
+ <heading>
+ <prgn>dpkg-gencontrol</prgn> - generates binary package
+ control files
+ </heading>
+
+ <p>
+ This program is usually called from <tt>debian/rules</tt>
+ (see <ref id="sourcetree">) in the top level of the source
+ tree.
+ </p>
+
+ <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/</prgn>
+ <footnote>
+ <p>
+ This is so that the control file which is produced has
+ the right permissions
+ </p>
+ </footnote>.
+ </p>
+
+ <p>
+ <prgn>dpkg-gencontrol</prgn> 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>
+
+ <p>
+ It is also necessary for <prgn>dpkg-gencontrol</prgn> to
+ be run after <prgn>dpkg-shlibdeps</prgn> so that the
+ variable substitutions created by
+ <prgn>dpkg-shlibdeps</prgn> in <tt>debian/substvars</tt>
+ are available.
+ </p>
+
+ <p>
+ For a package which generates only one binary package, and
+ which builds it in <tt>debian/tmp</tt> relative to the top
+ of the source package, it is usually sufficient to call:
+ <example>
+ dpkg-gencontrol
+ </example>
+ </p>
+
+ <p>
+ Sources which build several binaries will typically need
+ something like:
+ <example>
+ dpkg-gencontrol -Pdebian/tmp-<var>pkg</var> -p<var>package</var>
+ </example> The <tt>-P</tt> tells
+ <prgn>dpkg-gencontrol</prgn> that the package is being
+ built in a non-default directory, and the <tt>-p</tt>
+ tells it which package's control file should be generated.
+ </p>
+
+ <p>
+ <prgn>dpkg-gencontrol</prgn> also adds information to the
+ list of files in <tt>debian/files</tt>, for the benefit of
+ (for example) a future invocation of
+ <prgn>dpkg-genchanges</prgn>.</p>
+ </sect1>
+
+ <sect1>
+ <heading>
+ <prgn>dpkg-shlibdeps</prgn> - calculates shared library
+ dependencies
+ </heading>
+
+ <p>
+ This program is usually called from <tt>debian/rules</tt>
+ just before <prgn>dpkg-gencontrol</prgn> (see <ref
+ id="sourcetree">), in the top level of the source tree.
+ </p>
+
+ <p>
+ Its arguments are executables
+ <footnote>
+ <p>
+ 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.
+ </p>
+ </footnote> for which shared library dependencies should
+ be included in the binary package's control file.
+ </p>
+
+ <p>
+ If some of the executable(s) shared libraries should only
+ warrant a <tt>Recommends</tt> or <tt>Suggests</tt>, or if
+ some warrant a <tt>Pre-Depends</tt>, this can be achieved
+ by using the <tt>-d<var>dependency-field</var></tt> option
+ before those executable(s). (Each <tt>-d</tt> option
+ takes effect until the next <tt>-d</tt>.)
+ </p>
+
+ <p>
+ <prgn>dpkg-shlibdeps</prgn> does not directly cause the
+ output control file to be modified. Instead by default it
+ adds to the <tt>debian/substvars</tt> file variable
+ settings like <tt>shlibs:Depends</tt>. These variable
+ settings must be referenced in dependency fields in the
+ appropriate per-binary-package sections of the source
+ control file.
+ </p>
+
+ <p>
+ For example, the <prgn>procps</prgn> package generates two
+ kinds of binaries, simple C binaries like <prgn>ps</prgn>
+ which require a predependency and full-screen ncurses
+ binaries like <prgn>top</prgn> which require only a
+ recommendation. It can say in its <tt>debian/rules</tt>:
+ <example>
+ dpkg-shlibdeps -dPre-Depends ps -dRecommends top
+ </example>
+ and then in its main control file <tt>debian/control</tt>:
+ <example>
+ <var>...</var>
+ Package: procps
+ Pre-Depends: ${shlibs:Pre-Depends}
+ Recommends: ${shlibs:Recommends}
+ <var>...</var>
+ </example>
+ </p>
+
+ <p>
+ Sources which produce several binary packages with
+ different shared library dependency requirements can use
+ the <tt>-p<var>varnameprefix</var></tt> option to override
+ the default <tt>shlib:</tt> prefix (one invocation of
+ <prgn>dpkg-shlibdeps</prgn> per setting of this option).
+ They can thus produce several sets of dependency
+ variables, each of the form
+ <tt><var>varnameprefix</var>:<var>dependencyfield</var></tt>,
+ which can be referred to in the appropriate parts of the
+ binary package control files.
+ </p>
+ </sect1>
+
+
+ <sect1>
+ <heading>
+ <prgn>dpkg-distaddfile</prgn> - adds a file to
+ <tt>debian/files</tt>
+ </heading>
+
+ <p>
+ Some packages' uploads need to include files other than
+ the source and binary package files.
+ </p>
+
+ <p>
+ <prgn>dpkg-distaddfile</prgn> adds a file to the
+ <tt>debian/files</tt> file so that it will be included in
+ the <tt>.changes</tt> file when
+ <prgn>dpkg-genchanges</prgn> is run.
+ </p>
+
+ <p>
+ It is usually invoked from the <prgn>binary</prgn> target of
+ <tt>debian/rules</tt>:
+ <example>
+ dpkg-distaddfile <var>filename</var> <var>section</var> <var>priority</var>
+ </example>
+ The <var>filename</var> is relative to the directory where
+ <prgn>dpkg-genchanges</prgn> will expect to find it - this
+ is usually the directory above the top level of the source
+ tree. The <tt>debian/rules</tt> target should put the
+ file there just before or just after calling
+ <prgn>dpkg-distaddfile</prgn>.
+ </p>
+
+ <p>
+ The <var>section</var> and <var>priority</var> are passed
+ unchanged into the resulting <tt>.changes</tt> file. See
+ <ref id="f-classification">.
+ </p>
+ </sect1>
+
+
+ <sect1><heading><prgn>dpkg-genchanges</prgn> - generates a <tt>.changes</tt> upload
+ control file
+ </heading>
+
+ <p>
+ This program is usually called by package-independent
+ automatic building scripts such as
+ <prgn>dpkg-buildpackage</prgn>, but it may also be called
+ by hand.
+ </p>
+
+ <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</tt> 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.
+ </p>
+ </sect1>
+
+
+ <sect1><heading><prgn>dpkg-parsechangelog</prgn> - produces parsed representation of
+ a changelog
+ </heading>
+
+ <p>
+ This program is used internally by
+ <prgn>dpkg-source</prgn> et al. It may also occasionally
+ be useful in <tt>debian/rules</tt> and elsewhere. It
+ parses a changelog, <tt>debian/changelog</tt> by default,
+ and prints a control-file format representation of the
+ information in it to standard output.
+ </p>
+ </sect1>
+ </sect>
+
+ <sect id="sourcetree"><heading>The Debianised source tree
+ </heading>
+
+ <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>
+
+ <p>
+ The extra files created for Debian are in the subdirectory
+ <tt>debian</tt> of the top level of the Debianised source
+ tree. They are described below.
+ </p>
+
+ <sect1><heading><tt>debian/rules</tt> - the main building
+ script
+ </heading>
+
+ <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>
+
+ <p>
+ It must start with the line <tt>#!/usr/bin/make -f</tt>,
+ so that it can be invoked by saying its name rather than
+ invoking <prgn>make</prgn> explicitly.
+ </p>
+
+ <p>
+ Since an interactive <tt>debian/rules</tt> script makes it
+ impossible to autocompile that package and also makes it
+ hard for other people to reproduce the same binary
+ package, all <strong>required targets</strong> have to be
+ non-interactive. At a minimul, required targets are the
+ ones called by <prgn>dpkg-buildpackage</prgn>, namely,
+ <em>clean</em>, <em>binary</em>, <em>binary-arch</em>, and
+ <em>build</em>. It also follows that any target that these
+ targets depend on must also be non-interactive.
+ </p>
+
+ <p>
+ The targets which are required to be present are:
+ <taglist>
+ <tag><tt>build</tt></tag>
+ <item>
+ <p>
+ This should perform all non-interactive
+ configuration and compilation of the package. If a
+ package has an interactive pre-build configuration
+ routine, the Debianised source package should be
+ built after this has taken place, so that it can be
+ built without rerunning the configuration.
+ </p>
+
+ <p>
+ For some packages, notably ones where the same
+ source tree is compiled in different ways to produce
+ two binary packages, the <prgn>build</prgn> target
+ does not make much sense. For these packages it is
+ good enough to provide two (or more) targets
+ (<tt>build-a</tt> and <tt>build-b</tt> or whatever)
+ for each of the ways of building the package, and a
+ <prgn>build</prgn> target that does nothing. The
+ <prgn>binary</prgn> target will have to build the
+ package in each of the possible ways and make the
+ binary package out of each.
+ </p>
+
+ <p>
+ The <prgn>build</prgn> target must not do anything
+ that might require root privilege.
+ </p>
+
+ <p>
+ The <prgn>build</prgn> target may need to run
+ <prgn>clean</prgn> first - see below.
+ </p>
+
+ <p>
+ When a package has a configuration routine that
+ takes a long time, or when the makefiles are poorly
+ designed, or when <prgn>build</prgn> needs to run
+ <prgn>clean</prgn> first, it is a good idea to
+ <tt>touch build</tt> when the build process is
+ complete. This will ensure that if <tt>debian/rules
+ build</tt> is run again it will not rebuild the
+ whole program.
+ </p>
+ </item>
+
+ <tag><tt>binary</tt>, <tt>binary-arch</tt>,
+ <tt>binary-indep</tt>
+ </tag>
+ <item>
+ <p>
+ The <prgn>binary</prgn> target should be all that is
+ necessary for the user to build the binary
+ package. All these targets are required to be
+ non-interactive. It is split into two parts:
+ <prgn>binary-arch</prgn> builds the packages' output
+ files which are specific to a particular
+ architecture, and <prgn>binary-indep</prgn> builds
+ those which are not.
+ </p>
+
+ <p>
+ <prgn>binary</prgn> should usually be a target with
+ no commands which simply depends on
+ <prgn>binary-arch</prgn> and
+ <prgn>binary-indep</prgn>.
+ </p>
+
+ <p>
+ Both <prgn>binary-*</prgn> targets should depend on
+ the <prgn>build</prgn> target, above, so that the
+ package is built if it has not been already. It
+ should then create the relevant binary package(s),
+ using <prgn>dpkg-gencontrol</prgn> to make their
+ control files and <prgn>dpkg-deb</prgn> to build
+ them and place them in the parent of the top level
+ directory.
+ </p>
+
+ <p>
+ If one of the <prgn>binary-*</prgn> 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</em> still exist, but should always
+ succeed.
+ </p>
+
+ <p>
+ <ref id="binarypkg"> describes how to construct
+ binary packages.
+ </p>
+
+ <p>
+ The <prgn>binary</prgn> targets must be invoked as
+ root.
+ </p>
+ </item>
+
+ <tag><tt>clean</tt></tag>
+ <item>
+
+ <p>
+ This should undo any effects that the
+ <prgn>build</prgn> and <prgn>binary</prgn> targets
+ may have had, except that it should leave alone any
+ output files created in the parent directory by a
+ run of <prgn>binary</prgn>. This target is required
+ to be non-interactive.
+ </p>
+
+ <p>
+ If a <prgn>build</prgn> file is touched at the end
+ of the <prgn>build</prgn> target, as suggested
+ above, it must be removed as the first thing that
+ <prgn>clean</prgn> does, so that running
+ <prgn>build</prgn> again after an interrupted
+ <prgn>clean</prgn> doesn't think that everything is
+ already done.
+ </p>
+
+ <p>
+ The <prgn>clean</prgn> target must be invoked as
+ root if <prgn>binary</prgn> has been invoked since
+ the last <prgn>clean</prgn>, or if
+ <prgn>build</prgn> has been invoked as root (since
+ <prgn>build</prgn> may create directories, for
+ example).
+ </p>
+ </item>
+
+ <tag><tt>get-orig-source</tt> (optional)</tag>
+ <item>
+
+ <p>
+ This target fetches the most recent version of the
+ original source package from a canonical archive
+ site (via FTP or WWW, for example), does any
+ necessary rearrangement to turn it into the original
+ source tarfile format described below, and leaves it
+ in the current directory.
+ </p>
+
+ <p>
+ This target may be invoked in any directory, and
+ should take care to clean up any temporary files it
+ may have left.
+ </p>
+
+ <p>
+ This target is optional, but providing it if
+ possible is a good idea.
+ </p>
+ </item>
+ </taglist>
+
+ <p>
+ The <prgn>build</prgn>, <prgn>binary</prgn> and
+ <prgn>clean</prgn> targets must be invoked with a current
+ directory of the package's top-level directory.
+ </p>
+
+
+ <p>
+ Additional targets may exist in <tt>debian/rules</tt>,
+ either as published or undocumented interfaces or for the
+ package's internal use.
+ </p>
+ </sect1>
+
+
+ <sect1><heading><tt>debian/control</tt>
+ </heading>
+
+ <p>
+ This file contains version-independent details about the
+ source package and about the binary packages it creates.
+ </p>
+
+ <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>
+
+ <p>
+ The syntax and semantics of the fields are described below
+ in <ref id="controlfields">.
+ </p>
+
+ <p>
+ The general (binary-package-independent) fields are:
+ <list compact="compact">
+ <item>
+ <p><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</p>
+ </item>
+ <item>
+ <p><qref id="f-Maintainer"><tt>Maintainer</tt></qref></p>
+ </item>
+ <item>
+ <p>
+ <qref id="f-classification"><tt>Section</tt> and
+ <tt>Priority</tt></qref>
+ (classification, mandatory)
+ </p>
+ </item>
+ <item>
+ <p>
+ <qref id="f-Standards-Version"><tt>Standards-Version</tt></qref>
+ </p>
+ </item>
+ </list>
+
+ <p>
+ The per-binary-package fields are:
+ <list compact="compact">
+ <item>
+ <p><qref id="f-Package"><tt>Package</tt></qref> (mandatory)</p>
+ </item>
+ <item>
+ <p>
+ <qref id="f-Architecture"><tt>Architecture</tt></qref>
+ (mandatory)</p>
+ </item>
+ <item>
+ <p><qref id="descriptions"><tt>Description</tt></qref></p>
+ </item>
+ <item>
+ <p>
+ <qref id="f-classification"><tt>Section</tt> and
+ <tt>Priority</tt></qref> (classification)</p>
+ </item>
+ <item>
+ <p><qref id="f-Essential"><tt>Essential</tt></qref></p>
+ </item>
+ <item>
+ <p>
+ <qref id="relationships"><tt>Depends</tt> et
+ al.</qref> (package interrelationships)
+ </p>
+ </item>
+ </list>
+
+ <p>
+ These fields are used by <prgn>dpkg-gencontrol</prgn> to
+ generate control files for binary packages (see below), by
+ <prgn>dpkg-genchanges</prgn> to generate the
+ <tt>.changes</tt> file to accompany the upload, and by
+ <prgn>dpkg-source</prgn> when it creates the <tt>.dsc</tt>
+ source control file as part of a source archive.
+ </p>
+
+ <p>
+ The fields here may contain variable references - their
+ values will be substituted by
+ <prgn>dpkg-gencontrol</prgn>, <prgn>dpkg-genchanges</prgn>
+ or <prgn>dpkg-source</prgn> when they generate output
+ control files. See <ref id="srcsubstvars"> for details.
+ </p>
+
+ <p> <sect2><heading>User-defined fields
+ </heading>
+
+ <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>
+
+ <p>
+ If you wish to add additional unsupported fields to
+ these output files you should use the mechanism
+ described here.
+ </p>
+
+ <p>
+ Fields in the main source control information file with
+ names starting <tt>X</tt>, followed by one or more of
+ the letters <tt>BCS</tt> and a hyphen <tt>-</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</tt> is used the field
+ will appear in binary package control files, where the
+ letter <tt>S</tt> is used in source package control
+ files and where <tt>C</tt> is used in upload control
+ (<tt>.changes</tt>) files.
+ </p>
+
+ <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>
+ </p>
+ </sect2>
+
+ </sect1>
+
+ <sect1 id="dpkgchangelog"><heading><tt>debian/changelog</tt>
+ </heading>
+
+ <p>
+ This file records the changes to the Debian-specific parts of the
+ package
+ <footnote>
+ <p>
+ Though there is nothing stopping an author who is also
+ the Debian maintainer from using it for all their
+ changes, it will have to be renamed if the Debian and
+ upstream maintainers become different
+ people.
+ </p>
+ </footnote>.
+ </p>
+
+ <p>
+ It has a special format which allows the package building
+ tools to discover which version of the package is being
+ built and find out other release-specific information.
+ </p>
+
+ <p>
+ That format is a series of entries like this:
+ <example>
+ <var>package</var> (<var>version</var>) <var>distribution(s)</var>;
+ urgency=<var>urgency</var>
+
+ * <var>change details</var>
+ <var>more change details</var>
+ * <var>even more change details</var>
+
+ -- <var>maintainer name and email address</var> <var>date</var>
+ </example>
+ </p>
+
+ <p>
+ <var>package</var> and <var>version</var> are the source
+ package name and version number.
+ </p>
+
+ <p>
+ <var>distribution(s)</var> lists the distributions where
+ this version should be installed when it is uploaded - it
+ is copied to the <tt>Distribution</tt> field in the
+ <tt>.changes</tt> file. See <ref id="f-Distribution">.
+ </p>
+
+ <p>
+ <var>urgency</var> is the value for the <tt>Urgency</tt>
+ field in the <tt>.changes</tt> file for the upload. See
+ <ref id="f-Urgency">. It is not possible to specify an
+ urgency containing commas; commas are used to separate
+ <tt><var>keyword</var>=<var>value</var></tt> settings in
+ the <prgn>dpkg</prgn> changelog format (though there is
+ currently only one useful <var>keyword</var>,
+ <tt>urgency</tt>).
+ </p>
+
+ <p>
+ The change details may in fact be any series of lines
+ starting with at least two spaces, but conventionally each
+ change starts with an asterisk and a separating space and
+ continuation lines are indented so as to bring them in
+ line with the start of the text above. Blank lines may be
+ used here to separate groups of changes, if desired.
+ </p>
+
+ <p>
+ The maintainer name and email address should <em>not</em>
+ necessarily be those of the usual package maintainer.
+ They should be the details of the person doing
+ <em>this</em> version. The information here will be
+ copied to the <tt>.changes</tt> file, and then later used
+ to send an acknowledgement when the upload has been
+ installed.
+ </p>
+
+ <p>
+ The <var>date</var> should be in RFC822 format
+ <footnote>
+ <p>
+ This is generated by the <prgn>822-date</prgn>
+ program.
+ </p>
+ </footnote>; it should include the timezone specified
+ numerically, with the timezone name or abbreviation
+ optionally present as a comment.
+ </p>
+
+ <p>
+ The first `title' line with the package name should start
+ at the left hand margin; the `trailer' line with the
+ maintainer and date details should be preceded by exactly
+ one space. The maintainer details and the date must be
+ separated by exactly two spaces.
+ </p>
+
+ <p>
+ An Emacs mode for editing this format is available: it is
+ called <tt>debian-changelog-mode</tt>. 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.
+ </p>
+
+ <sect2><heading>Defining alternative changelog formats
+ </heading>
+
+ <p>
+ It is possible to use a different format to the standard
+ one, by providing a parser for the format you wish to
+ use.
+ </p>
+
+ <p>
+ In order to have <tt>dpkg-parsechangelog</tt> 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>
+
+ <p>
+ If such a line exists then <tt>dpkg-parsechangelog</tt>
+ will look for the parser as
+ <tt>/usr/lib/dpkg/parsechangelog/<var>format-name</var></tt>
+ or
+ <tt>/usr/local/lib/dpkg/parsechangelog/<var>format-name</var></tt>;
+ 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</tt>, and a parser for it is provided with
+ the <tt>dpkg</tt> package.
+ </p>
+
+ <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</var></tt> option to return changes
+ information from all versions present <em>strictly
+ after</em> <var>version</var>, and it should then be an
+ error for <var>version</var> not to be present in the
+ changelog.
+ </p>
+
+ <p>
+ The fields are:
+ <list compact="compact">
+ <item>
+ <p><qref id="f-Source"><tt>Source</tt></qref></p>
+ </item>
+ <item>
+ <p><qref id="versions"><tt>Version</tt></qref> (mandatory)</p>
+ </item>
+ <item>
+ <p>
+ <qref id="f-Distribution"><tt>Distribution</tt></qref>
+ (mandatory)
+ </p>
+ </item>
+ <item>
+ <p><qref id="f-Urgency"><tt>Urgency</tt></qref> (mandatory)</p>
+ </item>
+ <item>
+ <p>
+ <qref id="f-Maintainer"><tt>Maintainer</tt></qref>
+ (mandatory)
+ </p>
+ </item>
+ <item>
+ <p><qref id="f-Date"><tt>Date</tt></qref></p>
+ </item>
+ <item>
+ <p>
+ <qref id="f-Changes"><tt>Changes</tt></qref>
+ (mandatory)
+ </p>
+ </item>
+ </list>
+
+ <p>
+ If several versions are being returned (due to the use
+ of <tt>-v</tt>), 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>
+
+ <p>
+ For the format of the <tt>Changes</tt> field see <ref
+ id="f-Changes">.
+ </p>
+
+ <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>
+
+ <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>
+
+ <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>
+
+ <p>
+ A changelog parser may not interact with the user at
+ all.</p></sect2>
+ </sect1>
+
+ <sect1 id="srcsubstvars"><heading><tt>debian/substvars</tt>
+ and variable substitutions
+ </heading>
+
+ <p>
+ When <prgn>dpkg-gencontrol</prgn>,
+ <prgn>dpkg-genchanges</prgn> and <prgn>dpkg-source</prgn>
+ generate control files they do variable substitutions on
+ their output just before writing it. Variable
+ substitutions have the form
+ <tt>${<var>variable-name</var>}</tt>. The optional file
+ <tt>debian/substvars</tt> contains variable substitutions
+ to be used; variables can also be set directly from
+ <tt>debian/rules</tt> using the <tt>-V</tt> option to the
+ source packaging commands, and certain predefined
+ variables are available.
+ </p>
+
+ <p>
+ The is usually generated and modified dynamically by
+ <tt>debian/rules</tt> targets; in this case it must be
+ removed by the <prgn>clean</prgn> target.
+ </p>
+
+ <p>
+ See <manref name="dpkg-source" section="1"> for full
+ details about source variable substitutions, including the
+ format of <tt>debian/substvars</tt>.</p>
+ </sect1>
+
+ <sect1><heading><tt>debian/files</tt>
+ </heading>
+
+ <p>
+ This file is not a permanent part of the source tree; it
+ is used while building packages to record which files are
+ being generated. <prgn>dpkg-genchanges</prgn> uses it
+ when it generates a <tt>.changes</tt> file.
+ </p>
+
+ <p>
+ It should not exist in a shipped source package, and so it
+ (and any backup files or temporary files such as
+ <tt>files.new</tt>
+ <footnote>
+ <p>
+ <tt>files.new</tt> is used as a temporary file by
+ <prgn>dpkg-gencontrol</prgn> and
+ <prgn>dpkg-distaddfile</prgn> - they write a new
+ version of <tt>files</tt> here before renaming it,
+ to avoid leaving a corrupted copy if an error
+ occurs
+ </p>
+ </footnote>) should be removed by the
+ <prgn>clean</prgn> target. It may also be wise to
+ ensure a fresh start by emptying or removing it at the
+ start of the <prgn>binary</prgn> target.
+ </p>
+
+ <p>
+ <prgn>dpkg-gencontrol</prgn> adds an entry to this file
+ for the <tt>.deb</tt> file that will be created by
+ <prgn>dpkg-deb</prgn> 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</prgn>.
+ </p>
+
+ <p>
+ If a package upload includes files besides the source
+ package and any binary packages whose control files were
+ made with <prgn>dpkg-gencontrol</prgn> then they should be
+ placed in the parent of the package's top-level directory
+ and <prgn>dpkg-distaddfile</prgn> should be called to add
+ the file to the list in <tt>debian/files</tt>.</p>
+ </sect1>
+
+ <sect1><heading><tt>debian/tmp</tt>
+ </heading>
+
+ <p>
+ This is the canonical temporary location for the
+ construction of binary packages by the <prgn>binary</prgn>
+ target. The directory <tt>tmp</tt> 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</tt> subdirectory. See <ref
+ id="bincreating">.
+ </p>
+
+ <p>
+ If several binary packages are generated from the same
+ source tree it is usual to use several
+ <tt>debian/tmp<var>something</var></tt> directories, for
+ example <tt>tmp-a</tt> or <tt>tmp-doc</tt>.
+ </p>
+
+ <p>
+ Whatever <tt>tmp</tt> directories are created and used by
+ <prgn>binary</prgn> must of course be removed by the
+ <prgn>clean</prgn> target.</p></sect1>
+ </sect>
+
+
+ <sect id="sourcearchives"><heading>Source packages as archives
+ </heading>
+
+ <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>
+
+ <p>
+ <taglist>
+ <tag>Debian source control file - <tt>.dsc</tt></tag>
+ <item>
+
+ <p>
+ 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="compact">
+ <item>
+ <p><qref id="f-Source"><tt>Source</tt></qref></p>
+ </item>
+ <item>
+ <p><qref id="versions"><tt>Version</tt></qref></p>
+ </item>
+ <item>
+ <p><qref id="f-Maintainer"><tt>Maintainer</tt></qref></p>
+ </item>
+ <item>
+ <p><qref id="f-Binary"><tt>Binary</tt></qref></p>
+ </item>
+ <item>
+ <p><qref id="f-Architecture"><tt>Architecture</tt></qref></p>
+ </item>
+ <item>
+ <p>
+ <qref id="f-Standards-Version"><tt>Standards-Version</tt></qref></p>
+ </item>
+ <item>
+ <p><qref id="f-Files"><tt>Files</tt></qref></p>
+ </item>
+ </list>
+
+ <p>
+ The source package control file is generated by
+ <prgn>dpkg-source</prgn> 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.</p>
+ </item>
+
+ <tag>
+ Original source archive -
+ <tt>
+ <var>package</var>_<var>upstream-version</var>.orig.tar.gz
+ </tt>
+ </tag>
+
+ <item>
+
+ <p>
+ This is a compressed (with <tt>gzip -9</tt>)
+ <prgn>tar</prgn> file containing the source code from
+ the upstream authors of the program. The tarfile
+ unpacks into a directory
+ <tt><var>package</var>-<var>upstream-version</var>.orig</tt>,
+ and does not contain files anywhere other than in
+ there or in its subdirectories.</p>
+ </item>
+
+ <tag>
+ Debianisation diff -
+ <tt>
+ <var>package</var>_<var>upstream_version-revision</var>.diff.gz
+ </tt>
+ </tag>
+ <item>
+
+ <p>
+ This is a unified context diff (<tt>diff -u</tt>)
+ 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>
+
+ <p>
+ All the directories in the diff must exist, except the
+ <tt>debian</tt> subdirectory of the top of the source
+ tree, which will be created by
+ <prgn>dpkg-source</prgn> if necessary when unpacking.
+ </p>
+
+ <p>
+ The <prgn>dpkg-source</prgn> program will
+ automatically make the <tt>debian/rules</tt> file
+ executable (see below).</p></item>
+ </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>_<var>version</var>.tar.gz</tt> and
+ contains a directory
+ <tt><var>package</var>-<var>version</var></tt>.
+ </p>
+ </sect>
+
+ <sect><heading>Unpacking a Debian source package without
+ <prgn>dpkg-source</prgn>
+ </heading>
+
+ <p>
+ <tt>dpkg-source -x</tt> 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="compact">
+ <item>
+ <p>
+ Untar the tarfile, which will create a <tt>.orig</tt>
+ directory.</p>
+ </item>
+ <item>
+ <p>Rename the <tt>.orig</tt> directory to
+ <tt><var>package</var>-<var>version</var></tt>.</p>
+ </item>
+ <item>
+ <p>
+ Create the subdirectory <tt>debian</tt> at the top of
+ the source tree.</p>
+ </item>
+ <item><p>Apply the diff using <tt>patch -p0</tt>.</p>
+ </item>
+ <item><p>Untar the tarfile again if you want a copy of the original
+ source code alongside the Debianised version.</p>
+ </item>
+ </enumlist>
+
+ <p>
+ It is not possible to generate a valid Debian source archive
+ without using <prgn>dpkg-source</prgn>. In particular,
+ attempting to use <prgn>diff</prgn> directly to generate the
+ <tt>.diff.gz</tt> file will not work.
+ </p>
+
+ <sect1><heading>Restrictions on objects in source packages
+ </heading>
+
+ <p>
+ The source package may not contain any hard links
+ <footnote>
+ <p>
+ This is not currently detected when building source
+ packages, but only when extracting
+ them.
+ </p>
+ </footnote>
+ <footnote>
+ <p>
+ Hard links may be permitted at some point in the
+ future, but would require a fair amount of
+ work.
+ </p>
+ </footnote>, device special files, sockets or setuid or
+ setgid files.
+ <footnote>
+ <p>
+ Setgid directories are allowed.
+ </p>
+ </footnote>
+ </p>
+
+ <p>
+ The source packaging tools manage the changes between the
+ original and Debianised source using <prgn>diff</prgn> and
+ <prgn>patch</prgn>. Turning the original source tree as
+ included in the <tt>.orig.tar.gz</tt> into the debianised
+ source must not involve any changes which cannot be
+ handled by these tools. Problematic changes which cause
+ <prgn>dpkg-source</prgn> to halt with an error when
+ building the source package are:
+ <list compact="compact">
+ <item><p>Adding or removing symbolic links, sockets or pipes.</p>
+ </item>
+ <item><p>Changing the targets of symbolic links.</p>
+ </item>
+ <item><p>Creating directories, other than <tt>debian</tt>.</p>
+ </item>
+ <item><p>Changes to the contents of binary files.</p></item>
+ </list> Changes which cause <prgn>dpkg-source</prgn> to
+ print a warning but continue anyway are:
+ <list compact="compact">
+ <item>
+ <p>
+ Removing files, directories or symlinks.
+ <footnote>
+ <p>
+ 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.</p>
+ </footnote>
+ </p>
+ </item>
+ <item>
+ <p>
+ Changed text files which are missing the usual final
+ newline (either in the original or the modified
+ source tree).
+ </p>
+ </item>
+ </list>
+ Changes which are not represented, but which are not detected by
+ <prgn>dpkg-source</prgn>, are:
+ <list compact="compact">
+ <item><p>Changing the permissions of files (other than
+ <tt>debian/rules</tt>) and directories.</p></item>
+ </list>
+ </p>
+
+ <p>
+ The <tt>debian</tt> directory and <tt>debian/rules</tt>
+ are handled specially by <prgn>dpkg-source</prgn> - before
+ applying the changes it will create the <tt>debian</tt>
+ directory, and afterwards it will make
+ <tt>debian/rules</tt> world-exectuable.
+ </p>
+ </sect1>
+ </sect>
+ </chapt>
+
+ <chapt id="controlfields"><heading>Control files and their fields
+ </heading>
+
+ <p>
+ Many of the tools in the <prgn>dpkg</prgn> suite manipulate
+ data in a common format, known as control files. Binary and
+ source packages have control data as do the <tt>.changes</tt>
+ files which control the installation of uploaded files, and
+ <prgn>dpkg</prgn>'s internal databases are in a similar
+ format.
+ </p>
+
+ <sect><heading>Syntax of control files
+ </heading>
+
+ <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>
+
+ <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>
+
+ <p>
+ Some fields' values may span several lines; in this case
+ each continuation line <em>must</em> start with a space or
+ tab. Any trailing spaces or tabs at the end of individual
+ lines of a field value are ignored.
+ </p>
+
+ <p>
+ Except where otherwise stated only a single line of data is
+ allowed and whitespace is not significant in a field body.
+ Whitespace 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>
+
+ <p>
+ Field names are not case-sensitive, but it is usual to
+ capitalise the fields using mixed case as shown below.
+ </p>
+
+ <p>
+ Blank lines, or lines consisting only of spaces and tabs,
+ are not allowed within field values or between fields - that
+ would mean a new paragraph.
+ </p>
+
+ <p>
+ It is important to note that there are several fields which
+ are optional as far as <prgn>dpkg</prgn> 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</em> read
+ the Debian policy manual in conjuction with the details
+ below and the list of fields for the particular file.</p>
+ </sect>
+
+ <sect><heading>List of fields
+ </heading>
+
+ <sect1 id="f-Package"><heading><tt>Package</tt>
+ </heading>
+
+ <p>
+ The name of the binary package. Package names consist of
+ the alphanumerics and <tt>+</tt> <tt>-</tt> <tt>.</tt>
+ (plus, minus and full stop).
+ <footnote>
+ <p>
+ The characters <tt>@</tt> <tt>:</tt> <tt>=</tt>
+ <tt>t</tt>t> <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
+ </p>
+ </footnote>
+ </p>
+
+ <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><p>This is a
+ bug.</p></footnote>; use lowercase package names unless
+ the package you're building (or referring to, in other
+ fields) is already using uppercase.</p>
+ </sect1>
+
+ <sect1 id="f-Version"><heading><tt>Version</tt>
+ </heading>
+
+ <p>
+ This lists the source or binary package's version number -
+ see <ref id="versions">.
+ </p>
+
+ </sect1>
+
+ <sect1 id="f-Architecture"><heading><tt>Architecture</tt>
+ </heading>
+
+ <p>
+ This is the architecture string; it is a single word for
+ the CPU architecture.
+ </p>
+
+ <p>
+ <prgn>dpkg</prgn> will check the declared architecture of
+ a binary package against its own compiled-in value before
+ it installs it.
+ </p>
+
+ <p>
+ The special value <tt>all</tt> indicates that the package
+ is architecture-independent.
+ </p>
+
+ <p>
+ In the main <tt>debian/control</tt> file in the source
+ package, or in the source package control file
+ <tt>.dsc</tt>, a list of architectures (separated by
+ spaces) is also allowed, as is the special value
+ <tt>any</tt>. A list indicates that the source will build
+ an architecture-dependent package, and will only work
+ correctly on the listed architectures. <tt>any</tt>
+ 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>
+
+ <p>
+ In a <tt>.changes</tt> file the <tt>Architecture</tt>
+ 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</tt> is also present.
+ </p>
+
+ <p>
+ The current build architecture can be determined using <tt>dpkg
+ --print-architecture</tt>.
+ <footnote>
+ <p>
+ 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</prgn>. This is so that it will
+ work if you're cross-compiling.
+ </p>
+ </footnote> This value is automatically used by
+ <prgn>dpkg-gencontrol</prgn> when building the control
+ file for a binary package for which the source control
+ information doesn't specify architecture <tt>all</tt>.
+ </p>
+
+ <p>
+ There is a separate option,
+ <tt>--print-installation-architecture</tt>, for finding
+ out what architecture <prgn>dpkg</prgn> is willing to
+ install. This information is also in the output of
+ <tt>dpkg --version</tt>.</p>
+ </sect1>
+
+ <sect1 id="f-Maintainer"><heading><tt>Maintainer</tt>
+ </heading>
+
+ <p>
+ The package maintainer's name and email address. The name
+ should come first, then the email address inside angle
+ brackets <tt><></tt> (in RFC822 format).
+ </p>
+
+ <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>
+
+ <p>
+ In a <tt>.changes</tt> 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>
+
+ <p>
+ This field is usually optional in as far as the
+ <prgn>dpkg</prgn> are concerned, but its absence when
+ building packages usually generates a warning.</p>
+ </sect1>
+
+ <sect1 id="f-Source"><heading><tt>Source</tt>
+ </heading>
+
+ <p>
+ This field identifies the source package name.
+ </p>
+
+ <p>
+ In a main source control information or a
+ <tt>.changes</tt> or <tt>.dsc</tt> file or parsed
+ changelog data this may contain only the name of the
+ source package.
+ </p>
+
+ <p>
+ In the control file of a binary package (or in a
+ <tt>Packages</tt> file) it may be followed by a version
+ number in parentheses.
+ <footnote>
+ <p>
+ It is usual to leave a space after the package name if
+ a version number is specified.
+ </p>
+ </footnote> This version number may be omitted (and is, by
+ <prgn>dpkg-gencontrol</prgn>) if it has the same value as
+ the <tt>Version</tt> 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.
+ </p>
+ </sect1>
+
+ <sect1><heading>Package interrelationship fields:
+ <tt>Depends</tt>, <tt>Pre-Depends</tt>,
+ <tt>Recommends</tt> <tt>Suggests</tt>, <tt>Conflicts</tt>,
+ <tt>Provides</tt>, <tt>Replaces</tt>
+ </heading>
+
+ <p>
+ These fields describe the package's relationships with
+ other packages. Their syntax and semantics are described
+ in <ref id="relationships">.</p>
+ </sect1>
+
+ <sect1 id="f-Description"><heading><tt>Description</tt>
+ </heading>
+
+ <p>
+ In a binary package <tt>Packages</tt> 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>
+
+ <p>
+ In a <tt>.changes</tt> 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.</p>
+ </sect1>
+
+ <sect1 id="f-Essential"><heading><tt>Essential</tt>
+ </heading>
+
+ <p>
+ This is a boolean field which may occur only in the
+ control file of a binary package (or in the
+ <tt>Packages</tt> file) or in a per-package fields
+ paragraph of a main source control data file.
+ </p>
+
+ <p>
+ If set to <tt>yes</tt> then <prgn>dpkg</prgn> and
+ <prgn>dselect</prgn> will refuse to remove the package
+ (though it can be upgraded and/or replaced). The other
+ possible value is <tt>no</tt>, which is the same as not
+ having the field at all.</p>
+ </sect1>
+
+ <sect1 id="f-classification"><heading><tt>Section</tt> and
+ <tt>Priority</tt>
+ </heading>
+
+ <p>
+ These two fields classify the package. The
+ <tt>Priority</tt> represents how important that it is that
+ the user have it installed; the <tt>Section</tt>
+ represents an application area into which the package has
+ been classified.
+ </p>
+
+ <p>
+ When they appear in the <tt>debian/control</tt> file these
+ fields give values for the section and priority subfields
+ of the <tt>Files</tt> field of the <tt>.changes</tt> file,
+ and give defaults for the section and priority of the
+ binary packages.
+ </p>
+
+ <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>-File</tt></qref>field of a
+ <tt>.changes</tt> file. The section value in a
+ <tt>.changes</tt> file is used to decide where to install
+ a package in the FTP archive.
+ </p>
+
+ <p>
+ These fields are not used by by <prgn>dpkg</prgn> proper,
+ but by <prgn>dselect</prgn> 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>
+
+ <p>
+ These fields may appear in binary package control files,
+ in which case they provide a default value in case the
+ <tt>Packages</tt> files are missing the information.
+ <prgn>dpkg</prgn> and <prgn>dselect</prgn> will only use
+ the value from a <tt>.deb</tt> file if they have no other
+ information; a value listed in a <tt>Packages</tt> file
+ will always take precedence. By default
+ <prgn>dpkg-genchanges</prgn> does not include the section
+ and priority in the control file of a binary package - use
+ the <tt>-isp</tt>, <tt>-is</tt> or <tt>-ip</tt> options to
+ achieve this effect.</p>
+ </sect1>
+
+ <sect1 id="f-Binary"><heading><tt>Binary</tt>
+ </heading>
+
+ <p>
+ This field is a list of binary packages.
+ </p>
+
+ <p>
+ When it appears in the <tt>.dsc</tt> 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>
+
+ <p>
+ When it appears in a <tt>.changes</tt> file it lists the
+ names of the binary packages actually being uploaded.
+ </p>
+
+ <p>
+ The syntax is a list of binary packages separated by
+ commas.
+ <footnote>
+ <p>
+ A space after each comma is conventional.
+ </p>
+ </footnote> Currently the packages must be separated using
+ only spaces in the <tt>.changes</tt> file.</p>
+ </sect1>
+
+ <sect1 id="f-Installed-Size"><heading><tt>Installed-Size</tt>
+ </heading>
+
+ <p>
+ This field appears in the control files of binary
+ packages, and in the <tt>Packages</tt> files. It gives
+ the total amount of disk space required to install the
+ named package.
+ </p>
+
+ <p>
+ The disk space is represented in kilobytes as a simple
+ decimal number.</p>
+ </sect1>
+
+ <sect1 id="f-Files"><heading><tt>Files</tt>
+ </heading>
+
+ <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>
+
+ <p>
+ In the <tt>.dsc</tt> (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>
+ <p>
+ That is, the parts which are not the
+ <tt>.dsc</tt>.
+ </p>
+ </footnote> The exact forms of the filenames are described
+ in <ref id="sourcearchives">.
+ </p>
+
+ <p>
+ In the <tt>.changes</tt> 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>-</tt> should be used, though section
+ and priority values must be specified for new packages to
+ be installed properly.
+ </p>
+
+ <p>
+ The special value <tt>byhand</tt> for the section in a
+ <tt>.changes</tt> 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</tt> the priority should be <tt>-</tt>.
+ </p>
+
+ <p>
+ If a new Debian revision of a package is being shipped and
+ no new original source archive is being distributed the
+ <tt>.dsc</tt> must still contain the <tt>Files</tt> field
+ entry for the original source archive
+ <tt><var>package</var>-<var>upstream-version</var>.orig.tar.gz</tt>,
+ but the <tt>.changes</tt> 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</tt> file and diff which are being uploaded.</p>
+ </sect1>
+
+
+ <sect1
+ id="f-Standards-Version"><heading><tt>Standards-Version</tt>
+ </heading>
+
+ <p>
+ The most recent version of the standards (the
+ <prgn>dpkg</prgn> 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>
+
+ <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">.</p>
+ </sect1>
+
+
+ <sect1 id="f-Distribution"><heading><tt>Distribution</tt>
+ </heading>
+
+ <p>
+ In a <tt>.changes</tt> file or parsed changelog output
+ this contains the (space-separated) name(s) of the
+ distribution(s) where this version of the package should
+ be or was installed. Distribution names follow the rules
+ for package names. (See <ref id="f-Package">).
+ </p>
+
+ <p>
+ Current distribution values are:
+ <taglist>
+ <tag><em>stable</em></tag>
+ <item>
+ <p>
+ This is the current `released' version of Debian
+ GNU/Linux. A new version is released approximately
+ every 3 months after the <em>development</em> code has
+ been <em>frozen</em> for a month of testing. Once the
+ distribution is <em>stable</em> 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).
+ </p>
+ </item>
+
+ <tag><em>unstable</em></tag>
+ <item>
+ <p>
+ This distribution value refers to the
+ <em>developmental</em> part of the Debian distribution
+ tree. New packages, new upstream versions of packages
+ and bug fixes go into the <em>unstable</em> directory
+ tree. Download from this distribution at your own
+ risk.</p>
+ </item>
+
+ <tag><em>contrib</em></tag>
+ <item>
+ <p>
+ 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</em>
+ Distribution. There is currently no distinction
+ between stable and unstable packages in the
+ <em>contrib</em> or <em>non-free</em>
+ distributions. Use your best judgement in downloading
+ from this Distribution.</p>
+ </item>
+
+ <tag><em>non-free</em></tag>
+ <item>
+ <p>
+ Like the packages in the <em>contrib</em> seciton,
+ the packages in <em>non-free</em> 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.</p>
+
+ <tag><em>experimental</em></tag>
+ <item>
+ <p>
+ The packages with this distribution value are deemed
+ by their maintainers to be high risk. Oftentimes they
+ represent early beta or developmental packages from
+ various sources that the maintainers want people to
+ try, but are not ready to be a part of the other parts
+ of the Debian distribution tree. Download at your own
+ risk.</p>
+ </item>
+
+ <tag><em>frozen</em></tag>
+ <item>
+ <p>
+ From time to time, (currently, every 3 months) the
+ <em>unstable</em> distribution enters a state of
+ `code-freeze' in anticipation of release as a
+ <em>stable</em> version. During this period of testing
+ (usually 4 weeks) only fixes for existing or
+ newly-discovered bugs will be allowed.
+ </p>
+ </item>
+ </taglist> You should list <em>all</em> distributions that
+ the package should be installed into. Except in unusual
+ circumstances, installations to <em>stable</em> should also
+ go into <em>frozen</em> (if it exists) and
+ <em>unstable</em>. Likewise, installations into
+ <em>frozen</em> should also go into <em>unstable</em>.</p>
+ </sect1>
+
+ <sect1 id="f-Urgency"><heading><tt>Urgency</tt>
+ </heading>
+
+ <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>,
+ <tt>MEDIUM</tt> or <tt>HIGH</tt>) 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>
+
+ <p>
+ This field appears in the <tt>.changes</tt> file and in
+ parsed changelogs; its value appears as the value of the
+ <tt>urgency</tt> attribute in a <prgn>dpkg</prgn>-style
+ changelog (see <ref id="dpkgchangelog">).
+ </p>
+
+ <p>
+ Urgency keywords are not case-sensitive.</p>
+ </sect1>
+
+ <sect1 id="f-Date"><heading><tt>Date</tt>
+ </heading>
+
+ <p>
+ In <tt>.changes</tt> files and parsed changelogs, this
+ gives the date the package was built or last edited.</p>
+ </sect1>
+
+ <sect1 id="f-Format"><heading><tt>Format</tt>
+ </heading>
+
+ <p>
+ This field occurs in <tt>.changes</tt> files, and
+ specifies a format revision for the file. The format
+ described here is version <tt>1.5</tt>. 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">.</p>
+ </sect1>
+
+ <sect1 id="f-Changes"><heading><tt>Changes</tt>
+ </heading>
+
+ <p>
+ In a <tt>.changes</tt> file or parsed changelog this field
+ contains the human-readable changes data, describing the
+ differences between the last version and the current one.
+ </p>
+
+ <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>
+
+ <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>
+
+ <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).</p>
+ </sect1>
+
+ <sect1 id="f-Filename"><heading><tt>Filename</tt> and
+ <tt>MSDOS-Filename</tt>
+ </heading>
+
+ <p>
+ These fields in <tt>Packages</tt> 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.</p>
+ </sect1>
+
+ <sect1 id="f-Size"><heading><tt>Size</tt> and <tt>MD5sum</tt>
+ </heading>
+
+ <p>
+ These fields in <tt>Packages</tt> 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.</p>
+ </sect1>
+
+ <sect1 id="f-Status"><heading><tt>Status</tt>
+ </heading>
+
+ <p>
+ This field in <prgn>dpkg</prgn>'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.</p>
+ </sect1>
+
+ <sect1 id="f-Config-Version"><heading><tt>Config-Version</tt>
+ </heading>
+
+ <p>
+ If a package is not installed or not configured, this
+ field in <prgn>dpkg</prgn>'s status file records the last
+ version of the package which was successfully
+ configured.</p>
+ </sect1>
+
+ <sect1 id="f-Conffiles"><heading><tt>Conffiles</tt>
+ </heading>
+
+ <p>
+ This field in <prgn>dpkg</prgn>'s status file contains
+ information about the automatically-managed configuration
+ files held by a package. This field should <em>not</em>
+ appear anywhere in a package!</p>
+ </sect1>
+
+ <sect1><heading>Obsolete fields
+ </heading>
+
+ <p>
+ These are still recognised by <prgn>dpkg</prgn> but should
+ not appear anywhere any more.
+ <taglist compact="compact">
+
+ <tag><tt>Revision</tt></tag>
+ <tag><tt>Package-Revision</tt></tag>
+ <tag><tt>Package_Revision</tt></tag>
+ <item>
+ <p>
+ The Debian revision part of the package version was
+ at one point in a separate control file field. This
+ field went through several names.</p>
+ </item>
+
+ <tag><tt>Recommended</tt></tag>
+ <item><p>Old name for <tt>Recommends</tt></p>
+ </item>
+
+ <tag><tt>Optional</tt></tag>
+ <item><p>Old name for <tt>Suggests</tt>.</p>
+ </item>
+ <tag><tt>Class</tt></tag>
+ <item><p>Old name for <tt>Priority</tt>.</p>
+ </item>
+ </taglist>
+ </p>
+ </sect1>
+ </sect>
+ </chapt>
+
+ <chapt id="versions"><heading>Version numbering
+ </heading>
+
+ <p>
+ Every package has a version number, in its <tt>Version</tt>
+ control file field.
+ </p>
+
+ <p>
+ <prgn>dpkg</prgn> imposes an ordering on version numbers, so
+ that it can tell whether packages are being up- or downgraded
+ and so that <prgn>dselect</prgn> can tell whether a package it
+ finds available is newer than the one installed on the system.
+ The version number format has the most significant parts (as
+ far as comparison is concerned) at the beginning.
+ </p>
+
+ <p>
+ The version number format is:
+ &lsqb<var>epoch/<tt>:</tt>]<var>upstream-version</var>[<tt>-/<var>debian-revision</var>].</tt></var>
+ </p>
+
+ <p>
+ The three components here are:
+ <taglist>
+ <tag><var>epoch</var></tag>
+ <item>
+
+ <p>
+ 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</var> may not contain any colons.
+ </p>
+
+ <p>
+ It is provided to allow mistakes in the version numbers
+ of older versions of a package, and also a package's
+ previous version numbering schemes, to be left behind.
+ </p>
+
+ <p>
+ <prgn>dpkg</prgn> will not usually display the epoch
+ unless it is essential (non-zero, or if the
+ <var>upstream-version</var> contains a colon);
+ <prgn>dselect</prgn> does not display epochs at all in
+ the main part of the package selection display.</p>
+ </item>
+
+ <tag><var>upstream-version</var></tag>
+ <item>
+
+ <p>
+ This is the main part of the version. It is usually
+ version number of the original (`upstream') package of
+ which the <tt>.deb</tt> file has been made, if this is
+ applicable. Usually this will be in the same format as
+ that specified by the upstream author(s); however, it
+ may need to be reformatted to fit into
+ <prgn>dpkg</prgn>'s format and comparison scheme.
+ </p>
+
+ <p>
+ The comparison behaviour of <prgn>dpkg</prgn> with
+ respect to the <var>upstream-version</var> is described
+ below. The <var>upstream-version</var> portion of the
+ version number is mandatory.
+ </p>
+
+ <p>
+ The <var>upstream-version</var> may contain only
+ alphanumerics and the characters <tt>+</tt> <tt>.</tt>
+ <tt>-</tt> <tt>:</tt> (full stop, plus, hyphen, colon)
+ and should start with a digit. If there is no
+ <var>debian-revision</var> then hyphens are not allowed;
+ if there is no <var>epoch</var> then colons are not
+ allowed.</p>
+ </item>
+
+ <tag><var>debian-revision</var></tag>
+ <item>
+
+ <p>
+ This part of the version 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</var> and <prgn>dpkg</prgn>
+ compares it in the same way.
+ </p>
+
+ <p>
+ It is optional; if it isn't present then the
+ <var>upstream-version</var> may not contain a hyphen.
+ This format represents the case where a piece of
+ software was written specifically to be turned into a
+ Debian binary package, and so there is only one
+ `debianization' of it and therefore no revision
+ indication is required.
+ </p>
+
+ <p>
+ It is conventional to restart the
+ <var>debian-revision</var> at <tt>1</tt> each time the
+ <var>upstream-version</var> is increased.
+ </p>
+
+ <p>
+ <prgn>dpkg</prgn> will break the
+ <var>upstream-version</var> and
+ <var>debian-revision</var> apart at the last hyphen in
+ the string. The absence of a <var>debian-revision</var>
+ compares earlier than the presence of one (but note that
+ the <var>debian-revision</var> is the least significant
+ part of the version number).
+ </p>
+
+ <p>
+ The <var>debian-revision</var> may contain only
+ alphanumerics and the characters <tt>+</tt> and
+ <tt>.</tt> (plus and full stop).
+ </p>
+ </item>
+ </taglist>
+ The <var>upstream-version</var> and <var>debian-revision</var> parts are
+ compared by <prgn>dpkg</prgn> using the same algorithm:
+ </p>
+
+ <p>
+ The strings are compared from left to right.
+ </p>
+
+ <p>
+ First the initial part of each string consisting entirely of
+ non-digit characters is determined. These two parts (one of
+ which may be empty) are compared lexically. If a difference
+ is found it is returned. The lexical comparison is a
+ comparison of ASCII values modified so that all the letters
+ sort earlier than all the non-letters.
+ </p>
+
+ <p>
+ Then the initial part of the remainder of each string which
+ consists entirely of digit characters is determined. The
+ numerical values of these two parts are compared, and any
+ difference found is returned as the result of the comparison.
+ For these purposes an empty string (which can only occur at
+ the end of one or both version strings being compared) counts
+ as zero.
+ </p>
+
+ <p>
+ These two steps 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>
+
+ <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</em> there
+ to cope with version numbers containing strings of letters
+ which <prgn>dpkg</prgn> cannot interpret (such as
+ <tt>ALPHA</tt> or <tt>pre-</tt>), or with silly orderings (the
+ author of this manual has heard of a package whose versions
+ went <tt>1.1</tt>, <tt>1.2</tt>, <tt>1.3</tt>, <tt>1</tt>,
+ <tt>2.1</tt>, <tt>2.2</tt>, <tt>2</tt> and so forth).
+ </p>
+
+ <p>
+ If an upstream package has problematic version numbers they
+ should be converted to a sane form for use in the
+ <tt>Version</tt> field.
+ </p>
+
+ <p>
+ If you need to compare version numbers in a script, you may use
+ <tt>dpkg --compare-versions ...</tt>. Type <tt>dpkg
+ --help</tt> --> --for details on arguments.
+ </p>
+ </chapt>
+
+ <chapt id="maintainerscripts"><heading>Package maintainer scripts
+ and installation procedure
+ </heading>
+
+ <sect><heading>Introduction to package maintainer scripts
+ </heading>
+
+ <p>
+ It is possible supply scripts as part of a package which
+ <prgn>dpkg</prgn> will run for you when your package is
+ installed, upgraded or removed.
+ </p>
+
+ <p>
+ These scripts should be the files <tt>preinst</tt>,
+ <tt>postinst</tt>, <tt>prerm</tt> and <tt>postrm</tt> in the
+ control area of the package. They must be proper exectuable
+ files; if they are scripts (which is recommended) they must
+ start with the usual <tt>#!</tt> convention. They should be
+ readable and executable to anyone, and not world-writeable.
+ </p>
+
+ <p>
+ <prgn>dpkg</prgn> 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</prgn> can
+ stop its processing. For shell scripts this means that you
+ <em>almost always</em> need to use <tt>set -e</tt> (this is
+ usually true when writing shell scripts, in fact). It is
+ also important, of course, that they don't exit with a
+ non-zero status if everything went well.
+ </p>
+
+ <p>
+ 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>
+
+ <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>
+
+ <p>
+ Broadly speaking the <prgn>preinst</prgn> is called before
+ (a particular version of) a package is installed, and the
+ <prgn>postinst</prgn> afterwards; the <prgn>prerm</prgn>
+ before (a version of) a package is removed and the
+ <prgn>postrm</prgn> afterwards.
+ </p>
+ <!--
+ next paragraph by Guy Maor to close bug #2481
+ -->
+
+ <p> Programs called from maintainer scripts should not
+ normally have a path prepended to them. Before installation
+ is started <prgn>dpkg</prgn> checks to see if the programs
+ <prgn>ldconfig</prgn>, <prgn>start-stop-daemon</prgn>,
+ <prgn>install-info</prgn>, and <prgn>update-rc.d</prgn> can
+ be found via the <tt>PATH</tt> environment variable. Those
+ programs, and any other program that one would expect to on
+ the <tt>PATH</tt>, should thus be invoked without an
+ absolute pathname. Maintainer scripts should also not reset
+ the <tt>PATH</tt>, though they might choose to modify it by
+ pre- or appending package-specific directories. These
+ considerations really apply to all shell scripts.</p>
+ </sect>
+
+ <sect id="mscriptsinstact"><heading>Summary of ways maintainer
+ scripts are called
+ </heading>
+
+ <p>
+ <list compact="compact">
+ <item>
+ <p><var>new-preinst</var> <tt>install</tt></p>
+ </item>
+ <item>
+ <p><var>new-preinst</var> <tt>install</tt>
+ <var>old-version</var></p>
+ </item>
+ <item>
+ <p><var>new-preinst</var> <tt>upgrade</tt>
+ <var>old-version</var></p>
+ </item>
+ <item>
+ <p><var>old-preinst</var> <tt>abort-upgrade</tt>
+ <var>new-version</var>
+ </p>
+ </item>
+ </list>
+
+ <p>
+ <list compact="compact">
+ <item>
+ <p><var>postinst</var> <tt>configure</tt>
+ <var>most-recently-configured-version</var></p>
+ </item>
+ <item>
+ <p><var>old-postinst</var> <tt>abort-upgrade</tt>
+ <var>new version</var></p>
+ </item>
+ <item>
+ <p><var>conflictor's-postinst</var> <tt>abort-remove</tt>
+ <tt>in-favour</tt> <var>package</var>
+ <var>new-version</var></p>
+ </item>
+ <item>
+ <p>
+ <var>deconfigured's-postinst</var>
+ <tt>abort-deconfigure</tt> <tt>in-favour</tt>
+ <var>failed-install-package</var> <var>version</var>
+ <tt>removing</tt> <var>conflicting-package</var>
+ <var>version</var>
+ </p>
+ </item>
+ </list>
+
+ <p>
+ <list compact="compact">
+ <item>
+ <p><var>prerm</var> <tt>remove</tt></p>
+ </item>
+ <item>
+ <p><var>old-prerm</var> <tt>upgrade</tt>
+ <var>new-version</var></p>
+ </item>
+ <item>
+ <p><var>new-prerm</var> <tt>failed-upgrade</tt>
+ <var>old-version</var></p>
+ </item>
+ <item>
+ <p><var>conflictor's-prerm</var> <tt>remove</tt>
+ <tt>in-favour</tt> <var>package</var>
+ <var>new-version</var></p>
+ </item>
+ <item>
+ <p>
+ <var>deconfigured's-prerm</var> <tt>deconfigure</tt>
+ <tt>in-favour</tt> <var>package-being-installed</var>
+ <var>version</var> <tt>removing</tt>
+ <var>conflicting-package</var>
+ <var>version</var>
+ </p>
+ </item>
+ </list>
+
+ <p>
+ <list compact="compact">
+ <item>
+ <p><var>postrm</var> <tt>remove</tt></p>
+ </item>
+ <item>
+ <p><var>postrm</var> <tt>purge</tt></p>
+ </item>
+ <item>
+ <p>
+ <var>old-postrm</var> <tt>upgrade</tt>
+ <var>new-version</var></p>
+ </item>
+ <item>
+ <p><var>new-postrm</var> <tt>failed-upgrade</tt>
+ <var>old-version</var></p>
+ </item>
+ <item>
+ <p><var>new-postrm</var> <tt>abort-install</tt></p>
+ </item>
+ <item>
+ <p><var>new-postrm</var> <tt>abort-install</tt>
+ <var>old-version</var></p>
+ </item>
+ <item>
+ <p><var>new-postrm</var> <tt>abort-upgrade</tt>
+ <var>old-version</var></p>
+ </item>
+ <item>
+ <p>
+ <var>disappearer's-postrm</var> <tt>disappear</tt>
+ <var>r>overwrit</var>r>
+ <var>new-version</var></p></item>
+ </list>
+ </p>
+
+
+ <sect id="unpackphase"><heading>Details of unpack phase of
+ installation or upgrade
+ </heading>
+
+ <p>
+ The procedure on installation/upgrade/overwrite/disappear
+ (ie, when running <tt>dpkg --unpack</tt>, or the unpack
+ stage of <tt>dpkg
+ --install</tt>) 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>
+ <p>
+ <enumlist>
+ <item>
+ <p>If a version the package is already
+ installed, call
+ <example>
+ <var>old-prerm</var> upgrade <var>new-version</var>
+ </example></p>
+ </item>
+ <item>
+ <p>
+ If this gives an error (ie, a non-zero exit
+ status), dpkg will attempt instead:
+ <example>
+ <var>new-prerm</var> failed-upgrade <var>old-version</var>
+ </example>
+ Error unwind, for both the above cases:
+ <example>
+ <var>old-postinst</var> abort-upgrade <var>new-version</var>
+ </example>
+ </p>
+ </item>
+ </enumlist>
+ </p>
+ </item>
+ <item>
+ <p>If a `conflicting' package is being removed at the same time:
+ <enumlist>
+ <item>
+ <p>
+ If any packages depended on that conflicting
+ package and <tt>--auto-deconfigure</tt> is
+ specified, call, for each such package:
+ <example>
+ <var>deconfigured's-prerm</var> deconfigure \
+ in-favour <var>package-being-installed</var> <var>version</var> \
+ removing <var>conflicting-package</var> <var>version</var>
+ </example>
+ Error unwind:
+ <example>
+ <var>deconfigured's-postinst</var> abort-deconfigure \
+ in-favour <var>package-being-installed-but-failed</var> <var>version</var> \
+ removing <var>conflicting-package</var> <var>version</var>
+ </example>
+ The deconfigured packages are marked as
+ requiring configuration, so that if
+ <tt>--install</tt> is used they will be
+ configured again if possible.</p>
+ </item>
+ <item>
+ <p>To prepare for removal of the conflicting package, call:
+ <example>
+ <var>conflictor's-prerm</var> remove in-favour <var>package</var> <var>new-version</var>
+ </example>
+ Error unwind:
+ <example>
+ <var>conflictor's-postinst</var> abort-remove \
+ in-favour <var>package</var> <var>new-version</var>
+ </example>
+ </p>
+ </item>
+ </enumlist>
+ </p>
+ </item>
+ <item>
+ <p>
+ <enumlist>
+ <item>
+ <p>If the package is being upgraded, call:
+ <example>
+ <var>new-preinst</var> upgrade <var>old-version</var>
+ </example></p>
+ </item>
+ <item>
+ <p>
+ Otherwise, if the package had some configuration
+ files from a previous version installed (ie, it
+ is in the `configuration files only' state):
+ <example>
+ <var>new-preinst</var> install <var>old-version</var>
+ </example></p>
+
+ <item>
+ <p>Otherwise (ie, the package was completely purged):
+ <example>
+ <var>new-preinst</var> install
+ </example>
+ Error unwind versions, respectively:
+ <example>
+ <var>new-postrm</var> abort-upgrade <var>old-version</var>
+ <var>new-postrm</var> abort-install <var>old-version</var>
+ <var>new-postrm</var> abort-install
+ </example>
+ </p>
+ </item>
+ </enumlist>
+ </p>
+ </item>
+ <item>
+
+ <p>
+ The new package's files are unpacked, overwriting any
+ that may be on the system already, for example any
+ from the old version of the same package or from
+ another package (backups of the old files are left
+ around, and if anything goes wrong dpkg will attempt
+ to put them back as part of the error unwind).
+ </p>
+
+ <p>
+ It is an error for a package to contains files which
+ are on the system in another package, unless
+ <tt>Replaces</tt> is used (see <ref id="replaces">).
+ Currently the <tt>--force-overwrite</tt> flag is
+ enabled, downgrading it to a warning, but this may not
+ always be the case.
+ </p>
+
+ <p>
+ It is a more serious error for a package to contain a
+ plain file or other kind of nondirectory where another
+ package has a directory (again, unless
+ <tt>Replaces</tt> is used). This error can be
+ overridden if desired using
+ <tt>--force-overwrite-dir</tt>, but this is not
+ advisable.
+ </p>
+
+ <p>
+ Packages which overwrite each other's files produce
+ 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>
+ <p>
+ Part of the problem is due to what is arguably a
+ bug in <prgn>dpkg</prgn> .
+ </p>
+ </footnote>
+ </p>
+
+ <p>
+ A directory will never be replaced by a symbolic links
+ to a directory or vice versa; instead, the existing
+ state (symlink or not) will be left alone and
+ <prgn>dpkg</prgn> will follow the symlink if there is
+ one.</p>
+ </item>
+
+ <item>
+
+ <p><enumlist>
+ <item>
+ <p>If the package is being upgraded, call
+ <example>
+ <var>old-postrm</var> upgrade <var>new-version</var>
+ </example></p>
+ </item>
+ <item>
+ <p>If this fails, <prgn>dpkg</prgn> will attempt:
+ <example>
+ <var>new-postrm</var> failed-upgrade <var>old-version</var>
+ </example>
+ Error unwind, for both cases:
+ <example>
+ <var>old-preinst</var> abort-upgrade <var>new-version</var>
+ </example>
+ </p>
+ </item>
+ </enumlist>
+ This is the point of no return - if <prgn>dpkg</prgn>
+ gets this far, it won't back off past this point if an
+ error occurs. This will leave the package in a fairly
+ bad state, which will require a successful
+ reinstallation to clear up, but it's when
+ <prgn>dpkg</prgn> starts doing things that are
+ irreversible.</p>
+ </item>
+ <item>
+ <p>
+ Any files which were in the old version of the package
+ but not in the new are removed.</p>
+ </item>
+ <item>
+ <p>The new file list replaces the old.</p>
+ </item>
+ <item>
+ <p>The new maintainer scripts replace the old.</p>
+ </item>
+
+ <item>
+ <p>Any packages all of whose files have been overwritten during the
+ installation, and which aren't required for
+ dependencies, are considered to have been removed.
+ For each such package,
+ <enumlist>
+ <item>
+ <p><prgn>dpkg</prgn> calls:
+ <example>
+ <var>disappearer's-postrm</var> disappear \
+ <var>overwriter</var> <var>overwriter-version</var>
+ </example></p>
+ </item>
+ <item>
+ <p>The package's maintainer scripts are removed.
+ </p>
+ </item>
+ <item>
+ <p>
+ It is noted in the status database as being in a
+ sane state, namely not installed (any conffiles
+ it may have are ignored, rather than being
+ removed by <prgn>dpkg</prgn>). Note that
+ disappearing packages do not have their prerm
+ called, because <prgn>dpkg</prgn> doesn't know
+ in advance that the package is going to
+ vanish.
+ </p>
+ </item>
+ </enumlist>
+ </p>
+ </item>
+ <item>
+ <p>
+ Any files in the package we're unpacking that are also
+ listed in the file lists of other packages are removed
+ from those lists. (This will lobotomise the file list
+ of the `conflicting' package if there is one.)
+ </p>
+ </item>
+ <item>
+ <p>
+ The backup files made during installation, above, are
+ deleted.
+ </p>
+ </item>
+
+ <item>
+ <p>
+ The new package's status is now sane, and recorded as
+ `unpacked'. Here is another point of no return - if
+ the conflicting package's removal fails we do not
+ unwind the rest of the installation; the conflicting
+ package is left in a half-removed limbo.
+ </p>
+ </item>
+ <item>
+ <p>
+ If there was a conflicting package we go and do the
+ removal actions (described below), starting with the
+ removal of the conflicting package's files (any that
+ are also in the package being installed have already
+ been removed from the conflicting package's file list,
+ and so do not get removed now).
+ </p>
+ </item>
+ </enumlist>
+ </p>
+ </sect>
+
+ <sect><heading>Details of configuration
+ </heading>
+
+ <p>
+ When we configure a package (this happens with <tt>dpkg
+ --install</tt>, or with <tt>--configure</tt>), we first
+ update the conffiles and then call:
+ <example>
+ <var>postinst</var> configure <var>most-recently-configured-version</var>
+ </example>
+ </p>
+
+ <p>
+ No attempt is made to unwind after errors during
+ configuration.
+ </p>
+
+ <p>
+ If there is no most recently configured version
+ <prgn>dpkg</prgn> will pass a null argument; older versions
+ of dpkg may pass <tt><unknown></tt> (including the
+ angle brackets) in this case. Even older ones do not pass a
+ second argument at all, under any circumstances.
+ </p>
+ </sect>
+
+ <sect><heading>Details of removal and/or configuration purging
+ </heading>
+
+ <p>
+ <enumlist>
+ <item>
+ <p><example>
+ <var>prerm</var> remove
+ </example></p>
+ </item>
+ <item>
+ <p>
+ The package's files are removed (except conffiles).
+ </p>
+ </item>
+ <item>
+ <p><example>
+ <var>postrm</var> remove
+ </example></p>
+ </item>
+ <item>
+ <p>All the maintainer scripts except the postrm are removed.
+ </p>
+
+ <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</prgn>
+ status.</p>
+ </item>
+ <item>
+ <p>
+ The conffiles and any backup files (<tt>~</tt>-files,
+ <tt>#*#</tt> files, <tt>%</tt>-files,
+ <tt>.dpkg-{old,new,tmp}</tt>, etc.) are removed.</p>
+ </item>
+ <item>
+ <p><example>
+ <var>postrm</var> purge
+ </example></p>
+ </item>
+ <item>
+ <p>The package's file list is removed.</p>
+ </item>
+ </enumlist>
+ No attempt is made to unwind after errors during
+ removal.</p>
+ </sect>
+ </chapt>
+
+ <chapt id="descriptions"><heading>Descriptions of packages - the
+ <tt>Description</tt> field
+ </heading>
+
+ <p>
+ The <tt>Description</tt> control file field is used by
+ <prgn>dselect</prgn> when the user is selecting which packages
+ to install and by <prgn>dpkg</prgn> when it displays
+ information about the status of packages and so forth. It is
+ included on the FTP site in the <prgn>Packages</prgn> files,
+ and may also be used by the Debian WWW pages.
+ </p>
+
+ <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>
+
+ <p>
+ The field's format is as follows:
+ <example>
+ Description: <var>single line synopsis</var>
+ <var>extended description over several lines</var>
+ </example>
+ </p>
+
+ <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><heading>Types of formatting line in the extended
+ description
+ </heading>
+
+ <p>
+ <list>
+ <item>
+ <p>
+ 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.
+ </p>
+ </item>
+
+ <item>
+ <p>
+ 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).
+ </p>
+ </item>
+
+ <item>
+ <p>Those containing a single space followed by a single full stop
+ character. These are rendered as blank lines. This
+ is the <em>only</em> way to get a blank line - see
+ below.</p>
+ </item>
+
+ <item>
+ <p>
+ Those containing a space, a full stop and some more
+ characters. These are for future expansion. Do not
+ use them.</p>
+ </item>
+ </list>
+ </p>
+ </sect>
+
+ <sect><heading>Notes about writing descriptions
+ </heading>
+
+ <p>
+ <em>Always</em> 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</prgn>
+ <footnote>
+ <p>
+ Version 0.93.23 or later.
+ </p>
+ </footnote> to produce a syntax error when trying to build
+ the package. If you force it to build anyway
+ <prgn>dpkg</prgn> will refuse to install the resulting
+ mess.
+ </p>
+
+ <p>
+ <em>Do not</em> include any completely <em>empty</em>
+ lines. These separate different records in the Packages file
+ and different packages in the <tt>debian/control</tt> file,
+ and are forbidden in package control files. See the
+ previous paragraph for what happens if you get this wrong.
+ </p>
+
+ <p>
+ The single line synopsis should be kept brief - certainly
+ under 80 characters. <prgn>dselect</prgn> 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>
+
+ <p>
+ Do not include the package name in the synopsis line. The
+ display software knows how to display this already, and you
+ do not need to state it. Remember that in many situations
+ the user may only see the synopsis line - make it as
+ informative as you can.
+ </p>
+
+ <p>
+ The extended description should describe what the package
+ does and how it relates to the rest of the system (in terms
+ of, for example, which subsystem it is which part of).
+ </p>
+
+ <p>
+ The blurb that comes with a program in its announcements
+ and/or <prgn>README</prgn> files is rarely suitable for use
+ in a description. It is usually aimed at people who are
+ already in the community where the package is used. 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>
+
+ <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>
+
+ <p>
+ You may include information about dependencies and so forth
+ in the extended description, if you wish.
+ </p>
+
+ <p>
+ Do not use tab characters. Their effect is not predictable.
+ </p>
+
+ <p>
+ Do not try to linewrap the summary (the part on the same
+ line as the field name <tt>Description</tt>) 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.</p>
+ </sect>
+
+ <sect><heading>Example description in control file for Smail
+ </heading>
+
+ <p>
+ <example>
+ Package: smail
+ Version: 3.1.29.1-13
+ Maintainer: Ian Jackson <iwj10@cus.cam.ac.uk>
+ 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>
+ </p>
+ </sect>
+ </chapt>
+
+ <chapt id="relationships"><heading>Declaring relationships between
+ packages
+ </heading>
+
+ <p>
+ Packages can declare in their control file that they have
+ certain relationships to other packages - for example, that
+ they may not be installed at the same time as certain other
+ packages, and/or that they depend on the presence of others,
+ or that they should overwrite files in certain other packages
+ if present.
+ </p>
+
+ <p>
+ This is done using the <tt>Depends</tt>, <tt>Recommends</tt>,
+ <tt>Suggests</tt>, <tt>Conflicts</tt>, <tt>Provides</tt> and
+ <tt>Replaces</tt> control file fields.
+ </p>
+
+ <sect id="depsyntax"><heading>Syntax of relationship fields
+ </heading>
+
+ <p>
+ These fields all have a uniform syntax. They are a list of
+ package names separated by commas.
+ </p>
+
+ <p>
+ In <tt>Depends</tt>, <tt>Recommends</tt>, <tt>Suggests</tt>
+ and <tt>Pre-Depends</tt> (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>|</tt> (pipe symbols).
+ </p>
+
+ <p>
+ All the fields except <tt>Provides</tt> may restrict their
+ applicability to particular versions of each named package.
+ This is done in parentheses after each individual package
+ name; the parentheses should contain a relation from the
+ list below followed by a version number, in the format
+ described in <ref id="versions">.
+ </p>
+
+ <p>
+ The relations allowed are <tt><<</tt>, <tt><=</tt>,
+ <tt>=</tt>, <tt>>=</tt> and <tt>>></tt> for
+ strictly earlier, earlier or equal, exactly equal, later or
+ equal and strictly later, respectively. The forms
+ <tt><</tt> and <tt>></tt> were used to mean
+ earlier/later or equal, rather than strictly earlier/later,
+ so they should not appear in new packages (though
+ <prgn>dpkg</prgn> still supports them).
+ </p>
+
+ <p>
+ Whitespace may appear at any point in the version
+ specification, and must appear where it's necessary to
+ disambiguate; it is not otherwise significant. For
+ consistency and in case of future changes to
+ <prgn>dpkg</prgn> it is recommended that a single space be
+ used after a version relationship and before a version
+ number; it is usual also to put a single space after each
+ comma, on either side of each vertical bar, and before each
+ open parenthesis.
+ </p>
+
+ <p>
+ For example:
+ <example>
+ Package: metamail
+ Version: 2.7-3
+ Depends: libc5 (>= 5.2.18-4), mime-support, csh | tcsh
+ </example>
+ </p>
+ </sect>
+
+ <sect><heading>Dependencies - <tt>Depends</tt>, <tt>Recommends</tt>,
+ <tt>tt>Sugge</tt>tt>, <tt>Pre-Depends</tt>
+ </heading>
+
+ <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>
+
+ <p>
+ All but <tt>Pre-Depends</tt> (discussed below) take effect
+ <em>only</em> when a package is to be configured. They do
+ not prevent a package being on the system in an unconfigured
+ state while its dependencies are unsatisfied, and it is
+ possible to replace a package whose dependencies are
+ satisfied and which is properly installed with a different
+ version whose dependencies are not and cannot be satisfied;
+ when this is done the depending package will be left
+ unconfigured (since attempts to configure it will give
+ errors) and will not function properly.
+ </p>
+
+ <p>
+ For this reason packages in an installation run are usually
+ all unpacked first and all configured later; this gives
+ later versions of packages with dependencies on later
+ versions of other packages the opportunity to have their
+ dependencies satisfied.
+ </p>
+
+ <p>
+ Thus <tt>Depends</tt> allows package maintainers to impose
+ an order in which packages should be configured.
+ <taglist>
+ <tag><tt>Depends</tt></tag>
+ <item>
+
+ <p>This declares an absolute dependency.
+ </p>
+
+ <p>
+ <prgn>dpkg</prgn> 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>
+ <p>
+ Current versions (1.2.4) of <prgn>dpkg</prgn> have
+ a bug in this area which will cause some of these
+ problems to be ignored.
+ </p>
+ </footnote>, unless <tt>--auto-deconfigure</tt> is
+ specified, in which case those packages will be
+ deconfigured before the installation proceeds.
+ </p>
+
+ <p>
+ <prgn>dselect</prgn> makes it hard for the user to
+ select packages for installation, removal or upgrade
+ in a way that would mean that packages'
+ <prgn>Depends</prgn> fields would be unsatisfied. The
+ user can override this if they wish, for example if
+ they know that <prgn>dselect</prgn> has an out-of-date
+ view of the real package relationships.
+ </p>
+
+ <p>
+ The <tt>Depends</tt> field should be used if the
+ depended-on package is required for the depending
+ package to provide a significant amount of
+ functionality.</p>
+ </item>
+
+ <tag><tt>Recommends</tt></tag>
+ <item>
+ <p>This declares a strong, but not absolute, dependency.
+ </p>
+
+ <p>
+ <tt>Recommends</tt> is ignored by <prgn>dpkg</prgn>,
+ so that users using the command-line (who are presumed
+ to know what they're doing) will not be impeded.
+ </p>
+
+ <p>
+ It is treated by <prgn>dselect</prgn> exactly as
+ <tt>Depends</tt> is; this makes it hard for the user
+ to select things so as to leave <tt>Recommends</tt>
+ fields unsatisfied, but they are able to do so by
+ being persistent.
+ </p>
+
+ <p>
+ The <tt>Recommends</tt> field should list packages
+ that would be found together with this one in all but
+ unusual installations.</p>
+ </item>
+
+ <tag><tt>Suggests</tt></tag>
+ <item>
+
+ <p>
+ This is used to declare that one package may be more
+ useful with one or more others. Using this field
+ tells the packaging system and the user that the
+ listed packages are be related to this one and can
+ perhaps enhance its usefulness, but that installing
+ this one without them is perfectly reasonable.
+ </p>
+
+ <p>
+ <prgn>dselect</prgn> will offer suggsted packages to
+ the system administrator when they select the
+ suggesting package, but the default is not to install
+ the suggested package.</p>
+ </item>
+
+ <tag><tt>Pre-Depends</tt></tag>
+ <item>
+
+ <p>This field is like <tt>Depends</tt>, except that it also forces
+ <prgn>dpkg</prgn> to complete installation of the
+ packages named before even starting the installation
+ of the package which declares the predependency.
+ </p>
+
+ <p>
+ <prgn>dselect</prgn> 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>
+
+ <p>
+ However, this process is slow (because it requires
+ repeated invocations of <prgn>dpkg</prgn>) and
+ troublesome (because it requires guessing where to
+ find the appropriate files).
+ </p>
+
+ <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</tt> should be used sparingly,
+ preferably only by packages whose premature upgrade or
+ installation would hamper the ability of the system to
+ continue with any upgrade that might be in progress.
+ </p>
+
+ <p>
+ When the package declaring it is being configured, a
+ <tt>Pre-Dependency</tt> will be considered satisfied
+ only if the depending package has been correctly
+ configured, just as if an ordinary <tt>Depends</tt>
+ had been used.
+ </p>
+
+ <p>
+ However, when a package declaring a 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</tt> field.
+ </p>
+ </item>
+ </taglist>
+ </p>
+ <p>
+ When selecting which level of dependency to use you should
+ consider how important the depended-on package is to the
+ functionality of the one declaring the dependency. Some
+ packages are composed of components of varying degrees of
+ importance. Such a package should list using
+ <tt>Depends</tt> the package(s) which are required by the
+ more important components. The other components'
+ requirements may be mentioned as Suggestions or
+ Recommendations, as appropriate to the components' relative
+ importance.
+ </p>
+
+ <sect1><heading>Dependencies on shared libraries
+ </heading>
+
+ <p>
+ The dependency fields listed above are used by packages
+ which need shared libraries to declare dependencies on the
+ appropriate packages.
+ </p>
+
+ <p>
+ These dependencies are usually determined automatically
+ using <prgn>dpkg-shlibdeps</prgn> and inserted in the
+ package control file using the control file substitution
+ variables mechanism; see <ref id="srcsubstvars"> and
+ <ref id="sourcetools">.
+ </p>
+ </sect1>
+
+ <sect1><heading>Deconfiguration due to removal during bulk
+ installations
+ </heading>
+
+ <p>
+ If <prgn>dpkg</prgn> 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</prgn> will usually not remove the conflicting
+ package and halt with an error.
+ </p>
+
+ <p>
+ However, if the <tt>--auto-deconfigure</tt> (<tt>-B</tt>)
+ option is used <prgn>dpkg</prgn> 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</prgn> 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>
+
+ <p>
+ <prgn>dselect</prgn> supplies this argument to
+ <prgn>dpkg</prgn> when it invokes it, so that bulk
+ installations proceed smoothly.
+ </p>
+ </sect1>
+
+ <sect id="conflicts"><heading>Alternative packages -
+ <tt>tt>Confli</tt>tt> and <tt>Replaces</tt>
+ </heading>
+
+ <p>
+ When one package declares a conflict with another
+ <prgn>dpkg</prgn> will refuse to allow them to be installed
+ on the system at the same time.
+ </p>
+
+ <p>
+ If one package is to be installed, the other must be removed first -
+ if the package being installed is marked as replacing (<ref
+ id="replaces">) the one on the system, or the one on the system is
+ marked as deselected, or both packages are marked
+ <tt>Essential</tt>, then <prgn>dpkg</prgn> will
+ automatically remove the package which is causing the
+ conflict, otherwise it will halt the installation of the new
+ package with an error.
+ </p>
+
+ <p>
+ <prgn>dselect</prgn> 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</prgn> will
+ select one of the packages for removal, and the user must
+ make sure it is the right one. In the future
+ <prgn>dselect</prgn> will look for the presence of a
+ <tt>Replaces</tt> field to help decide which package should
+ be installed and which removed.
+ </p>
+
+ <p>
+ A package will not cause a conflict merely because its
+ configuration files are still installed; it must be at least
+ half-installed.
+ </p>
+
+ <p>
+ A special exception is made for packages which declare a
+ conflict with their own package name, or with a virtual
+ package which they provide (see below): this does not
+ prevent their installation, and allows a package to conflict
+ with others providing a replacement for it. You use this
+ feature when you want the package in question to be the only
+ package providing something.
+ </p>
+
+ <p>
+ A <tt>Conflicts</tt> entry should almost never have an
+ `earlier than' version clause. This would prevent
+ <prgn>dpkg</prgn> from upgrading or installing the package
+ which declared such a conflict until the upgrade or removal
+ of the conflicted-with package had been completed. This
+ aspect of installation ordering is not handled by
+ <prgn>dselect</prgn>, so that the use <tt>Conflicts</tt> in
+ this way is likely to cause problems for `bulk run' upgrades
+ and installations.
+ </p>
+ </sect>
+
+ <sect id="virtual"><heading>Virtual packages - <tt>Provides</tt>
+ </heading>
+
+ <p>
+ As well as the names of actual (`concrete') packages, the
+ package relationship fields <tt>Depends</tt>,
+ <tt>Recommends</tt>, <tt>Suggests</tt> and
+ <tt>Conflicts</tt> may mention virtual packages.
+ </p>
+
+ <p>
+ A virtual package is one which appears in the
+ <tt>Provides</tt> control file field of another package.
+ The effect is as if the package(s) which provide a
+ particular virtual package name had been listed by name
+ everywhere were the virtual package name appears.
+ </p>
+
+ <p>
+ If there are both a real and a virtual package of the same
+ name then the dependency may be satisfied (or the conflict
+ caused) by either the real package or any of the virtual
+ packages which provide it. This is so that, for example,
+ supposing we have
+ <example>
+ Package: vm
+ Depends: emacs
+ </example>
+ and someone else releases an xemacs package they can say
+ <example>
+ Package: xemacs
+ Provides: emacs
+ </example> and all will work in the interim (until a purely
+ virtual package name is decided on and the <tt>emacs</tt>
+ and <tt>vm</tt> packages are changed to use it).
+ </p>
+
+ <p>
+ If a dependency or a conflict has a version number attached
+ then only real packages will be considered to see whether
+ the relationship is satisfied (or the prohibition violated,
+ for a conflict) - it is assumed that a real package which
+ provides virtual package is not of the `right' version. So,
+ a <tt>Provides</tt> field may not contain version numbers,
+ and the version number of the concrete package which
+ provides a particular virtual package will not be looked at
+ when considering a dependency on or conflict with the
+ virtual package name.
+ </p>
+
+ <p>
+ It is likely that the ability will be added in a future
+ release of <prgn>dpkg</prgn> to specify a version number for
+ each virtual package it provides. This feature is not yet
+ present, however, and is expected to be used only
+ infrequently.
+ </p>
+
+ <p>
+ If you want to specify which of a set of real packages should be the
+ default to satisfy a particular dependency on a virtual package, you
+ should list the real package as alternative before the virtual.
+ </p>
+ </sect>
+
+
+ <sect id="replaces"><heading><tt>Replaces</tt> - overwriting
+ files and replacing packages
+ </heading>
+
+ <p>
+ The <tt>Replaces</tt> control file field has two purposes,
+ which come into play in different situations.
+ </p>
+
+ <p>
+ Virtual packages (<ref id="virtual">) are not considered
+ when looking at a <tt>Replaces</tt> field - the packages
+ declared as being replaced must be mentioned by their real
+ names.
+ </p>
+
+ <sect1><heading>Overwriting files in other packages
+ </heading>
+
+ <p>
+ Firstly, as mentioned before, it is usually an error for a
+ package to contains files which are on the system in
+ another package, though currently the
+ <tt>--force-overwrite</tt> flag is enabled by default,
+ downgrading the error to a warning,
+ </p>
+
+ <p>
+ If the overwriting package declares that it replaces the
+ one containing the file being overwritten then
+ <prgn>dpkg</prgn> will proceed, and replace the file from
+ the old package with that from the new. The file will no
+ longer be listed as `owned' by the old package.
+ </p>
+
+ <p>
+ If a package is completely replaced in this way, so that
+ <prgn>dpkg</prgn> does not know of any files it still
+ contains, it is considered to have disappeared. It will
+ be marked as not wanted on the system (selected for
+ removal) and not installed. Any conffiles details noted
+ in the package will be ignored, as they will have been
+ taken over by the replacing package(s). The package's
+ <prgn>postrm</prgn> script will be run to allow the
+ package to do any final cleanup required. See <ref
+ id="mscriptsinstact">.
+ </p>
+
+ <p>
+ In the future <prgn>dpkg</prgn> will discard files which
+ 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>
+
+ <p>
+ This usage of <tt>Replaces</tt> only takes effect when
+ both packages are at least partially on the system at
+ once, so that it can only happen if they do not conflict
+ or if the conflict has been overridden.</p>
+ </sect1>
+
+ <sect1><heading>Replacing whole packages, forcing their
+ removal
+ </heading>
+
+ <p>
+ Secondly, <tt>Replaces</tt> allows <prgn>dpkg</prgn> and
+ <prgn>dselect</prgn> 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</em>
+ conflict, so that the two effects do not interfere with
+ each other.
+ </p>
+ </sect1>
+ </sect>
+
+ <sect><heading>Defaults for satisfying dependencies - ordering
+ </heading>
+
+ <p>
+ Ordering is significant in dependency fields.
+ </p>
+
+ <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>
+
+ <p>
+ In the absence of other information <prgn>dselect</prgn>
+ will offer a default selection of the first named package in
+ a list of alternatives.
+ </p>
+
+ <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>
+
+ <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>
+
+ <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>
+
+ <p>
+ If <prgn>emacs</prgn> and <prgn>info</prgn> both have the
+ same priority then <prgn>dselect</prgn>'s choice is
+ essentially random. Better would be
+ <example>
+ Package: glibcdoc
+ Recommends: info | info-browser
+ </example>
+ so that <prgn>dselect</prgn> defaults to selecting the
+ lightweight standalone info browser.
+ </p>
+ </sect>
+ </chapt>
+
+ <chapt id="conffiles"><heading>Configuration file handling
+ </heading>
+
+ <p>
+ <prgn>dpkg</prgn> can do a certain amount of automatic
+ handling of package configuration files.
+ </p>
+
+ <p>
+ Whether this mechanism is appropriate depends on a number of
+ factors, but basically there are two approaches to any
+ particular configuration file.
+ </p>
+
+ <p>
+ The easy method is to ship a best-effort configuration in the
+ package, and use <prgn>dpkg</prgn>'s conffile mechanism to
+ handle updates. If the user is unlikely to want to edit the
+ file, but you need them to be able to without losing their
+ changes, and a new package with a changed version of the file
+ is only released infrequently, this is a good approach.
+ </p>
+
+ <p>
+ The hard method is to build the configuration file from
+ scratch in the <prgn>postinst</prgn> script, and to take the
+ responsibility for fixing any mistakes made in earlier
+ versions of the package automatically. This will be
+ appropriate if the file is likely to need to be different on
+ each system.
+ </p>
+
+ <sect><heading>Automatic handling of configuration files by
+ <prgn>dpkg</prgn>
+ </heading>
+
+ <p>
+ A package may contain a control area file called
+ <tt>conffiles</tt>. 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>
+
+ <p>
+ When a package is upgraded <prgn>dpkg</prgn> will process
+ the configuration files during the configuration stage,
+ shortly before it runs the package's <prgn>postinst</prgn>
+ script,
+ </p>
+
+ <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>
+
+ <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>
+
+ <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>
+
+ <p>
+ When a package is installed for the first time
+ <prgn>dpkg</prgn> will install the file that comes with it,
+ unless that would mean overwriting a file already on the
+ filesystem.
+ </p>
+
+ <p>
+ However, note that <prgn>dpkg</prgn> will <em>not</em>
+ 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>
+
+ <p>
+ Note that a package should <em>not</em> modify a
+ <prgn>dpkg</prgn>-handled conffile in its maintainer
+ scripts. Doing this will lead to <prgn>dpkg</prgn> giving
+ the user confusing and possibly dangerous options for
+ conffile update when the package is upgraded.</p>
+ </sect>
+
+ <sect><heading>Fully-featured maintainer script configuration
+ handling
+ </heading>
+
+ <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</prgn> script.
+ </p>
+
+ <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>
+
+ <p>
+ When using this method there are a couple of important
+ issues which should be considered:
+ </p>
+
+ <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>
+
+ <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</tt>, by convention called
+ <tt><var>package</var>config</tt> and then run that if
+ appropriate from the post-installation script. The
+ <tt><var>package</var>config</tt> 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</tt> flag to
+ overwrite it.</p></sect>
+ </chapt>
+
+
+
+ <chapt id="alternatives"><heading>Alternative versions of an interface -
+ <prgn>update-alternatives</prgn>
+ </heading>
+
+ <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>
+
+ <p>
+ For example, there are several versions of the <prgn>vi</prgn>
+ editor, and there is no reason to prevent all of them from
+ being installed at once, each under their own name
+ (<prgn>nvi</prgn>, <prgn>vim</prgn> or whatever).
+ Nevertheless it is desirable to have the name <tt>vi</tt>
+ refer to something, at least by default.
+ </p>
+
+ <p>
+ If all the packages involved cooperate, this can be done with
+ <prgn>update-alternatives</prgn>.
+ </p>
+
+ <p>
+ Each package provides its own version under its own name, and
+ calls <prgn>update-alternatives</prgn> in its postinst to
+ register its version (and again in its prerm to deregister
+ it).
+ </p>
+
+ <p>
+ See the manpage <manref name="update-alternatives"
+ section="8"> for details.
+ </p>
+
+ <p>
+ If <prgn>update-alternatives</prgn> does not seem appropriate
+ you may wish to consider using diversions instead.</p>
+ </chapt>
+
+
+ <chapt id="diversions"><heading>Diversions - overriding a
+ package's version of a file
+ </heading>
+
+ <p>
+ It is possible to have <prgn>dpkg</prgn> 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>
+
+ <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>
+
+ <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>
+
+ <p>
+ There is a diversion list, which is read by <prgn>dpkg</prgn>,
+ and updated by a special program <prgn>dpkg-divert</prgn>.
+ Please see <manref name="dpkg-divert" section="8"> for full
+ details of its operation.
+ </p>
+
+ <p>
+ When a package wishes to divert a file from another, it should
+ call <prgn>dpkg-divert</prgn> in its preinst to add the
+ diversion and rename the existing file. For example,
+ supposing that a <prgn>smailwrapper</prgn> package wishes to
+ install a wrapper around <tt>/usr/sbin/smail</tt>:
+ <example>
+ if [ install = "$1" ]; then
+ dpkg-divert --package smailwrapper --add --rename \
+ --divert /usr/sbin/smail.real /usr/sbin/smail
+ fi
+ </example> Testing <tt>$1</tt> is necessary so that the script
+ doesn't try to add the diversion again when
+ <prgn>smailwrapper</prgn> is upgraded. The <tt>--package
+ smailwrapper</tt> ensures that <prgn>smailwrapper</prgn>'s
+ copy of <tt>/usr/sbin/smail</tt> can bypass the diversion and
+ get installed as the true version.
+ </p>
+
+ <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>
+
+ <p>
+ Do not attempt to divert a file which is vitally important for
+ the system's operation - when using <prgn>dpkg-divert</prgn>
+ there is a time, after it has been diverted but before
+ <prgn>dpkg</prgn> has installed the new version, when the file
+ does not exist.</p>
+ </chapt>
+
+
+ <chapt id="sharedlibs"><heading>Shared libraries
+ </heading>
+
+ <p>
+ Packages containing shared libraries must be constructed with
+ a little care to make sure that the shared library is always
+ available. This is especially important for packages whose
+ shared libraries are vitally important, such as the libc.
+ </p>
+
+ <p>
+ Firstly, your package should install the shared libraries
+ under their normal names. For example, the
+ <prgn>libgdbm1</prgn> package should install
+ <tt>libgdbm.so.1.7.3</tt> as
+ <tt>/usr/lib/libgdbm.so.1.7.3</tt>. The files should not be
+ renamed or relinked by any prerm or postrm scripts;
+ <prgn>dpkg</prgn> will take care of renaming things safely
+ without affecting running programs, and attempts to interfere
+ with this are likely to lead to problems.
+ </p>
+
+ <p>
+ Secondly, your package should include the symlink that
+ <prgn>ldconfig</prgn> would create for the shared libraries.
+ For example, the <prgn>libgdbm1</prgn> package should include
+ a symlink from <tt>/usr/lib/libgdbm.so.1</tt> to
+ <tt>libgdbm.so.1.7.3</tt>. This is needed so that
+ <prgn>ld.so</prgn> can find the library in between the time
+ <prgn>dpkg</prgn> installs it and <prgn>ldconfig</prgn> is run
+ in the <prgn>postinst</prgn> script. Futhermore, and <em>this
+ is very important</em>, the library must be placed before the
+ symlink pointing to it in the <tt>.deb</tt> file. This is so
+ that by the time <prgn>dpkg</prgn> comes to install the
+ symlink (overwriting the previous symlink pointing at an older
+ version of the library) the new shared library is already in
+ place. Currently the way to ensure the ordering is done
+ properly is to install the library in the appropriate
+ <tt>debian/tmp/.../lib</tt> directory before creating the
+ symlink, by putting the commands in the <tt>debian/rules</tt>
+ in the appropriate order.
+ </p>
+
+ <!--
+ next Paragraph added to close Bug #5299, Guy Maor
+ -->
+
+ <p>
+ Thirdly, the development package should contain a symlink for
+ the shared library without a version number. For example, the
+ <tt>libgdbm1-dev</tt> package should include a symlink from
+ <tt>/usr/lib/libgdm.so</tt> to <tt>libgdm.so.1.7.3</tt>. This
+ symlink is needed by <prgn>ld</prgn> when compiling packages
+ as it will only look for <tt>libgdm.so</tt> and
+ <tt>libgdm.a</tt> when compiling dynamically or statically,
+ respectively.
+ </p>
+
+ <!--
+ next paragraph changed by Christian Schwarz (see policy weekly #6)
+ -->
+
+ <p>
+ Any package installing shared libraries in a directory that's listed
+ in <tt>/etc/ld.so.conf</tt> or in one of the default library
+ directories of <prgn>ld.so</prgn> (currently, these are <tt>/usr/lib</tt>
+ and <tt>/lib</tt>) must call <prgn>ldconfig</prgn> in its <prgn>postinst</prgn>
+ script if and only if the first argument is `configure'. However, it
+ is important not to call <prgn>ldconfig</prgn> in the postrm or preinst
+ scripts in the case where the package is being upgraded (see <ref
+ id="unpackphase">), as <prgn>ldconfig</prgn> will see the temporary names
+ that <prgn>dpkg</prgn> uses for the files while it is
+ installing them and will make the shared library links point
+ to them, just before <prgn>dpkg</prgn> continues the
+ installation and removes the links!
+ </p>
+
+ <!--
+ moved from section 2.2 , DMorris
+ -->
+
+ <sect id="shlibs"><heading>The <tt>shlibs</tt> File Format
+ </heading>
+
+ <p>
+ This file is for use by <prgn>dpkg-shlibdeps</prgn> and is
+ required when your package provides shared libraries.
+ </p>
+
+ <p>
+ Each line is of the form:
+ <example>
+ <var>library-name</var> <var>version-or-soname</var> <var>dependencies ...</var>
+ </example>
+ </p>
+
+ <p>
+ <var>library-name</var> is the name of the shared library,
+ for example <tt>libc5</tt>.
+ </p>
+
+ <p>
+ <var>version-or-soname</var> is the soname of the library -
+ ie, the thing that must exactly match for the library to be
+ recognised by <prgn>ld.so</prgn>. Usually this is major
+ version number of the library.
+ </p>
+
+ <p>
+ <var>dependencies</var> has the same syntax as a dependency
+ field in a binary package control file. It should give
+ details of which package(s) are required to satisfy a binary
+ built against the version of the library contained in the
+ package. See <ref id="depsyntax">.
+ </p>
+
+ <p>
+ For example, if the package <tt>foo</tt> contains
+ <tt>libfoo.so.1.2.3</tt>, where the soname of the library is
+ <tt>libfoo.so.1</tt>, and the first version of the package
+ which contained a minor number of at least <tt>2.3</tt> was
+ <var>1.2.3-1</var>, then the package's <var>shlibs</var>
+ could say:
+ <example>
+ libfoo 1 foo (>= 1.2.3-1)
+ </example>
+ </p>
+
+ <p>
+ The version-specific dependency is to avoid warnings from
+ <prgn>ld.so</prgn> about using older shared libraries with
+ newer binaries.</p>
+ </sect>
+
+ <sect><heading>Further Technical information on
+ <tt>shlibs</tt></heading>
+
+
+ <!--
+ following section mostly provided by Heiko Schlittermann
+ edited by DMorris
+ -->
+
+ <sect1><heading><em>What</em> are the <tt>shlibs</tt> files?
+ </heading>
+
+ <p>
+ The <tt>debian/shlibs</tt> 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>
+
+ <p>
+ Other <tt>shlibs</tt> files that exist on a Debian system are
+ <list>
+ <item> <p><tt>/etc/dpkg/shlibs.default</tt></p></item>
+ <item> <p><tt>/etc/dpkg/shlibs.override</tt></p></item>
+ <item> <p><tt>/var/lib/dpkg/info/*.shlibs</tt></p></item>
+ <item> <p><tt>debian/shlibs.local</tt></p></item>
+ </list>
+ These files are used by <prgn>dpkg-shlibdeps</prgn> when
+ creating a binary package.</p>
+ </sect1>
+
+ <sect1><heading><em>How</em> does <prgn>dpkg-shlibdeps</prgn>
+ work?
+ </heading>
+
+ <p>
+ <prgn>dpkg-shlibdeps</prgn> calls <prgn>ldd</prgn> to
+ determine the shared libraries used by the compiled
+ binaries passed through its command line.
+ </p>
+
+ <p>
+ For each shared library, <prgn>dpkg-shlibdeps</prgn> needs to know
+ <list compact="compact">
+ <item><p>the package containing the library, and</p></item>
+ <item><p>the library version number,</p></item>
+
+ </list> <p>
+ it scans the following files in this order.
+ <enumlist compact="compact">
+ <item><p><tt>debian/shlibs.local</tt></p></item>
+ <item><p><tt>/etc/dpkg/shlibs.override</tt></p></item>
+ <item><p><tt>/var/lib/dpkg/info/*.shlibs</tt></p></item>
+ <item><p><tt>/etc/dpkg/shlibs.default</tt></p></item>
+ </enumlist></p>
+ </sect1>
+
+ <sect1><heading><em>Who</em> maintains the various
+ <tt>shlibs</tt> files?
+ </heading>
+
+ <p>
+ <list compact="compact">
+ <item>
+ <p><tt>/etc/dpkg/shlibs.default</tt> - the maintainer
+ of dpkg</p>
+ </item>
+ <item>
+ <p>
+ <tt>/var/lib/dpkg/info/<var>package</var>.shlibs</tt>
+ - the maintainer of each package</p>
+ </item>
+ <item>
+ <p>
+ <tt>/etc/dpkg/shlibs.override</tt> - the local
+ system administrator</p>
+ </item>
+ <item>
+ <p><tt>debian/shlibs.local</tt> - the maintainer of
+ the package
+ </p>
+ </item>
+ </list>
+ The <tt>shlibs.default</tt> file is managed by
+ <prgn>dpkg</prgn>. The entries in <tt>shlibs.default</tt>
+ that are provided by <prgn>dpkg</prgn> are just there to
+ fix things until the shared library packages all have
+ <tt>shlibs</tt> files.
+ </p>
+ </sect1>
+
+ <sect1><heading><em>How</em> to use <prgn>dpkg-shlibdeps</prgn> and
+ the <tt>shlibs</tt> files?
+ </heading>
+
+ <sect2><heading>If your package doesn't provide a shared
+ library
+ </heading>
+
+ <p>
+ Put a call to <prgn>dpkg-shlibdeps</prgn> into your
+ <tt>debian/rules</tt> file. If your package contains
+ only binaries (e.g. no scripts) use:
+ <example>
+ dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/*
+ </example>
+ If <prgn>dpkg-shlibdeps</prgn> doesn't complain, you're
+ done. If it does complain you might need to create your
+ own <tt>debian/shlibs.local</tt> file.</p>
+ </sect2>
+
+ <sect2><heading>If your package provides a shared library
+ </heading>
+
+ <p>
+ Create a <tt>debian/shlibs</tt> file and let
+ <tt>debian/rules</tt> install it in the control area:
+ <example>
+ install -m644 debian/shlibs debian/tmp/DEBIAN
+ </example>
+ If your package contains additional binaries see above.
+ </p>
+ </sect2>
+ </sect1>
+
+ <sect1><heading><em>How</em> to write
+ <tt>debian/shlibs.local</tt>
+ </heading>
+
+ <p>
+ This file is intended only as a <em>temporary</em> fix if
+ your binaries depend on a library which doesn't provide
+ its own <tt>/var/lib/dpkg/*.shlibs</tt> file yet.
+ </p>
+
+ <p>
+ Let's assume you are packaging a binary <tt>foo</tt>. 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</prgn>
+ <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</prgn> binary depends on the
+ <prgn>libbar</prgn> shared library, but no package seems
+ to provide a <tt>*.shlibs</tt> file in
+ <tt></tt>var/lib/dpkg/info/. Let's determine the package
+ responsible:
+ </p>
+
+ <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</prgn> package, version
+ 1.0-1 is the one we are using. Now we can create our own
+ <tt>debian/shlibs.local</tt> to temporarly fix the above
+ problem. Include the following line into your
+ <tt>debian/shlibs.local</tt> file.
+ <example>
+ libbar 1 bar1 (>= 1.0-1)
+ </example>
+ Now your package build should work. As soon as the
+ maintainer of <prgn>libbar1</prgn> provides a
+ <tt>shlibs</tt> file, you can remove your
+ <tt>debian/shlibs.local</tt> file.
+ </p>
+ </sect1>
+ </sect>
+ </chapt>
+
+ <chapt id="methif"><heading><prgn>dselect</prgn>'s interface to
+ its installation methods
+ </heading>
+
+ <p>
+ <prgn>dselect</prgn> calls scripts from its installation
+ methods when it needs to actually access data from the
+ distribution. The core program <prgn>dselect</prgn> itself
+ just calls these scripts and provides the package and access
+ method selection interfaces. The installation methods are
+ responsible for invoking <prgn>dpkg</prgn> as appropriate.
+ </p>
+
+ <p>
+ Each installation method has three scripts:
+ <list compact="compact">
+ <item><p>Setup installation parameters.</p></item>
+ <item><p>Update list of available packages.</p></item>
+ <item><p>Install.</p></item>
+ </list>
+
+ <p>
+ <prgn>dselect</prgn> searches for methods in
+ <tt>/usr/lib/dpkg/methods</tt> and
+ <tt>/usr/local/lib/dpkg/methods</tt>.
+ </p>
+
+ <sect><heading>Functions of the method scripts
+ </heading>
+
+ <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</tt> files can be found, or the tape or floppy
+ device to install from. It should store the responses under
+ <tt>/var/lib/dpkg/methods</tt> - see below. If no available
+ packages list is available it should perhaps offer to scan
+ the available packages.
+ </p>
+
+ <p>
+ The update script should obtain a list of available packages
+ if possible, and run <tt>dpkg --update-avail</tt>, <tt>dpkg
+ --merge-avail</tt> and/or <tt>dpkg --forget-old-unavail</tt>
+ to load it into <prgn>dpkg</prgn> and <prgn>dselect</prgn>'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</tt>.
+ </p>
+
+ <p>
+ The install script should feed all the available
+ <tt>.deb</tt> files to <tt>dpkg --iGOEB</tt> (this is
+ equivalent to <tt>dpkg --install
+ --refuse-downgrade --selected-only --skip-same-version
+ --auto-deconfigure</tt>). The <tt>-R</tt>
+ (<tt>--recursive</tt>) option for traversing subdirectories
+ may also be useful here).
+ </p>
+
+ <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>
+
+ <p>
+ If a method script succeeds (returns a zero exit status)
+ <prgn>dselect</prgn> will return immediately to the main
+ menu, with the `next' option highlighted ready for the user
+ to select it. If it fails <prgn>dselect</prgn> will display
+ a message and wait for the user to hit return.</p>
+ </sect>
+
+ <sect><heading>Location and arguments of the method scripts
+ </heading>
+
+ <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>
+
+ <p>
+ Each group of methods implemented by the same set of scripts
+ should have a subdirectory
+ <tt>/usr/lib/dpkg/methods/<var>group</var></tt> or
+ <tt>/usr/local/lib/dpkg/methods/<var>group</var></tt>,
+ containing:
+ <taglist compact="compact">
+ <tag><tt>names</tt></tag>
+ <item><p>a list of user-visible methods provided by these scripts.</p>
+ </item>
+ <tag><tt>setup</tt></tag>
+ <tag><tt>update</tt></tag>
+ <tag><tt>install</tt></tag>
+ <item><p>executable programs, the scripts themselves.</p>
+ </item>
+ <tag><tt>desc.<var>option</var></tt></tag>
+ <item><p>description file.</p></item>
+ </taglist>
+ </p>
+
+ <p>
+ <tt>names</tt> will be formatted as a list of lines, each containing:
+ <example>
+ <var>sequence</var> <var>method</var> <var>summary</var>
+ </example>
+ </p>
+ <p>
+ <var>sequence</var> is a two-digit number that will be used
+ much like <tt>rc.d</tt> prefixes to control the order in the
+ main menu. If in doubt use 50.
+ </p>
+
+ <p>
+ <var>method</var> is a name which is displayed by
+ <prgn>dselect</prgn> as the name of the method, and which
+ will be passed to <tt>setup</tt>, <tt>update</tt> and
+ <tt>unpack</tt> as their first argument.
+ </p>
+
+ <p>
+ <var>summary</var> is the brief description string for
+ <prgn>dselect</prgn>'s menu.
+ </p>
+
+ <p>
+ Each of the three scripts gets the same three arguments:
+ <var>vardir</var>, <var>group</var> and <var>method</var>.
+ <var>vardir</var> is the base directory for storing
+ <prgn>dpkg</prgn> and <prgn>dselect</prgn>'s state, usually
+ <tt>/var/lib/dpkg</tt>; this is passed in so that the
+ <tt>--admindir</tt> option to <prgn>dselect</prgn> is
+ honoured).
+ </p>
+
+ <p>
+ Each option may have an extended description in
+ <tt>desc.<var>option</var></tt>. This should be formatted
+ like the extended description part of a <tt>Description</tt>
+ field entry <em>shifted one character to the left</em>.
+ </p>
+
+ <p>
+ <tt><var>vardir</var>/methods</tt> will exist, and a method
+ group may use a
+ <tt><var>vardir</var>/methods/<var>group</var></tt>
+ directory to store its state.
+ </p>
+
+ <p>
+ The group name and method name must follow the rules for C
+ identifiers.
+ </p>
+ </sect>
+ </chapt>
+
+ <chapt id="conversion"><heading>Conversion procedure from old
+ source packages
+ </heading>
+
+ <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>
+
+ <p>
+ You are strongly advised to download and examine the <prgn>hello</prgn>
+ package, and to read the section in the <prgn>dpkg</prgn> 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>
+
+ <p>
+ <list>
+ <item>
+ <p>
+ 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>-<var>upstream-version</var>.orig/</tt>
+ or
+ <tt><var>package</var>_<var>upstream-version</var>.orig.tar.gz</tt>.
+ </p>
+ </item>
+
+ <item>
+ <p>
+ Rename all files <tt>debian.*</tt> to <tt>debian/*</tt>.
+ There may be some exceptions to this, but this is a good
+ start.</p>
+ </item>
+
+ <item>
+ <p>
+ Edit the <tt>debian/changelog</tt> - 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>
+ </p>
+ </item>
+
+ <item>
+ <p>
+ Edit/create <tt>debian/control</tt>:
+ <list compact="compact">
+ <item>
+ <p>
+ Remove the <tt>Version</tt> 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>,
+ <tt>Priority</tt>, <tt>Maintainer</tt> go above
+ the first blank line, most of the rest
+ below.
+ </p>
+ </item>
+
+ <item>
+ <p>
+ Reorder the fields and add a blank line at an
+ appropriate point, separating the source package
+ fields from the binary package fields.
+ </p>
+ </item>
+
+ <item>
+ <p>Add the <tt>Source</tt> field.</p></item>
+
+ <item>
+ <p>
+ Add the <tt>Standards-Version</tt> field. (Please
+ check out the Debian Policy Manual for details
+ about this field.)</p>
+ </item>
+
+ <item>
+ <p>
+ Change the <tt>Architecture</tt> field for each
+ package to <tt>any</tt>, <tt>all</tt> or whatever.
+ If there isn't an <tt>Architecture</tt> field add
+ one.</p>
+ </item>
+
+ <item>
+ <p>
+ If any other use of sed or things used to happen
+ to make the binary control files use
+ <prgn>dpkg-gencontrol</prgn>'s variable
+ substitution features to achieve the same effect.
+ Use <tt>debian/substvars</tt> if you need to put
+ unusally-generated information (apart from details
+ of <tt>.deb</tt> files) in the <tt>.changes</tt>
+ file too.</p>
+ </item>
+ </list>
+ </p>
+ </item>
+
+ <item>
+ <p>Edit the <tt>debian/rules</tt>:
+ <list compact="compact">
+ <item>
+ <p>
+ Remove the <prgn>source</prgn> and
+ <prgn>diff</prgn> and any <prgn>changes</prgn> and
+ <prgn>dist</prgn> targets. These things now
+ happen in a package-independent way and are not
+ done by <tt>debian/rules</tt>.</p>
+ </item>
+ <item>
+ <p>
+ Split the <prgn>binary</prgn> target into
+ <prgn>binary-arch</prgn> and
+ <prgn>binary-indep</prgn>; in many cases all of
+ <prgn>binary</prgn> should go into
+ <prgn>binary-arch</prgn>. Create the
+ <prgn>binary</prgn> target and the unused of the
+ two other <prgn>binary-*</prgn> targets if there
+ is one - you can copy the ones from the
+ <prgn>hello</prgn> package.</p>
+ </item>
+ <item>
+ <p>
+ Change the <prgn>binary</prgn> target to use
+ <prgn>dpkg-gencontrol</prgn> to make the package
+ control file(s). Move it to after all the files
+ have been installed but just before the last
+ <prgn>chown</prgn> and <prgn>chmod</prgn> in the
+ target.</p>
+ </item>
+ <item>
+ <p>
+ Change occurrences of <tt>debian-tmp</tt> to
+ <tt>debian/tmp</tt>.</p>
+ </item>
+ <item>
+ <p>
+ Change occurrences of
+ <tt>debian.{post,pre}{inst,rm}</tt> to
+ <tt>debian/*</tt>.</p>
+ </item>
+ <item>
+ <p>
+ Remove the version number setting at the top, if
+ there is one.</p>
+ </item>
+ <item>
+ <p>
+ Ensure that the package's Debian-specific and
+ upstream changelogs are installed.</p>
+ </item>
+ </list>
+ </p>
+ </item>
+
+ <item>
+ <p>
+ Change the package to use <prgn>dpkg-shlibdeps</prgn> to
+ determine its shared library dependencies and substitute
+ them in. Shared library dependencies should no longer
+ be hardwired in the source package.</p>
+ </item>
+
+ <item>
+ <p>
+ Check that the <tt>debian/README</tt> is really the
+ copyright file, and if so rename it to
+ <tt>debian/copyright</tt> and edit <tt>debian/rules</tt>
+ to cope with this and to change the installation of the
+ copyright file from
+ <tt>/usr/doc/<var>package</var>/copyright</tt> to
+ <tt>/usr/doc/copyright/<var>package</var></tt>. If it
+ isn't then find <tt>debian/copyright</tt> and decide
+ what to do with the <tt>README</tt>.</p>
+ </item>
+
+ <item>
+ <p>Check for various other anachronisms and problems:
+ <list compact="compact">
+ <item>
+ <p>
+ Remove any <tt>Package_Revision</tt>,
+ <tt>Package-Revision</tt> or <tt>Revision</tt>
+ fields.</p>
+ </item>
+ <item>
+ <p>
+ Rename <tt>Optional</tt> to <tt>Suggests</tt>,
+ <tt>Recommended</tt> to
+ <tt>Recommends</tt>.</p>
+ </item>
+ <item>
+ <p>
+ Change
+ <tt>/usr/doc/examples/<var>package</var></tt> to
+ <tt>/usr/doc/<var>package</var>/examples</tt>.</p>
+ </item>
+ <item>
+ <p>
+ Make sure that manpages are installed
+ compressed.</p>
+ </item>
+ <item>
+ <p>
+ 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.</p>
+ </item>
+ </list>
+ </p>
+ </item>
+
+ <item>
+ <p>Look everything over.</p></item>
+
+ <item>
+ <p>
+ Do a test build using <tt>dpkg-buildpackage -us -uc -sa
+ -r<var>whatever</var></tt>. Check the permissions and
+ locations of files in the resulting package by examining
+ the output of <tt>dpkg-deb --contents</tt>, and check
+ that the source build happened OK. Test install the
+ binary package(s) and test extract the source
+ package(s).</p>
+ </item>
+
+ <item>
+ <p>
+ Sign the release: either rebuild everything with
+ <tt>dpkg-buildpackage -sa</tt>, or PGP-sign the
+ <tt>.dsc</tt>, rebuild the <tt>.changes</tt> using
+ <tt>dpkg-genchanges -sa</tt>, and then PGP-sign the
+ <tt>.changes</tt>.</p>
+ </item>
+
+ </list>
+ </p>
+
+ <p>
+ The use of <tt>-sa</tt> on <prgn>dpkg-buildpackage</prgn> and
+ <prgn>dpkg-genchanges</prgn> is important when doing the first
+ build/uploading of a new-format source package. Unless this
+ happens to be Debian revision <tt>0</tt> or <tt>1</tt> by
+ default the original source tarfile will not be included in
+ the uploaded files listed in the <tt>.changes</tt> file, and
+ so it won't be installed on the FTP site. <tt>-sa</tt>
+ requests that the original source be included
+ regardless.</p>
+ </chapt>
+
+ </book>
+</debiandoc>
-<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 <iwj10@cus.cam.ac.uk>
-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/<</,
-<tt/<=/,
-<tt/=/,
-<tt/>=/ and
-<tt/>>/
-for strictly earlier, earlier or equal, exactly equal, later or equal
-and strictly later, respectively. The forms <tt/</ and <tt/>/
-were used to mean earlier/later or equal, rather than strictly
-earlier/later, so they should not appear in new packages (though
-<prgn/dpkg/ 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>
projects / debian / debian-policy.git / commitdiff