--- /dev/null
+<!doctype debiandoc system>
+
+<!--
+ Debian GNU/Linux Packaging Manual.
+ Copyright (C)1996 Ian Jackson; released under the terms of the GNU
+ General Public License, version 2 or (at your option) any later.
+ Revised: David A. Morris (bweaver@debian.org)
+ Maintainer since 1998, Christian Schwarz <schwarz@debian.org>
+ -->
+
+<book>
+
+<title>Debian Packaging Manual
+<author>Ian Jackson <email/ijackson@gnu.ai.mit.edu/
+<author>Revised: David A. Morris <email/bweaver@debian.org/
+<author>Maintainer: Christian Schwarz <email/schwarz@debian.org/
+<version>version 2.4.1.0, 14 April 1998
+
+<abstract>
+This manual describes the technical aspects of creating Debian binary
+and source packages. It also documents the interface between
+<prgn/dselect/ and its access method scripts. It does not deal with
+the Debian Project policy requirements, and it assumes familiarity
+with <prgn/dpkg/'s functions from the system administrator's
+perspective.
+
+<copyright>Copyright ©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/
+</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>
+<example>
+<var/prerm/ remove
+</example>
+
+<item>
+The package's files are removed (except conffiles).
+
+<item>
+<example>
+<var/postrm/ remove
+</example>
+
+<item>
+All the maintainer scripts except the postrm are removed.
+<p>
+
+If we aren't purging the package we stop here. Note that packages
+which have no postrm and no conffiles are automatically purged when
+removed, as there is no difference except for the <prgn/dpkg/ status.
+
+<item>
+The conffiles and any backup files (<tt/~/-files, <tt/#*#/ files,
+<tt/%/-files, <tt/.dpkg-{old,new,tmp}/, etc.) are removed.
+
+<item>
+<example>
+<var/postrm/ purge
+</example>
+
+<item>
+The package's file list is removed.
+
+</enumlist>
+
+No attempt is made to unwind after errors during removal.
+
+
+<chapt id="descriptions">Descriptions of packages - the
+<tt/Description/ field
+<p>
+
+The <tt/Description/ control file field is used by <prgn/dselect/ when
+the user is selecting which packages to install and by <prgn/dpkg/
+when it displays information about the status of packages and so
+forth. It is included on the FTP site in the <prgn/Packages/ files,
+and may also be used by the Debian WWW pages.
+<p>
+
+The description is intended to describe the program to a user who has
+never met it before so that they know whether they want to install it.
+It should also give information about the significant dependencies and
+conflicts between this package and others, so that the user knows why
+these dependencies and conflicts have been declared.
+<p>
+
+The field's format is as follows:
+<example>
+Description: <var/single line synopsis/
+ <var/extended description over several lines/
+</example>
+<p>
+
+The synopsis is often printed in lists of packages and so forth, and
+should be as informative as possible. Every package should also have
+an extended description.
+<p>
+
+<sect>Types of formatting line in the extended description
+<p>
+
+<list>
+<item>
+Those starting with a single space are part of a paragraph.
+Successive lines of this form will be word-wrapped when displayed.
+The leading space will usually be stripped off.
+
+<item>
+Those starting with two or more spaces. These will be displayed
+verbatim. If the display cannot be panned horizontally the
+displaying program will linewrap them `hard' (ie, without taking
+account of word breaks). If it can they will be allowed to trail
+off to the right. None, one or two initial spaces may be deleted,
+but the number of spaces deleted from each line will be the same
+(so that you can have indenting work correctly, for example).
+
+<item>
+Those containing a single space followed by a single full stop
+character. These are rendered as blank lines. This is the <em/only/
+way to get a blank line - see below.
+
+<item>
+Those containing a space, a full stop and some more characters. These
+are for future expansion. Do not use them.
+</list>
+
+<sect>Notes about writing descriptions
+<p>
+
+<em/Always/ start extended description lines with at least one
+whitespace character. Fields in the control file and in the Packages
+file are separated by field names starting in the first column, just
+as message header fields are in RFC822. Forgetting the whitespace
+will cause <prgn/dpkg-deb/<footnote>Version 0.93.23 or
+later.</footnote> to produce a syntax error when trying to build the
+package. If you force it to build anyway <prgn/dpkg/ will refuse to
+install the resulting mess.
+<p>
+
+<em/Do not/ include any completely <em/empty/ lines. These separate
+different records in the Packages file and different packages in the
+<tt>debian/control</> file, and are forbidden in package control
+files. See the previous paragraph for what happens if you get this
+wrong.
+<p>
+
+The single line synopsis should be kept brief - certainly under 80
+characters. <prgn/dselect/ displays between 25 and 49 characters
+without panning if you're using an 80-column terminal, depending on
+what display options are in effect.
+<p>
+
+Do not include the package name in the synopsis line. The display
+software knows how to display this already, and you do not need to
+state it. Remember that in many situations the user may only see
+the synopsis line - make it as informative as you can.
+<p>
+
+The extended description should describe what the package does and
+how it relates to the rest of the system (in terms of, for
+example, which subsystem it is which part of).
+<p>
+
+The blurb that comes with a program in its announcements and/or
+<prgn/README/ files is rarely suitable for use in a description. It
+is usually aimed at people who are already in the community where the
+package is used. The description field needs to make sense to anyone,
+even people who have no idea about any of the
+things the package deals with.
+<p>
+
+Put important information first, both in the synopis and extended
+description. Sometimes only the first part of the synopsis or of
+the description will be displayed. You can assume that there will
+usually be a way to see the whole extended description.
+<p>
+
+You may include information about dependencies and so forth in the
+extended description, if you wish.
+<p>
+
+Do not use tab characters. Their effect is not predictable.
+<p>
+
+Do not try to linewrap the summary (the part on the same line as the
+field name <tt/Description/) into the extended description. This will
+not work correctly when the full description is displayed, and makes
+no sense where only the summary is available.
+
+<sect>Example description in control file for Smail
+<p>
+
+<example>
+Package: smail
+Version: 3.1.29.1-13
+Maintainer: Ian Jackson <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 / blobdiff