+ </taglist>
+
+ <p>
+ You should list <em>all</em> distributions that the
+ package should be installed into.
+ </p>
+
+ <p>
+ More information is available in the Debian Developer's
+ Reference, section "The Debian archive".
+ </p>
+ </footnote>
+ </p>
+ </sect1>
+
+ <sect1 id="f-Date">
+ <heading><tt>Date</tt></heading>
+
+ <p>
+ This field includes the date the package was built or last edited.
+ </p>
+
+ <p>
+ The value of this field is usually extracted from the
+ <file>debian/changelog</file> file - see
+ <ref id="dpkgchangelog">).
+ </p>
+ </sect1>
+
+ <sect1 id="f-Format">
+ <heading><tt>Format</tt></heading>
+
+ <p>
+ This field specifies a format revision for the file.
+ The most current format described in the Policy Manual
+ is version <strong>1.5</strong>. 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="f-Version">.
+ </p>
+ </sect1>
+
+ <sect1 id="f-Urgency">
+ <heading><tt>Urgency</tt></heading>
+
+ <p>
+ This is a description of how important it is to upgrade to
+ this version from previous ones. It consists of a single
+ keyword usually taking one of the values <tt>low</tt>,
+ <tt>medium</tt> or <tt>high</tt> (not case-sensitive)
+ followed by an optional commentary (separated by a space)
+ which is usually in parentheses. For example:
+
+ <example>
+ Urgency: low (HIGH for users of diversions)
+ </example>
+
+ </p>
+
+ <p>
+ The value of this field is usually extracted from the
+ <file>debian/changelog</file> file - see
+ <ref id="dpkgchangelog">.
+ </p>
+ </sect1>
+
+ <sect1 id="f-Changes">
+ <heading><tt>Changes</tt></heading>
+
+ <p>
+ This field contains the human-readable changes data, describing
+ the differences between the last version and the current one.
+ </p>
+
+ <p>
+ There should be nothing in this field before the first
+ newline; all the subsequent lines must be indented by at
+ least one space; blank lines must be represented by a line
+ consiting only of a space and a full stop.
+ </p>
+
+ <p>
+ The value of this field is usually extracted from the
+ <file>debian/changelog</file> file - see
+ <ref id="dpkgchangelog">).
+ </p>
+
+ <p>
+ Each version's change information should be preceded by a
+ "title" line giving at least the version, distribution(s)
+ and urgency, in a human-readable way.
+ </p>
+
+ <p>
+ If data from several versions is being returned the entry
+ for the most recent version should be returned first, and
+ entries should be separated by the representation of a
+ blank line (the "title" line may also be followed by the
+ representation of blank line).
+ </p>
+ </sect1>
+
+ <sect1 id="f-Binary">
+ <heading><tt>Binary</tt></heading>
+
+ <p>
+ This field is a list of binary packages.
+ </p>
+
+ <p>
+ When it appears in the <file>.dsc</file> file it is the list
+ of binary packages which a source package can produce. It
+ does not necessarily produce all of these binary packages
+ for every architecture. The source control file doesn't
+ contain details of which architectures are appropriate for
+ which of the binary packages.
+ </p>
+
+ <p>
+ When it appears in a <file>.changes</file> file it lists the
+ names of the binary packages actually being uploaded.
+ </p>
+
+ <p>
+ The syntax is a list of binary packages separated by
+ commas<footnote>
+ A space after each comma is conventional.
+ </footnote>. Currently the packages must be separated using
+ only spaces in the <file>.changes</file> file.
+ </p>
+ </sect1>
+
+ <sect1 id="f-Installed-Size">
+ <heading><tt>Installed-Size</tt></heading>
+
+ <p>
+ This field appears in the control files of binary
+ packages, and in the <file>Packages</file> files. It gives
+ the total amount of disk space required to install the
+ named package.
+ </p>
+
+ <p>
+ The disk space is represented in kilobytes as a simple
+ decimal number.
+ </p>
+ </sect1>
+
+ <sect1 id="f-Files">
+ <heading><tt>Files</tt></heading>
+
+ <p>
+ This field contains a list of files with information about
+ each one. The exact information and syntax varies with
+ the context. In all cases the part of the field
+ contents on the same line as the field name is empty. The
+ remainder of the field is one line per file, each line
+ being indented by one space and containing a number of
+ sub-fields separated by spaces.
+ </p>
+
+ <p>
+ In the <file>.dsc</file> file, each line contains the MD5
+ checksum, size and filename of the tar file 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</tt>.
+ </footnote>.
+ The exact forms of the filenames are described
+ in <ref id="pkg-sourcearchives">.
+ </p>
+
+ <p>
+ In the <file>.changes</file> file this contains one line per
+ file being uploaded. Each line contains the MD5 checksum,
+ size, section and priority and the filename.
+ The <qref id="f-Section">section</qref>
+ and <qref id="f-Priority">priority</qref>
+ are the values of the corresponding fields in
+ the main source control file. If no section or priority is
+ specified then <tt>-</tt> should be used, though section
+ and priority values must be specified for new packages to
+ be installed properly.
+ </p>
+
+ <p>
+ The special value <tt>byhand</tt> for the section in a
+ <tt>.changes</tt> file indicates that the file in question
+ is not an ordinary package file and must by installed by
+ hand by the distribution maintainers. If the section is
+ <tt>byhand</tt> the priority should be <tt>-</tt>.
+ </p>
+
+ <p>
+ If a new Debian revision of a package is being shipped and
+ no new original source archive is being distributed the
+ <tt>.dsc</tt> must still contain the <tt>Files</tt> field
+ entry for the original source archive
+ <file><var>package</var>-<var>upstream-version</var>.orig.tar.gz</file>,
+ but the <file>.changes</file> 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
+ <file>.dsc</file> file and diff which are being uploaded.</p>
+ </sect1>
+
+ <sect1 id="f-Closes">
+ <heading><tt>Closes</tt></heading>
+
+ <p>
+ A space-separated list of bug report numbers that the upload
+ governed by the .changes file closes.
+ </p>
+ </sect1>
+
+ </sect>
+
+ <sect>
+ <heading>User-defined fields</heading>
+
+ <p>
+ Additional user-defined fields may be added to the
+ source package control file. Such fields will be
+ ignored, and not copied to (for example) binary or
+ source package control files or upload control files.
+ </p>
+
+ <p>
+ If you wish to add additional unsupported fields to
+ these output files you should use the mechanism
+ described here.
+ </p>
+
+ <p>
+ Fields in the main source control information file with
+ names starting <tt>X</tt>, followed by one or more of
+ the letters <tt>BCS</tt> and a hyphen <tt>-</tt>, will
+ be copied to the output files. Only the part of the
+ field name after the hyphen will be used in the output
+ file. Where the letter <tt>B</tt> is used the field
+ will appear in binary package control files, where the
+ letter <tt>S</tt> is used in source package control
+ files and where <tt>C</tt> is used in upload control
+ (<tt>.changes</tt>) files.
+ </p>
+
+ <p>
+ For example, if the main source information control file
+ contains the field
+ <example>
+ XBS-Comment: I stand between the candle and the star.
+ </example>
+ then the binary and source package control files will contain the
+ field
+ <example>
+ Comment: I stand between the candle and the star.
+ </example>
+ </p>
+
+ </sect>
+
+ </chapt>
+
+
+ <chapt id="maintainerscripts">
+ <heading>Package maintainer scripts and installation procedure</heading>
+
+ <sect>
+ <heading>Introduction to package maintainer scripts</heading>
+
+ <p>
+ It is possible to supply scripts as part of a package which
+ the package management system will run for you when your
+ package is installed, upgraded or removed.
+ </p>
+
+ <p>
+ These scripts are the files <prgn>preinst</prgn>,
+ <prgn>postinst</prgn>, <prgn>prerm</prgn> and <prgn>postrm</prgn> in the
+ control area of the package. They must be proper executable
+ files; if they are scripts (which is recommended), they must
+ start with the usual <tt>#!</tt> convention. They should be
+ readable and executable by anyone, and not world-writable.
+ </p>
+
+ <p>
+ The package management system looks at the exit status from
+ these scripts. It is important that they exit with a
+ non-zero status if there is an error, so that the package
+ management system can stop its processing. For shell
+ scripts this means that you <em>almost always</em> need to
+ use <tt>set -e</tt> (this is usually true when writing shell
+ scripts, in fact). It is also important, of course, that
+ they don't exit with a non-zero status if everything went
+ well.
+ </p>
+
+ <p>
+ When a package is upgraded a combination of the scripts from
+ the old and new packages is called during the upgrade
+ procedure. If your scripts are going to be at all
+ complicated you need to be aware of this, and may need to
+ check the arguments to your scripts.
+ </p>
+
+ <p>
+ Broadly speaking the <prgn>preinst</prgn> is called before
+ (a particular version of) a package is installed, and the
+ <prgn>postinst</prgn> afterwards; the <prgn>prerm</prgn>
+ before (a version of) a package is removed and the
+ <prgn>postrm</prgn> afterwards.
+ </p>
+
+ <p>
+ Programs called from maintainer scripts should not normally
+ have a path prepended to them. Before installation is
+ started, the package management system checks to see if the
+ programs <prgn>ldconfig</prgn>,
+ <prgn>start-stop-daemon</prgn>, <prgn>install-info</prgn>,
+ and <prgn>update-rc.d</prgn> can be found via the
+ <tt>PATH</tt> environment variable. Those programs, and any
+ other program that one would expect to be on the
+ <tt>PATH</tt>, should thus be invoked without an absolute
+ pathname. Maintainer scripts should also not reset the
+ <tt>PATH</tt>, though they might choose to modify it by
+ prepending or appending package-specific directories. These
+ considerations really apply to all shell scripts.</p>
+ </sect>
+
+ <sect id="idempotency">
+ <heading>Maintainer scripts Idempotency</heading>
+
+ <p>
+ It is necessary for the error recovery procedures that the
+ scripts be idempotent. This means that if it is run
+ successfully, and then it is called again, it doesn't bomb
+ out or cause any harm, but just ensures that everything is
+ the way it ought to be. If the first call failed, or
+ aborted half way through for some reason, the second call
+ should merely do the things that were left undone the first
+ time, if any, and exit with a success status if everything
+ is OK.<footnote>
+ This is so that if an error occurs, the user interrupts
+ <prgn>dpkg</prgn> or some other unforeseen circumstance
+ happens you don't leave the user with a badly-broken
+ package when <prgn>dpkg</prgn> attempts to repeat the
+ action.
+ </footnote>
+ </p>
+ </sect>
+
+ <sect id="controllingterminal">
+ <heading>Controlling terminal for maintainer scripts</heading>
+
+ <p>
+ The maintainer scripts are guaranteed to run with a
+ controlling terminal and can interact with the user.
+ If they need to prompt for passwords, do full-screen
+ interaction or something similar you should do these
+ things to and from <file>/dev/tty</file>, since
+ <prgn>dpkg</prgn> will at some point redirect scripts'
+ standard input and output so that it can log the
+ installation process. Likewise, because these scripts
+ may be executed with standard output redirected into a
+ pipe for logging purposes, Perl scripts should set
+ unbuffered output by setting <tt>$|=1</tt> so that the
+ output is printed immediately rather than being
+ buffered.
+ </p>
+
+ <p>
+ Each script should return a zero exit status for
+ success, or a nonzero one for failure.
+ </p>
+ </sect>
+
+ <sect id="mscriptsinstact"><heading>Summary of ways maintainer
+ scripts are called
+ </heading>
+
+ <p>
+ <list compact="compact">
+ <item>
+ <var>new-preinst</var> <tt>install</tt>
+ </item>
+ <item>
+ <var>new-preinst</var> <tt>install</tt> <var>old-version</var>
+ </item>
+ <item>
+ <var>new-preinst</var> <tt>upgrade</tt> <var>old-version</var>
+ </item>
+ <item>
+ <var>old-preinst</var> <tt>abort-upgrade</tt>
+ <var>new-version</var>
+ </item>
+ </list>
+
+ <p>
+ <list compact="compact">
+ <item>
+ <var>postinst</var> <tt>configure</tt>
+ <var>most-recently-configured-version</var>
+ </item>
+ <item>
+ <var>old-postinst</var> <tt>abort-upgrade</tt>
+ <var>new-version</var>
+ </item>
+ <item>
+ <var>conflictor's-postinst</var> <tt>abort-remove</tt>
+ <tt>in-favour</tt> <var>package</var>
+ <var>new-version</var>
+ </item>
+ <item>
+ <var>deconfigured's-postinst</var>
+ <tt>abort-deconfigure</tt> <tt>in-favour</tt>
+ <var>failed-install-package</var> <var>version</var>
+ <tt>removing</tt> <var>conflicting-package</var>
+ <var>version</var>
+ </item>
+ </list>
+
+ <p>
+ <list compact="compact">
+ <item>
+ <var>prerm</var> <tt>remove</tt>
+ </item>
+ <item>
+ <var>old-prerm</var> <tt>upgrade</tt>
+ <var>new-version</var>
+ </item>
+ <item>
+ <var>new-prerm</var> <tt>failed-upgrade</tt>
+ <var>old-version</var>
+ </item>
+ <item>
+ <var>conflictor's-prerm</var> <tt>remove</tt>
+ <tt>in-favour</tt> <var>package</var>
+ <var>new-version</var>
+ </item>
+ <item>
+ <var>deconfigured's-prerm</var> <tt>deconfigure</tt>
+ <tt>in-favour</tt> <var>package-being-installed</var>
+ <var>version</var> <tt>removing</tt>
+ <var>conflicting-package</var>
+ <var>version</var>
+ </item>
+ </list>
+
+ <p>
+ <list compact="compact">
+ <item>
+ <var>postrm</var> <tt>remove</tt>
+ </item>
+ <item>
+ <var>postrm</var> <tt>purge</tt>
+ </item>
+ <item>
+ <var>old-postrm</var> <tt>upgrade</tt>
+ <var>new-version</var>
+ </item>
+ <item>
+ <var>new-postrm</var> <tt>failed-upgrade</tt>
+ <var>old-version</var>
+ </item>
+ <item>
+ <var>new-postrm</var> <tt>abort-install</tt>
+ </item>
+ <item>
+ <var>new-postrm</var> <tt>abort-install</tt>
+ <var>old-version</var>
+ </item>
+ <item>
+ <var>new-postrm</var> <tt>abort-upgrade</tt>
+ <var>old-version</var>
+ </item>
+ <item>
+ <var>disappearer's-postrm</var> <tt>disappear</tt>
+ <var>overwriter</var>
+ <var>overwriter-version</var>
+ </item>
+ </list>
+ </p>
+
+
+ <sect id="unpackphase">
+ <heading>Details of unpack phase of installation or upgrade</heading>
+
+ <p>
+ The procedure on installation/upgrade/overwrite/disappear
+ (i.e., when running <tt>dpkg --unpack</tt>, or the unpack
+ stage of <tt>dpkg --install</tt>) is as follows. In each
+ case, if a major error occurs (unless listed below) the
+ actions are, in general, run backwards - this means that the
+ maintainer scripts are run with different arguments in
+ reverse order. These are the "error unwind" calls listed
+ below.
+
+ <enumlist>
+ <item>
+ <enumlist>
+ <item>
+ If a version of the package is already installed, call
+ <example compact="compact">
+<var>old-prerm</var> upgrade <var>new-version</var>
+ </example>
+ </item>
+ <item>
+ If the script runs but exits with a non-zero
+ exit status, <prgn>dpkg</prgn> will attempt:
+ <example compact="compact">
+<var>new-prerm</var> failed-upgrade <var>old-version</var>
+ </example>
+ Error unwind, for both the above cases:
+ <example compact="compact">
+<var>old-postinst</var> abort-upgrade <var>new-version</var>
+ </example>
+ </item>
+ </enumlist>
+ </item>
+
+ <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</tt> is
+ specified, call, for each such package:
+ <example compact="compact">
+<var>deconfigured's-prerm</var> deconfigure \
+ in-favour <var>package-being-installed</var> <var>version</var> \
+ removing <var>conflicting-package</var> <var>version</var>
+ </example>
+ Error unwind:
+ <example compact="compact">
+<var>deconfigured's-postinst</var> abort-deconfigure \
+ in-favour <var>package-being-installed-but-failed</var> <var>version</var> \
+ removing <var>conflicting-package</var> <var>version</var>
+ </example>
+ The deconfigured packages are marked as
+ requiring configuration, so that if
+ <tt>--install</tt> is used they will be
+ configured again if possible.
+ </item>
+ <item>
+ To prepare for removal of the conflicting package, call:
+ <example compact="compact">
+<var>conflictor's-prerm</var> remove \
+ in-favour <var>package</var> <var>new-version</var>
+ </example>
+ Error unwind:
+ <example compact="compact">
+<var>conflictor's-postinst</var> abort-remove \
+ in-favour <var>package</var> <var>new-version</var>
+ </example>
+ </item>
+ </enumlist>
+ </item>
+
+ <item>
+ <enumlist>
+ <item>
+ If the package is being upgraded, call:
+ <example compact="compact">
+<var>new-preinst</var> upgrade <var>old-version</var>
+ </example>
+ </item>
+ <item>
+ Otherwise, if the package had some configuration
+ files from a previous version installed (i.e., it
+ is in the "configuration files only" state):
+ <example compact="compact">
+<var>new-preinst</var> install <var>old-version</var>
+ </example>
+ </item>
+ <item>
+ Otherwise (i.e., the package was completely purged):
+ <example compact="compact">
+<var>new-preinst</var> install
+ </example>
+ Error unwind actions, respectively:
+ <example compact="compact">
+<var>new-postrm</var> abort-upgrade <var>old-version</var>
+<var>new-postrm</var> abort-install <var>old-version</var>
+<var>new-postrm</var> abort-install
+ </example>
+ </item>
+ </enumlist>
+ </item>
+
+ <item>
+ <p>
+ The new package's files are unpacked, overwriting any
+ that may be on the system already, for example any
+ from the old version of the same package or from
+ another package. Backups of the old files are kept
+ temporarily, and if anything goes wrong the package
+ management system will attempt to put them back as
+ part of the error unwind.
+ </p>
+
+ <p>
+ It is an error for a package to contain files which
+ are on the system in another package, unless
+ <tt>Replaces</tt> is used (see <ref id="replaces">).
+ <!--
+ The following paragraph is not currently the case:
+ Currently the <tt>- - force-overwrite</tt> flag is
+ enabled, downgrading it to a warning, but this may not
+ always be the case.
+ -->
+ </p>
+
+ <p>
+ It is a more serious error for a package to contain a
+ plain file or other kind of non-directory where another
+ package has a directory (again, unless
+ <tt>Replaces</tt> is used). This error can be
+ overridden if desired using
+ <tt>--force-overwrite-dir</tt>, but this is not
+ advisable.
+ </p>
+
+ <p>
+ Packages which overwrite each other's files produce
+ behavior which, though deterministic, is hard for the
+ system administrator to understand. It can easily
+ lead to "missing" programs if, for example, a package
+ is installed which overwrites a file from another
+ package, and is then removed again.<footnote>
+ Part of the problem is due to what is arguably a
+ bug in <prgn>dpkg</prgn>.
+ </footnote>
+ </p>
+
+ <p>
+ A directory will never be replaced by a symbolic link
+ to a directory or vice versa; instead, the existing
+ state (symlink or not) will be left alone and
+ <prgn>dpkg</prgn> will follow the symlink if there is
+ one.
+ </p>
+ </item>
+
+ <item>
+ <p>
+ <enumlist>
+ <item>
+ If the package is being upgraded, call
+ <example compact="compact">
+<var>old-postrm</var> upgrade <var>new-version</var>
+ </example>
+ </item>
+ <item>
+ If this fails, <prgn>dpkg</prgn> will attempt:
+ <example compact="compact">
+<var>new-postrm</var> failed-upgrade <var>old-version</var>
+ </example>
+ Error unwind, for both cases:
+ <example compact="compact">
+<var>old-preinst</var> abort-upgrade <var>new-version</var>
+ </example>
+ </item>
+ </enumlist>
+ </p>
+
+ <p>
+ This is the point of no return - if
+ <prgn>dpkg</prgn> gets this far, it won't back off
+ past this point if an error occurs. This will
+ leave the package in a fairly bad state, which
+ will require a successful re-installation to clear
+ up, but it's when <prgn>dpkg</prgn> starts doing
+ things that are irreversible.
+ </p>
+ </item>
+
+ <item>
+ Any files which were in the old version of the package
+ but not in the new are removed.
+ </item>
+
+ <item>
+ The new file list replaces the old.
+ </item>
+
+ <item>
+ The new maintainer scripts replace the old.
+ </item>
+
+ <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</prgn> calls:
+ <example compact="compact">
+<var>disappearer's-postrm</var> disappear \
+ <var>overwriter</var> <var>overwriter-version</var>
+ </example>
+ </item>
+ <item>
+ The package's maintainer scripts are removed.
+ </item>
+ <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</prgn>). Note that
+ disappearing packages do not have their prerm
+ called, because <prgn>dpkg</prgn> doesn't know
+ in advance that the package is going to
+ vanish.
+ </item>
+ </enumlist>
+ </item>
+
+ <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 lobotomize the file list
+ of the "conflicting" package if there is one.)
+ </item>
+
+ <item>
+ The backup files made during installation, above, are
+ deleted.
+ </item>
+
+ <item>
+ <p>
+ The new package's status is now sane, and recorded as
+ "unpacked".
+ </p>
+
+ <p>
+ Here is another point of no return - if the
+ conflicting package's removal fails we do not unwind
+ the rest of the installation; the conflicting package
+ is left in a half-removed limbo.
+ </p>
+ </item>
+
+ <item>
+ 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).
+ </item>
+ </enumlist>
+ </p>
+ </sect>
+
+ <sect id="configdetails"><heading>Details of configuration</heading>
+
+ <p>
+ When we configure a package (this happens with <tt>dpkg
+ --install</tt> and <tt>dpkg --configure</tt>), we first
+ update any <tt>conffile</tt>s and then call:
+ <example compact="compact">
+<var>postinst</var> configure <var>most-recently-configured-version</var>
+ </example>
+ </p>
+
+ <p>
+ No attempt is made to unwind after errors during
+ configuration.
+ </p>
+
+ <p>
+ If there is no most recently configured version
+ <prgn>dpkg</prgn> will pass a null argument.
+ <footnote>
+ <p>
+ Historical note: Truly ancient (pre-1997) versions of
+ <prgn>dpkg</prgn> passed <tt><unknown></tt>
+ (including the angle brackets) in this case. Even older
+ ones did not pass a second argument at all, under any
+ circumstance. Note that upgrades using such an old dpkg
+ version are unlikely to work for other reasons, even if
+ this old argument behavior is handled by your postinst script.
+ </p>
+ </footnote>
+ </p>
+ </sect>
+
+ <sect id="removedetails"><heading>Details of removal and/or
+ configuration purging</heading>
+
+ <p>
+ <enumlist>
+ <item>
+ <example compact="compact">
+<var>prerm</var> remove
+ </example>
+ </item>
+ <item>
+ The package's files are removed (except <tt>conffile</tt>s).
+ </item>
+ <item>
+ <example compact="compact">
+<var>postrm</var> remove
+ </example>
+ </item>
+ <item>
+ <p>
+ All the maintainer scripts except the <prgn>postrm</prgn>
+ are removed.
+ </p>
+
+ <p>
+ If we aren't purging the package we stop here. Note
+ that packages which have no <prgn>postrm</prgn> and no
+ <tt>conffile</tt>s are automatically purged when
+ removed, as there is no difference except for the
+ <prgn>dpkg</prgn> status.
+ </p>
+ </item>
+ <item>
+ The <tt>conffile</tt>s and any backup files
+ (<tt>~</tt>-files, <tt>#*#</tt> files,
+ <tt>%</tt>-files, <tt>.dpkg-{old,new,tmp}</tt>, etc.)
+ are removed.
+ </item>
+ <item>
+ <example compact="compact">
+<var>postrm</var> purge
+ </example>
+ </item>
+ <item>
+ The package's file list is removed.
+ </item>
+ </enumlist>
+
+ If there are problems during this process, we call
+ <example compact="compact">postinst
+ abort-remove</example>. No other attempt is made to unwind
+ after errors during removal.
+ </p>
+ </sect>
+ </chapt>
+
+
+ <chapt id="relationships">
+ <heading>Declaring relationships between packages</heading>
+
+ <sect id="depsyntax">
+ <heading>Syntax of relationship fields</heading>
+
+ <p>
+ These fields all have a uniform syntax. They are a list of
+ package names separated by commas.
+ </p>
+
+ <p>
+ In the <tt>Depends</tt>, <tt>Recommends</tt>,
+ <tt>Suggests</tt>, <tt>Pre-Depends</tt>,
+ <tt>Build-Depends</tt> and <tt>Build-Depends-Indep</tt>
+ control file fields of the package, which declare
+ dependencies on other packages, the package names listed may
+ also include lists of alternative package names, separated
+ by vertical bar (pipe) symbols <tt>|</tt>. In such a case,
+ if any one of the alternative packages is installed, that
+ part of the dependency is considered to be satisfied.
+ </p>
+
+ <p>
+ All of the fields except for <tt>Provides</tt> may restrict
+ their applicability to particular versions of each named
+ package. This is done in parentheses after each individual
+ package name; the parentheses should contain a relation from
+ the list below followed by a version number, in the format
+ described in <ref id="f-Version">.
+ </p>
+
+ <p>
+ The relations allowed are <tt><<</tt>, <tt><=</tt>,
+ <tt>=</tt>, <tt>>=</tt> and <tt>>></tt> for
+ strictly earlier, earlier or equal, exactly equal, later or
+ equal and strictly later, respectively. The deprecated
+ forms <tt><</tt> and <tt>></tt> were used to mean
+ earlier/later or equal, rather than strictly earlier/later,
+ so they should not appear in new packages (though
+ <prgn>dpkg</prgn> still supports them).
+ </p>
+
+ <p>
+ Whitespace may appear at any point in the version
+ specification subject to the rules in <ref
+ id="controlsyntax">, and must appear where it's necessary to
+ disambiguate; it is not otherwise significant. For
+ consistency and in case of future changes to
+ <prgn>dpkg</prgn> it is recommended that a single space be
+ used after a version relationship and before a version
+ number; it is also conventional to put a single space after
+ each comma, on either side of each vertical bar, and before
+ each open parenthesis.
+ </p>
+
+ <p>
+ For example, a list of dependencies might appear as:
+ <example compact="compact">
+Package: mutt
+Version: 1.3.17-1
+Depends: libc6 (>= 2.2.1), exim | mail-transport-agent
+ </example>
+ </p>
+
+ <p>
+ All fields that specify build-time relationships
+ (<tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
+ <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>)
+ may be restricted to a certain set of architectures. This
+ is indicated in brackets after each individual package name and
+ the optional version specification. The brackets enclose a
+ list of Debian architecture names separated by whitespace.
+ Exclamation marks may be prepended to each of the names.
+ (It is not permitted for some names to be prepended with
+ exclamation marks and others not.) If the current Debian
+ host architecture is not in this list and there are no
+ exclamation marks in the list, or it is in the list with a
+ prepended exclamation mark, the package name and the
+ associated version specification are ignored completely for
+ the purposes of defining the relationships.
+ </p>
+
+ <p>
+ For example:
+ <example compact="compact">
+Source: glibc
+Build-Depends-Indep: texinfo
+Build-Depends: kernel-headers-2.2.10 [!hurd-i386],
+ hurd-dev [hurd-i386], gnumach-dev [hurd-i386]
+ </example>
+ </p>
+
+ <p>
+ Note that the binary package relationship fields such as
+ <tt>Depends</tt> appear in one of the binary package
+ sections of the control file, whereas the build-time
+ relationships such as <tt>Build-Depends</tt> appear in the
+ source package section of the control file (which is the
+ first section).
+ </p>
+ </sect>
+
+ <sect id="binarydeps">
+ <heading>Binary Dependencies - <tt>Depends</tt>,
+ <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
+ <tt>Pre-Depends</tt>
+ </heading>
+
+ <p>
+ Packages can declare in their control file that they have
+ certain relationships to other packages - for example, that
+ they may not be installed at the same time as certain other
+ packages, and/or that they depend on the presence of others.
+ </p>
+
+ <p>
+ This is done using the <tt>Depends</tt>, <tt>Pre-Depends</tt>,
+ <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt> and
+ <tt>Conflicts</tt> control file fields.
+ </p>
+
+ <p>
+ These six fields are used to declare a dependency
+ relationship by one package on another. Except for
+ <tt>Enhances</tt>, they appear in the depending (binary)
+ package's control file. (<tt>Enhances</tt> appears in the
+ recommending package's control file.)
+ </p>
+
+ <p>
+ A <tt>Depends</tt> field takes effect <em>only</em> when a
+ package is to be configured. It does 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. If it is necessary, a
+ <tt>Pre-Depends</tt> field can be used, which has a partial
+ effect even when a package is being unpacked, as explained
+ in detail below. (The other three dependency fields,
+ <tt>Recommends</tt>, <tt>Suggests</tt> and
+ <tt>Enhances</tt>, are only used by the various front-ends
+ to <prgn>dpkg</prgn> such as <prgn>dselect</prgn>.)
+ </p>
+
+ <p>
+ For this reason packages in an installation run are usually
+ all unpacked first and all configured later; this gives
+ later versions of packages with dependencies on later
+ versions of other packages the opportunity to have their
+ dependencies satisfied.
+ </p>
+
+ <p>
+ The <tt>Depends</tt> field thus allows package maintainers
+ to impose an order in which packages should be configured.
+ </p>
+
+ <p>
+ The meaning of the five dependency fields is as follows:
+ <taglist>
+ <tag><tt>Depends</tt></tag>
+ <item>
+ <p>
+ This declares an absolute dependency. A package will
+ not be configured unless all of the packages listed in
+ its <tt>Depends</tt> field have been correctly
+ configured.
+ </p>
+
+ <p>
+ The <tt>Depends</tt> field should be used if the
+ depended-on package is required for the depending
+ package to provide a significant amount of
+ functionality.
+ </p>
+
+ <p>
+ The <tt>Depends</tt> field should also be used if the
+ <prgn>postinst</prgn>, <prgn>prerm</prgn> or
+ <prgn>postrm</prgn> scripts require the package to be
+ present in order to run. Note, however, that the
+ <prgn>postrm</prgn> cannot rely on any non-essential
+ packages to be present during the <tt>purge</tt>
+ phase.
+ </item>
+
+ <tag><tt>Recommends</tt></tag>
+ <item>
+ <p>
+ This declares a strong, but not absolute, dependency.
+ </p>
+
+ <p>
+ The <tt>Recommends</tt> field should list packages
+ that would be found together with this one in all but
+ unusual installations.
+ </p>
+ </item>
+
+ <tag><tt>Suggests</tt></tag>
+ <item>
+ This is used to declare that one package may be more
+ useful with one or more others. Using this field
+ tells the packaging system and the user that the
+ listed packages are related to this one and can
+ perhaps enhance its usefulness, but that installing
+ this one without them is perfectly reasonable.
+ </item>
+
+ <tag><tt>Enhances</tt></tag>
+ <item>
+ This field is similar to Suggests but works in the
+ opposite direction. It is used to declare that a
+ package can enhance the functionality of another
+ package.
+ </item>
+
+ <tag><tt>Pre-Depends</tt></tag>
+ <item>
+ <p>
+ This field is like <tt>Depends</tt>, except that it
+ also forces <prgn>dpkg</prgn> to complete installation
+ of the packages named before even starting the
+ installation of the package which declares the
+ pre-dependency, as follows:
+ </p>
+
+ <p>
+ When a package declaring a pre-dependency is about to
+ be <em>unpacked</em> the pre-dependency can be
+ satisfied if the depended-on package is either fully
+ configured, <em>or even if</em> the depended-on
+ package(s) are only unpacked or half-configured,
+ provided that they have been configured correctly at
+ some point in the past (and not removed or partially
+ removed since). In this case, both the
+ previously-configured and currently unpacked or
+ half-configured versions must satisfy any version
+ clause in the <tt>Pre-Depends</tt> field.
+ </p>
+
+ <p>
+ When the package declaring a pre-dependency is about
+ to be <em>configured</em>, the pre-dependency will be
+ treated as a normal <tt>Depends</tt>, that is, it will
+ be considered satisfied only if the depended-on
+ package has been correctly configured.
+ </p>
+
+ <p>
+ <tt>Pre-Depends</tt> should be used sparingly,
+ preferably only by packages whose premature upgrade or
+ installation would hamper the ability of the system to
+ continue with any upgrade that might be in progress.
+ </p>
+
+ <p>
+ <tt>Pre-Depends</tt> are also required if the
+ <prgn>preinst</prgn> script depends on the named
+ package. It is best to avoid this situation if
+ possible.
+ </p>
+ </item>
+ </taglist>
+ </p>
+
+ <p>
+ When selecting which level of dependency to use you should
+ consider how important the depended-on package is to the
+ functionality of the one declaring the dependency. Some
+ packages are composed of components of varying degrees of
+ importance. Such a package should list using
+ <tt>Depends</tt> the package(s) which are required by the
+ more important components. The other components'
+ requirements may be mentioned as Suggestions or
+ Recommendations, as appropriate to the components' relative
+ importance.
+ </p>
+ </sect>
+
+ <sect id="conflicts">
+ <heading>Conflicting binary packages - <tt>Conflicts</tt></heading>
+
+ <p>
+ When one binary package declares a conflict with another
+ using a <tt>Conflicts</tt> field, <prgn>dpkg</prgn> will
+ refuse to allow them to be installed on the system at the
+ same time.
+ </p>
+
+ <p>
+ If one package is to be installed, the other must be removed
+ first - if the package being installed is marked as
+ replacing (see <ref id="replaces">) the one on the system,
+ or the one on the system is marked as deselected, or both
+ packages are marked <tt>Essential</tt>, then
+ <prgn>dpkg</prgn> will automatically remove the package
+ which is causing the conflict, otherwise it will halt the
+ installation of the new package with an error. This
+ mechanism is specifically designed to produce an error when
+ the installed package is <tt>Essential</tt>, but the new
+ package is not.
+ </p>
+
+ <p>
+ A package will not cause a conflict merely because its
+ configuration files are still installed; it must be at least
+ half-installed.
+ </p>
+
+ <p>
+ A special exception is made for packages which declare a
+ conflict with their own package name, or with a virtual
+ package which they provide (see below): this does not
+ prevent their installation, and allows a package to conflict
+ with others providing a replacement for it. You use this
+ feature when you want the package in question to be the only
+ package providing some feature.
+ </p>
+
+ <p>
+ A <tt>Conflicts</tt> entry should almost never have an
+ "earlier than" version clause. This would prevent
+ <prgn>dpkg</prgn> from upgrading or installing the package
+ which declared such a conflict until the upgrade or removal
+ of the conflicted-with package had been completed.
+ </p>
+ </sect>
+
+ <sect id="virtual"><heading>Virtual packages - <tt>Provides</tt>
+ </heading>
+
+ <p>
+ As well as the names of actual ("concrete") packages, the
+ package relationship fields <tt>Depends</tt>,
+ <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
+ <tt>Pre-Depends</tt>, <tt>Conflicts</tt>,
+ <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
+ <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>
+ may mention "virtual packages".
+ </p>
+
+ <p>
+ A <em>virtual package</em> is one which appears in the
+ <tt>Provides</tt> control file field of another package.
+ The effect is as if the package(s) which provide a
+ particular virtual package name had been listed by name
+ everywhere the virtual package name appears. (See also <ref
+ id="virtual_pkg">)
+ </p>
+
+ <p>
+ If there are both concrete and virtual packages of the same
+ name, then the dependency may be satisfied (or the conflict
+ caused) by either the concrete package with the name in
+ question or any other concrete package which provides the
+ virtual package with the name in question. This is so that,
+ for example, supposing we have
+ <example compact="compact">
+Package: foo
+Depends: bar
+ </example>
+ and someone else releases an enhanced version of the
+ <tt>bar</tt> package (for example, a non-US variant), they
+ can say:
+ <example compact="compact">
+Package: bar-plus
+Provides: bar
+ </example>
+ and the <tt>bar-plus</tt> package will now also satisfy the
+ dependency for the <tt>foo</tt> package.
+ </p>
+
+ <p>
+ If a dependency or a conflict has a version number attached
+ then only real packages will be considered to see whether
+ the relationship is satisfied (or the prohibition violated,
+ for a conflict) - it is assumed that a real package which
+ provides the virtual package is not of the "right" version.
+ So, a <tt>Provides</tt> field may not contain version
+ numbers, and the version number of the concrete package
+ which provides a particular virtual package will not be
+ looked at when considering a dependency on or conflict with
+ the virtual package name.
+ </p>
+
+ <p>
+ It is likely that the ability will be added in a future
+ release of <prgn>dpkg</prgn> to specify a version number for
+ each virtual package it provides. This feature is not yet
+ present, however, and is expected to be used only
+ infrequently.
+ </p>
+
+ <p>
+ If you want to specify which of a set of real packages
+ should be the default to satisfy a particular dependency on
+ a virtual package, you should list the real package as an
+ alternative before the virtual one.
+ </p>
+ </sect>
+
+
+ <sect id="replaces"><heading>Overwriting files and replacing
+ packages - <tt>Replaces</tt></heading>
+
+ <p>
+ Packages can declare in their control file that they should
+ overwrite files in certain other packages, or completely
+ replace other packages. The <tt>Replaces</tt> control file
+ field has these two distinct purposes.
+ </p>
+
+ <sect1><heading>Overwriting files in other packages</heading>
+
+ <p>
+ Firstly, as mentioned before, it is usually an error for a
+ package to contain files which are on the system in
+ another package.
+ </p>
+
+ <p>
+ However, if the overwriting package declares that it
+ <tt>Replaces</tt> the one containing the file being
+ overwritten, then <prgn>dpkg</prgn> will replace the file
+ from the old package with that from the new. The file
+ will no longer be listed as "owned" by the old package.
+ </p>
+
+ <p>
+ If a package is completely replaced in this way, so that
+ <prgn>dpkg</prgn> does not know of any files it still
+ contains, it is considered to have "disappeared". It will
+ be marked as not wanted on the system (selected for
+ removal) and not installed. Any <tt>conffile</tt>s
+ details noted for the package will be ignored, as they
+ will have been taken over by the overwriting package. The
+ package's <prgn>postrm</prgn> script will be run with a
+ special argument to allow the package to do any final
+ cleanup required. See <ref id="mscriptsinstact">.
+ <footnote>
+ <p>
+ Replaces is a one way relationship -- you have to
+ install the replacing package after the replaced
+ package.
+ </p>
+ </footnote>
+ </p>
+
+ <p>
+ For this usage of <tt>Replaces</tt>, virtual packages (see
+ <ref id="virtual">) are not considered when looking at a
+ <tt>Replaces</tt> field - the packages declared as being
+ replaced must be mentioned by their real names.
+ </p>
+
+ <p>
+ Furthermore, this usage of <tt>Replaces</tt> only takes
+ effect when both packages are at least partially on the
+ system at once, so that it can only happen if they do not
+ conflict or if the conflict has been overridden.
+ </p>
+
+ </sect1>
+
+ <sect1><heading>Replacing whole packages, forcing their
+ removal</heading>
+
+ <p>
+ Secondly, <tt>Replaces</tt> allows the packaging system to
+ resolve which package should be removed when there is a
+ conflict - see <ref id="conflicts">. This usage only
+ takes effect when the two packages <em>do</em> conflict,
+ so that the two usages of this field do not interfere with
+ each other.
+ </p>
+
+ <p>
+ In this situation, the package declared as being replaced
+ can be a virtual package, so for example, all mail
+ transport agents (MTAs) would have the following fields in
+ their control files:
+ <example compact="compact">
+Provides: mail-transport-agent
+Conflicts: mail-transport-agent
+Replaces: mail-transport-agent
+ </example>
+ ensuring that only one MTA can be installed at any one
+ time.
+ </sect1>
+ </sect>
+
+ <sect id="sourcebinarydeps">
+ <heading>Relationships between source and binary packages -
+ <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
+ <tt>Build-Conflicts</tt>, <tt>Build-Conflicts-Indep</tt>
+ </heading>
+
+ <p>
+ Source packages that require certain binary packages to be
+ installed or absent at the time of building the package
+ can declare relationships to those binary packages.
+ </p>
+
+ <p>
+ This is done using the <tt>Build-Depends</tt>,
+ <tt>Build-Depends-Indep</tt>, <tt>Build-Conflicts</tt> and
+ <tt>Build-Conflicts-Indep</tt> control file fields.
+ </p>
+
+ <p>
+ Build-dependencies on "build-essential" binary packages can be
+ omitted. Please see <ref id="pkg-relations"> for more information.
+ </p>
+
+ <p>
+ The dependencies and conflicts they define must be satisfied
+ (as defined earlier for binary packages) in order to invoke
+ the targets in <tt>debian/rules</tt>, as follows:<footnote>
+ <p>
+ If you make "build-arch" or "binary-arch", you need
+ Build-Depends. If you make "build-indep" or
+ "binary-indep", you need Build-Depends and
+ Build-Depends-Indep. If you make "build" or "binary",
+ you need both.
+ </p>
+ <p>
+ There is no Build-Depends-Arch; the autobuilders will
+ only need the Build-Depends if they know how to build
+ only build-arch and binary-arch. Anyone building the
+ build-indep/binary-indep targets is basically assumed to
+ be building the whole package and so installs all build
+ dependencies.
+ </p>
+ <p>
+ The purpose of the original split, I recall, was so that
+ the autobuilders wouldn't need to install extra packages
+ needed only for the binary-indep targets. But without a
+ build-arch/build-indep split, this didn't work, since
+ most of the work is done in the build target, not in the
+ binary target.
+ </p>
+ </footnote>
+
+ <taglist>
+ <tag><tt>Build-Depends</tt>, <tt>Build-Conflicts</tt></tag>
+ <item>
+ The <tt>Build-Depends</tt> and
+ <tt>Build-Conflicts</tt> fields must be satisfied when
+ any of the following targets is invoked:
+ <tt>build</tt>, <tt>clean</tt>, <tt>binary</tt>,
+ <tt>binary-arch</tt>, <tt>build-arch</tt>,
+ <tt>build-indep</tt> and <tt>binary-indep</tt>.
+ </item>
+ <tag><tt>Build-Depends-Indep</tt>,
+ <tt>Build-Conflicts-Indep</tt></tag>
+ <item>
+ The <tt>Build-Depends-Indep</tt> and
+ <tt>Build-Conflicts-Indep</tt> fields must be
+ satisfied when any of the following targets is
+ invoked: <tt>build</tt>, <tt>build-indep</tt>,
+ <tt>binary</tt> and <tt>binary-indep</tt>.
+ </item>
+ </taglist>
+ </p>
+
+ </sect>
+
+ </chapt>
+
+
+ <chapt id="sharedlibs"><heading>Shared libraries</heading>
+
+ <p>
+ Packages containing shared libraries must be constructed with
+ a little care to make sure that the shared library is always
+ available. This is especially important for packages whose
+ shared libraries are vitally important, such as the C library
+ (currently <tt>libc6</tt>).
+ </p>
+
+ <p>
+ Packages involving shared libraries should be split up into
+ several binary packages. This section mostly deals with how
+ this separation is to be accomplished; rules for files within
+ the shared library packages are in <ref id="libraries"> instead.
+ </p>
+
+ <sect id="sharedlibs-runtime">
+ <heading>Run-time shared libraries</heading>
+
+ <p>
+ The run-time shared library needs to be placed in a package called
+ <package><var>libraryname</var><var>soversion</var></package>, where
+ <file><var>soversion</var></file> is the version number in the
+ soname of the shared library<footnote>
+ The soname is the shared object name: it's the thing
+ that has to match exactly between building an executable
+ and running it for the dynamic linker to be able run the
+ program. For example, if the soname of the library is
+ <file>libfoo.so.6</file>, the library package would be
+ called <file>libfoo6</file>.
+ </footnote>.
+ Alternatively, if it would be confusing to directly append
+ <var>soversion</var> to <var>libraryname</var> (e.g. because
+ <var>libraryname</var> itself ends in a number), you may use
+ <package><var>libraryname</var>-<var>soversion</var></package> and
+ <package><var>libraryname</var>-<var>soversion</var>-dev</package>
+ instead.
+ </p>
+
+ <p>
+ If you have several shared libraries built from the same
+ source tree you may lump them all together into a single
+ shared library package, provided that you change all of
+ their sonames at once (so that you don't get filename
+ clashes if you try to install different versions of the
+ combined shared libraries package).
+ </p>
+
+ <p>
+ The package should install the shared libraries under
+ their normal names. For example, the <package>libgdbm3</package>
+ package should install <file>libgdbm.so.3.0.0</file> as
+ <file>/usr/lib/libgdbm.so.3.0.0</file>. The files should not be
+ renamed or re-linked by any <prgn>prerm</prgn> or
+ <prgn>postrm</prgn> scripts; <prgn>dpkg</prgn> will take care
+ of renaming things safely without affecting running programs,
+ and attempts to interfere with this are likely to lead to
+ problems.
+ </p>
+
+ <p>
+ Shared libraries should not be installed executable, since
+ the dynamic linker does not require this and trying to
+ execute a shared library usually results in a core dump.
+ </p>
+
+ <p>
+ The run-time library package should include the symbolic link that
+ <prgn>ldconfig</prgn> would create for the shared libraries.
+ For example, the <package>libgdbm3</package> package should include
+ a symbolic link from <file>/usr/lib/libgdbm.so.3</file> to
+ <file>libgdbm.so.3.0.0</file>. This is needed so that the dynamic
+ linker (for example <prgn>ld.so</prgn> or
+ <prgn>ld-linux.so.*</prgn>) can find the library between the
+ time that <prgn>dpkg</prgn> installs it and the time that
+ <prgn>ldconfig</prgn> is run in the <prgn>postinst</prgn>
+ script.<footnote>
+ The package management system requires the library to be
+ placed before the symbolic link pointing to it in the
+ <file>.deb</file> file. This is so that when
+ <prgn>dpkg</prgn> comes to install the symlink
+ (overwriting the previous symlink pointing at an older
+ version of the library), the new shared library is already
+ in place. In the past, this was achieved by creating the
+ library in the temporary packaging directory before
+ creating the symlink. Unfortunately, this was not always
+ effective, since the building of the tar file in the
+ <file>.deb</file> depended on the behavior of the underlying
+ file system. Some file systems (such as reiserfs) reorder
+ the files so that the order of creation is forgotten.
+ Since version 1.7.0, <prgn>dpkg</prgn>
+ reorders the files itself as necessary when building a
+ package. Thus it is no longer important to concern
+ oneself with the order of file creation.
+ </footnote>
+ </p>
+
+ <sect1 id="ldconfig">
+ <heading><tt>ldconfig</tt></heading>
+
+ <p>
+ Any package installing shared libraries in one of the default
+ library directories of the dynamic linker (which are currently
+ <file>/usr/lib</file> and <file>/lib</file>) or a directory that is
+ listed in <file>/etc/ld.so.conf</file><footnote>
+ These are currently
+ <list compact="compact">
+ <item>/usr/X11R6/lib/Xaw3d</item>
+ <item>/usr/local/lib</item>
+ <item>/usr/lib/libc5-compat</item>
+ <item>/lib/libc5-compat</item>
+ <item>/usr/X11R6/lib</item>
+ </list>
+ </footnote>
+ must use <prgn>ldconfig</prgn> to update the shared library
+ system.
+ </p>
+
+ <p>
+ The package must call <prgn>ldconfig</prgn> in the
+ <prgn>postinst</prgn> script if the first argument is
+ <tt>configure</tt>; the <prgn>postinst</prgn> script may
+ optionally invoke <prgn>ldconfig</prgn> at other times. The
+ package should call <prgn>ldconfig</prgn> in the
+ <prgn>postrm</prgn> script if the first argument is
+ <tt>remove</tt>. The maintainer scripts must not invoke
+ <prgn>ldconfig</prgn> under any circumstances other than those
+ described in this paragraph.<footnote>
+ <p>
+ During install or upgrade, the preinst is called before
+ the new files are installed, so calling "ldconfig" is
+ pointless. The preinst of an existing package can also be
+ called if an upgrade fails. However, this happens during
+ the critical time when a shared libs may exist on-disk
+ under a temporary name. Thus, it is dangerous and
+ forbidden by current policy to call "ldconfig" at this
+ time.
+ </p>
+
+ <p>
+ When a package is installed or upgraded, "postinst
+ configure" runs after the new files are safely on-disk.
+ Since it is perfectly safe to invoke ldconfig
+ unconditionally in a postinst, it is OK for a package to
+ simply put ldconfig in its postinst without checking the
+ argument. The postinst can also be called to recover from
+ a failed upgrade. This happens before any new files are
+ unpacked, so there is no reason to call "ldconfig" at this
+ point.
+ </p>
+
+ <p>
+ For a package that is being removed, prerm is
+ called with all the files intact, so calling ldconfig is
+ useless. The other calls to "prerm" happen in the case of
+ upgrade at a time when all the files of the old package
+ are on-disk, so again calling "ldconfig" is pointless.
+ </p>
+
+ <p>
+ postrm, on the other hand, is called with the "remove"
+ argument just after the files are removed, so this is the
+ proper time to call "ldconfig" to notify the system of the
+ fact shared libraries from the package are removed.
+ The postrm can be called at several other times. At the
+ time of "postrm purge", "postrm abort-install", or "postrm
+ abort-upgrade", calling "ldconfig" is useless because the
+ shared lib files are not on-disk. However, when "postrm"
+ is invoked with arguments "upgrade", "failed-upgrade", or
+ "disappear", a shared lib may exist on-disk under a
+ temporary filename.
+ </p>
+ </footnote>
+ </p>
+ </sect1>
+
+ </sect>
+
+ <sect id="sharedlibs-runtime-progs">
+ <heading>Run-time support programs</heading>
+
+ <p>
+ If your package has some run-time support programs which use
+ the shared library you must not put them in the shared
+ library package. If you do that then you won't be able to
+ install several versions of the shared library without
+ getting filename clashes.
+ </p>
+
+ <p>
+ Instead, either create another package for the runtime binaries
+ (this package might typically be named
+ <package><var>libraryname</var>-runtime</package>; note the absence
+ of the <var>soversion</var> in the package name), or if the
+ development package is small, include them in there.
+ </p>
+ </sect>
+
+ <sect id="sharedlibs-static">
+ <heading>Static libraries</heading>
+
+ <p>
+ The static library (<file><var>libraryname.a</var></file>)
+ is usually provided in addition to the shared version.
+ It is placed into the development package (see below).
+ </p>
+
+ <p>
+ In some cases, it is acceptable for a library to be
+ available in static form only; these cases include:
+ <list>
+ <item>libraries for languages whose shared library support
+ is immature or unstable</item>
+ <item>libraries whose interfaces are in flux or under
+ development (commonly the case when the library's
+ major version number is zero, or where the ABI breaks
+ across patchlevels)</item>
+ <item>libraries which are explicitly intended to be
+ available only in static form by their upstream
+ author(s)</item>
+ </list>
+ </p>
+
+ <sect id="sharedlibs-dev">
+ <heading>Development files</heading>
+
+ <p>
+ The development files associated to a shared library need to be
+ placed in a package called
+ <package><var>libraryname</var><var>soversion</var>-dev</package>,
+ or if you prefer only to support one development version at a
+ time, <package><var>libraryname</var>-dev</package>.
+ </p>
+
+ <p>
+ In case several development versions of a library exist, you may
+ need to use <prgn>dpkg</prgn>'s Conflicts mechanism (see
+ <ref id="conflicts">) to ensure that the user only installs one
+ development version at a time (as different development versions are
+ likely to have the same header files in them, which would cause a
+ filename clash if both were installed).
+ </p>
+
+ <p>
+ The development package should contain a symlink for the associated
+ shared library without a version number. For example, the
+ <package>libgdbm-dev</package> package should include a symlink
+ from <file>/usr/lib/libgdbm.so</file> to
+ <file>libgdbm.so.3.0.0</file>. This symlink is needed by the linker
+ (<prgn>ld</prgn>) when compiling packages, as it will only look for
+ <file>libgdbm.so</file> when compiling dynamically.
+ </p>
+ </sect>
+
+ <sect id="sharedlibs-intradeps">
+ <heading>Dependencies between the packages of the same library</heading>
+
+ <p>
+ Typically the development version should have an exact
+ version dependency on the runtime library, to make sure that
+ compilation and linking happens correctly. The
+ <tt>${Source-Version}</tt> substitution variable can be
+ useful for this purpose.
+ </p>
+ </sect>
+
+ <sect id="sharedlibs-shlibdeps">
+ <heading>Dependencies between the library and other packages -
+ the <tt>shlibs</tt> system</heading>
+
+ <p>
+ If a package contains a binary or library which links to a
+ shared library, we must ensure that when the package is
+ installed on the system, all of the libraries needed are
+ also installed. This requirement led to the creation of the
+ <tt>shlibs</tt> system, which is very simple in its design:
+ any package which <em>provides</em> a shared library also
+ provides information on the package dependencies required to
+ ensure the presence of this library, and any package which
+ <em>uses</em> a shared library uses this information to
+ determine the dependencies it requires. The files which
+ contain the mapping from shared libraries to the necessary
+ dependency information are called <file>shlibs</file> files.
+ </p>
+
+ <p>
+ Thus, when a package is built which contains any shared
+ libraries, it must provide a <file>shlibs</file> file for other
+ packages to use, and when a package is built which contains
+ any shared libraries or compiled binaries, it must run
+ <prgn>dpkg-shlibdeps</prgn> on these to determine the
+ libraries used and hence the dependencies needed by this
+ package.<footnote>
+ <p>
+ In the past, the shared libraries linked to were
+ determined by calling <prgn>ldd</prgn>, but now
+ <prgn>objdump</prgn> is used to do this. The only
+ change this makes to package building is that
+ <prgn>dpkg-shlibdeps</prgn> must also be run on shared
+ libraries, whereas in the past this was unnecessary.
+ The rest of this footnote explains the advantage that
+ this method gives.
+ </p>
+
+ <p>
+ We say that a binary <tt>foo</tt> <em>directly</em> uses
+ a library <tt>libbar</tt> if it is explicitly linked
+ with that library (that is, it uses the flag
+ <tt>-lbar</tt> during the linking stage). Other
+ libraries that are needed by <tt>libbar</tt> are linked
+ <em>indirectly</em> to <tt>foo</tt>, and the dynamic
+ linker will load them automatically when it loads
+ <tt>libbar</tt>. A package should depend on
+ the libraries it directly uses, and the dependencies for
+ those libraries should automatically pull in the other
+ libraries.
+ </p>
+
+ <p>
+ Unfortunately, the <prgn>ldd</prgn> program shows both
+ the directly and indirectly used libraries, meaning that
+ the dependencies determined included both direct and
+ indirect dependencies. The use of <prgn>objdump</prgn>
+ avoids this problem by determining only the directly
+ used libraries.
+ </p>
+
+ <p>
+ A good example of where this helps is the following. We
+ could update <tt>libimlib</tt> with a new version that
+ supports a new graphics format called dgf (but retaining
+ the same major version number). If we used the old
+ <prgn>ldd</prgn> method, every package that uses
+ <tt>libimlib</tt> would need to be recompiled so it
+ would also depend on <tt>libdgf</tt> or it wouldn't run
+ due to missing symbols. However with the new system,
+ packages using <tt>libimlib</tt> can rely on
+ <tt>libimlib</tt> itself having the dependency on
+ <tt>libdgf</tt> and so they would not need rebuilding.
+ </p>
+ </footnote>
+ </p>
+
+ <p>
+ In the following sections, we will first describe where the
+ various <tt>shlibs</tt> files are to be found, then how to
+ use <prgn>dpkg-shlibdeps</prgn>, and finally the
+ <tt>shlibs</tt> file format and how to create them if your
+ package contains a shared library.
+ </p>
+
+ <sect1>
+ <heading>The <tt>shlibs</tt> files present on the system</heading>
+
+ <p>
+ There are several places where <tt>shlibs</tt> files are
+ found. The following list gives them in the order in which
+ they are read by <prgn>dpkg-shlibdeps</prgn>. (The first
+ one which gives the required information is used.)
+ </p>
+
+ <p>
+ <list>
+ <item>
+ <p><file>debian/shlibs.local</file></p>
+
+ <p>
+ This lists overrides for this package. Its use is
+ described below (see <ref id="shlibslocal">).
+ </p>
+ </item>
+
+ <item>
+ <p><file>/etc/dpkg/shlibs.override</file></p>
+
+ <p>
+ This lists global overrides. This list is normally
+ empty. It is maintained by the local system
+ administrator.
+ </p>
+ </item>
+
+ <item>
+ <p><file>DEBIAN/shlibs</file> files in the "build directory"</p>
+
+ <p>
+ When packages are being built, any
+ <file>debian/shlibs</file> files are copied into the
+ control file area of the temporary build directory and
+ given the name <file>shlibs</file>. These files give
+ details of any shared libraries included in the
+ package.<footnote>
+ An example may help here. Let us say that the
+ source package <tt>foo</tt> generates two binary
+ packages, <tt>libfoo2</tt> and
+ <tt>foo-runtime</tt>. When building the binary
+ packages, the two packages are created in the
+ directories <file>debian/libfoo2</file> and
+ <file>debian/foo-runtime</file> respectively.
+ (<file>debian/tmp</file> could be used instead of one
+ of these.) Since <tt>libfoo2</tt> provides the
+ <tt>libfoo</tt> shared library, it will require a
+ <tt>shlibs</tt> file, which will be installed in
+ <file>debian/libfoo2/DEBIAN/shlibs</file>, eventually
+ to become
+ <file>/var/lib/dpkg/info/libfoo2.shlibs</file>. Then
+ when <prgn>dpkg-shlibdeps</prgn> is run on the
+ executable
+ <file>debian/foo-runtime/usr/bin/foo-prog</file>, it
+ will examine the
+ <file>debian/libfoo2/DEBIAN/shlibs</file> file to
+ determine whether <tt>foo-prog</tt>'s library
+ dependencies are satisfied by any of the libraries
+ provided by <tt>libfoo2</tt>. For this reason,
+ <prgn>dpkg-shlibdeps</prgn> must only be run once
+ all of the individual binary packages'
+ <tt>shlibs</tt> files have been installed into the
+ build directory.
+ </footnote>
+ </p>
+ </item>
+
+ <item>
+ <p><file>/var/lib/dpkg/info/*.shlibs</file></p>
+
+ <p>
+ These are the <file>shlibs</file> files corresponding to
+ all of the packages installed on the system, and are
+ maintained by the relevant package maintainers.
+ </p>
+ </item>
+
+ <item>
+ <p><file>/etc/dpkg/shlibs.default</file></p>
+
+ <p>
+ This file lists any shared libraries whose packages
+ have failed to provide correct <file>shlibs</file> files.
+ It was used when the <file>shlibs</file> setup was first
+ introduced, but it is now normally empty. It is
+ maintained by the <tt>dpkg</tt> maintainer.
+ </p>
+ </item>
+ </list>
+ </p>
+ </sect1>
+
+ <sect1>
+ <heading>How to use <prgn>dpkg-shlibdeps</prgn> and the
+ <file>shlibs</file> files</heading>
+
+ <p>
+ Put a call to <prgn>dpkg-shlibdeps</prgn> into your
+ <file>debian/rules</file> file. If your package contains only
+ compiled binaries and libraries (but no scripts), you can
+ use a command such as:
+ <example compact="compact">
+dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* \
+ debian/tmp/usr/lib/*
+ </example>
+ Otherwise, you will need to explicitly list the compiled
+ binaries and libraries.<footnote>
+ If you are using <tt>debhelper</tt>, the
+ <prgn>dh_shlibdeps</prgn> program will do this work for
+ you. It will also correctly handle multi-binary
+ packages.
+ </footnote>
+ </p>
+
+ <p>
+ This command puts the dependency information into the
+ <file>debian/substvars</file> file, which is then used by
+ <prgn>dpkg-gencontrol</prgn>. You will need to place a
+ <tt>${shlib:Depends}</tt> variable in the <tt>Depends</tt>
+ field in the control file for this to work.
+ </p>
+
+ <p>
+ If <prgn>dpkg-shlibdeps</prgn> doesn't complain, you're
+ done. If it does complain you might need to create your own
+ <file>debian/shlibs.local</file> file, as explained below (see
+ <ref id="shlibslocal">).
+ </p>
+
+ <p>
+ If you have multiple binary packages, you will need to call
+ <prgn>dpkg-shlibdeps</prgn> on each one which contains
+ compiled libraries or binaries. In such a case, you will
+ need to use the <tt>-T</tt> option to the <tt>dpkg</tt>
+ utilities to specify a different <file>substvars</file> file.
+ For more details on this and other options, see <manref
+ name="dpkg-shlibdeps" section="1">.
+ </p>
+ </sect1>
+
+ <sect1 id="shlibs">
+ <heading>The <file>shlibs</file> File Format</heading>
+
+ <p>
+ Each <file>shlibs</file> file has the same format. Lines
+ beginning with <tt>#</tt> are considered to be comments and
+ are ignored. Each line is of the form:
+ <example compact="compact">
+<var>library-name</var> <var>soname-version-number</var> <var>dependencies ...</var>
+ </example>
+ </p>
+
+ <p>
+ We will explain this by reference to the example of the
+ <tt>zlib1g</tt> package, which (at the time of writing)
+ installs the shared library <file>/usr/lib/libz.so.1.1.3</file>.
+ </p>
+
+ <p>
+ <var>library-name</var> is the name of the shared library,
+ in this case <tt>libz</tt>. (This must match the name part
+ of the soname, see below.)
+ </p>
+
+ <p>
+ <var>soname-version-number</var> is the version part of the
+ soname of the library. The soname is the thing that must
+ exactly match for the library to be recognized by the
+ dynamic linker, and is usually of the form
+ <tt><var>name</var>.so.<var>major-version</var></tt>, in our
+ example, <tt>libz.so.1</tt>.<footnote>
+ This can be determined using the command
+ <example compact="compact">
+objdump -p /usr/lib/libz.so.1.1.3 | grep SONAME
+ </example>
+ </footnote>
+ The version part is the part which comes after
+ <tt>.so.</tt>, so in our case, it is <tt>1</tt>.
+ </p>
+
+ <p>
+ <var>dependencies</var> has the same syntax as a dependency
+ field in a binary package control file. It should give
+ details of which packages are required to satisfy a binary
+ built against the version of the library contained in the
+ package. See <ref id="depsyntax"> for details.
+ </p>
+
+ <p>
+ In our example, if the first version of the <tt>zlib1g</tt>
+ package which contained a minor number of at least
+ <tt>1.3</tt> was <var>1:1.1.3-1</var>, then the
+ <tt>shlibs</tt> entry for this library could say:
+ <example compact="compact">
+libz 1 zlib1g (>= 1:1.1.3)
+ </example>
+ The version-specific dependency is to avoid warnings from
+ the dynamic linker about using older shared libraries with
+ newer binaries.
+ </p>
+ </sect1>
+
+ <sect1>
+ <heading>Providing a <file>shlibs</file> file</heading>
+
+ <p>
+ If your package provides a shared library, you should create
+ a <file>shlibs</file> file following the format described above.
+ It is usual to call this file <file>debian/shlibs</file> (but if
+ you have multiple binary packages, you might want to call it
+ <file>debian/shlibs.<var>package</var></file> instead). Then
+ let <file>debian/rules</file> install it in the control area:
+ <example compact="compact">
+install -m644 debian/shlibs debian/tmp/DEBIAN
+ </example>
+ or, in the case of a multi-binary package:
+ <example compact="compact">
+install -m644 debian/shlibs.<var>package</var> debian/<var>package</var>/DEBIAN/shlibs
+ </example>
+ An alternative way of doing this is to create the
+ <file>shlibs</file> file in the control area directly from
+ <file>debian/rules</file> without using a <file>debian/shlibs</file>
+ file at all,<footnote>
+ This is what <prgn>dh_makeshlibs</prgn> in the
+ <tt>debhelper</tt> suite does.
+ </footnote>
+ since the <file>debian/shlibs</file> file itself is ignored by
+ <prgn>dpkg-shlibdeps</prgn>.
+ </p>
+
+ <p>
+ As <prgn>dpkg-shlibdeps</prgn> reads the
+ <file>DEBIAN/shlibs</file> files in all of the binary packages
+ being built from this source package, all of the
+ <file>DEBIAN/shlibs</file> files should be installed before
+ <prgn>dpkg-shlibdeps</prgn> is called on any of the binary
+ packages.
+ </p>
+ </sect1>
+
+ <sect1 id="shlibslocal">
+ <heading>Writing the <file>debian/shlibs.local</file> file</heading>
+
+ <p>
+ This file is intended only as a <em>temporary</em> fix if
+ your binaries or libraries depend on a library whose package
+ does not yet provide a correct <file>shlibs</file> file.
+ </p>
+
+ <p>
+ We will assume that you are trying to package a binary
+ <tt>foo</tt>. When you try running
+ <prgn>dpkg-shlibdeps</prgn> you get the following error
+ message (<tt>-O</tt> displays the dependency information on
+ <tt>stdout</tt> instead of writing it to
+ <tt>debian/substvars</tt>, and the lines have been wrapped
+ for ease of reading):
+ <example compact="compact">
+$ dpkg-shlibdeps -O debian/tmp/usr/bin/foo
+dpkg-shlibdeps: warning: unable to find dependency
+ information for shared library libbar (soname 1,
+ path /usr/lib/libbar.so.1, dependency field Depends)
+shlibs:Depends=libc6 (>= 2.2.2-2)
+ </example>
+ You can then run <prgn>ldd</prgn> on the binary to find the
+ full location of the library concerned:
+ <example compact="compact">
+$ ldd foo
+libbar.so.1 => /usr/lib/libbar.so.1 (0x4001e000)
+libc.so.6 => /lib/libc.so.6 (0x40032000)
+/lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
+ </example>
+ So the <prgn>foo</prgn> binary depends on the
+ <prgn>libbar</prgn> shared library, but no package seems to
+ provide a <file>*.shlibs</file> file handling
+ <file>libbar.so.1</file> in <file>/var/lib/dpkg/info/</file>. Let's
+ determine the package responsible:
+ <example compact="compact">
+$ dpkg -S /usr/lib/libbar.so.1
+bar1: /usr/lib/libbar.so.1
+$ dpkg -s bar1 | grep Version
+Version: 1.0-1
+ </example>
+ This tells us that the <tt>bar1</tt> package, version 1.0-1,
+ is the one we are using. Now we can file a bug against the
+ <tt>bar1</tt> package and create our own
+ <file>debian/shlibs.local</file> to locally fix the problem.
+ Including the following line into your
+ <file>debian/shlibs.local</file> file:
+ <example compact="compact">
+libbar 1 bar1 (>= 1.0-1)
+ </example>
+ should allow the package build to work.
+ </p>
+
+ <p>
+ As soon as the maintainer of <tt>bar1</tt> provides a
+ correct <file>shlibs</file> file, you should remove this line
+ from your <file>debian/shlibs.local</file> file. (You should
+ probably also then have a versioned <tt>Build-Depends</tt>
+ on <tt>bar1</tt> to help ensure that others do not have the
+ same problem building your package.)
+ </p>
+ </sect1>
+
+ </sect>
+
+ </chapt>
+
+
+ <chapt id="opersys"><heading>The Operating System</heading>
+
+ <sect>
+ <heading>Filesystem hierarchy</heading>
+
+
+ <sect1 id="fhs">
+ <heading>Filesystem Structure</heading>
+
+ <p>
+ The location of all installed files and directories must
+ comply with the Filesystem Hierarchy Standard (FHS),
+ version 2.1, except where doing so would violate other
+ terms of Debian Policy. The version of this document
+ referred here can be found in the <tt>debian-policy</tt>
+ package or on
+ <url id="http://www.debian.org/doc/packaging-manuals/fhs/"
+ name="FHS (Debian copy)"> alongside this manual (or, if
+ you have the <package>debian-policy</package> installed,
+ you can try <url
+ id="file:///usr/share/doc/debian-policy/fhs/" name="FHS
+ (local copy)">). The
+ latest version, which may be a more recent version, may
+ be found on
+ <url id="http://www.pathname.com/fhs/" name="FHS (upstream)">.
+ Specific questions about following the standard may be
+ asked on the <tt>debian-devel</tt> mailing list, or
+ referred to the FHS mailing list (see the
+ <url id="http://www.pathname.com/fhs/" name="FHS web site"> for
+ more information).
+ </p>
+ </sect1>
+
+ <sect1>
+ <heading>Site-specific programs</heading>
+
+ <p>
+ As mandated by the FHS, packages must not place any
+ files in <file>/usr/local</file>, either by putting them in
+ the file system archive to be unpacked by <prgn>dpkg</prgn>
+ or by manipulating them in their maintainer scripts.
+ </p>
+
+ <p>
+ However, the package may create empty directories below
+ <file>/usr/local</file> so that the system administrator knows
+ where to place site-specific files. These directories
+ should be removed on package removal if they are
+ empty.
+ </p>
+
+ <p>
+ Note, that this applies only to directories <em>below</em>
+ <file>/usr/local</file>, not <em>in</em> <file>/usr/local</file>.
+ Packages must not create sub-directories in the directory
+ <file>/usr/local</file> itself, except those listed in FHS,
+ section 4.5. However, you may create directories below
+ them as you wish. You must not remove any of the
+ directories listed in 4.5, even if you created them.
+ </p>
+
+ <p>
+ Since <file>/usr/local</file> can be mounted read-only from a
+ remote server, these directories must be created and
+ removed by the <prgn>postinst</prgn> and <prgn>prerm</prgn>
+ maintainer scripts and not be included in the
+ <file>.deb</file> archive. These scripts must not fail if
+ either of these operations fail.
+ </p>
+
+ <p>
+ For example, the <tt>emacsen-common</tt> package could
+ contain something like
+ <example compact="compact">
+if [ ! -e /usr/local/share/emacs ]
+then
+ if mkdir /usr/local/share/emacs 2>/dev/null
+ then
+ chown root:staff /usr/local/share/emacs
+ chmod 2775 /usr/local/share/emacs
+ fi
+fi
+ </example>
+ in its <prgn>postinst</prgn> script, and
+ <example compact="compact">
+rmdir /usr/local/share/emacs/site-lisp 2>/dev/null || true
+rmdir /usr/local/share/emacs 2>/dev/null || true
+ </example>
+ in the <prgn>prerm</prgn> script. (Note that this form is
+ used to ensure that if the script is interrupted, the
+ directory <file>/usr/local/share/emacs</file> will still be
+ removed.)
+ </p>
+
+ <p>
+ If you do create a directory in <file>/usr/local</file> for
+ local additions to a package, you should ensure that
+ settings in <file>/usr/local</file> take precedence over the
+ equivalents in <file>/usr</file>.
+ </p>
+
+ <p>
+ However, because <file>/usr/local</file> and its contents are
+ for exclusive use of the local administrator, a package
+ must not rely on the presence or absence of files or
+ directories in <file>/usr/local</file> for normal operation.
+ </p>
+
+ <p>
+ The <file>/usr/local</file> directory itself and all the
+ subdirectories created by the package should (by default) have
+ permissions 2775 (group-writable and set-group-id) and be
+ owned by <tt>root.staff</tt>.
+ </p>
+ </sect1>
+
+ <sect1>
+ <heading>The system-wide mail directory</heading>
+ <p>
+ The system-wide mail directory is <file>/var/mail</file>. This
+ directory is part of the base system and should not owned
+ by any particular mail agents. The use of the old
+ location <file>/var/spool/mail</file> is deprecated, even
+ though the spool may still be physically located there.
+ To maintain partial upgrade compatibility for systems
+ which have <file>/var/spool/mail</file> as their physical mail
+ spool, packages using <file>/var/mail</file> must depend on
+ either <package>libc6</package> (>= 2.1.3-13), or on
+ <package>base-files</package> (>= 2.2.0), or on later
+ versions of either one of these packages.
+ </p>
+ </sect1>
+ </sect>
+
+ <sect>
+ <heading>Users and groups</heading>
+
+ <sect1>
+ <heading>Introduction</heading>
+ <p>
+ The Debian system can be configured to use either plain or
+ shadow passwords.
+ </p>
+
+ <p>
+ Some user ids (UIDs) and group ids (GIDs) are reserved
+ globally for use by certain packages. Because some
+ packages need to include files which are owned by these
+ users or groups, or need the ids compiled into binaries,
+ these ids must be used on any Debian system only for the
+ purpose for which they are allocated. This is a serious
+ restriction, and we should avoid getting in the way of
+ local administration policies. In particular, many sites
+ allocate users and/or local system groups starting at 100.
+ </p>
+
+ <p>
+ Apart from this we should have dynamically allocated ids,
+ which should by default be arranged in some sensible
+ order, but the behavior should be configurable.
+ </p>
+
+ <p>
+ Packages other than <tt>base-passwd</tt> must not modify
+ <file>/etc/passwd</file>, <file>/etc/shadow</file>,
+ <file>/etc/group</file> or <file>/etc/gshadow</file>.
+ </p>
+ </sect1>
+
+ <sect1>
+ <heading>UID and GID classes</heading>
+ <p>
+ The UID and GID numbers are divided into classes as
+ follows:
+ <taglist>
+ <tag>0-99:</tag>
+ <item>
+ <p>
+ Globally allocated by the Debian project, the same
+ on every Debian system. These ids will appear in
+ the <file>passwd</file> and <file>group</file> files of all
+ Debian systems, new ids in this range being added
+ automatically as the <tt>base-passwd</tt> package is
+ updated.
+ </p>
+
+ <p>
+ Packages which need a single statically allocated
+ uid or gid should use one of these; their
+ maintainers should ask the <tt>base-passwd</tt>
+ maintainer for ids.
+ </p>
+ </item>
+
+ <tag>100-999:</tag>
+ <item>
+ <p>
+ Dynamically allocated system users and groups.
+ Packages which need a user or group, but can have
+ this user or group allocated dynamically and
+ differently on each system, should use <tt>adduser
+ --system</tt> to create the group and/or user.
+ <prgn>adduser</prgn> will check for the existence of
+ the user or group, and if necessary choose an unused
+ id based on the ranges specified in
+ <file>adduser.conf</file>.
+ </p>
+ </item>
+
+ <tag>1000-29999:</tag>
+ <item>
+ <p>
+ Dynamically allocated user accounts. By default
+ <prgn>adduser</prgn> will choose UIDs and GIDs for
+ user accounts in this range, though
+ <file>adduser.conf</file> may be used to modify this
+ behavior.
+ </p>
+ </item>
+
+ <tag>30000-59999:</tag>
+ <item>
+ <p>Reserved.</p>
+ </item>
+
+ <tag>60000-64999:</tag>
+ <item>
+ <p>
+ Globally allocated by the Debian project, but only
+ created on demand. The ids are allocated centrally
+ and statically, but the actual accounts are only
+ created on users' systems on demand.
+ </p>
+
+ <p>
+ These ids are for packages which are obscure or
+ which require many statically-allocated ids. These
+ packages should check for and create the accounts in
+ <file>/etc/passwd</file> or <file>/etc/group</file> (using
+ <prgn>adduser</prgn> if it has this facility) if
+ necessary. Packages which are likely to require
+ further allocations should have a "hole" left after
+ them in the allocation, to give them room to
+ grow.
+ </p>
+ </item>
+
+ <tag>65000-65533:</tag>
+ <item>
+ <p>Reserved.</p>
+ </item>
+
+ <tag>65534:</tag>
+ <item>
+ <p>
+ User <tt>nobody</tt>. The corresponding gid refers
+ to the group <tt>nogroup</tt>.
+ </p>
+ </item>
+
+ <tag>65535:</tag>
+ <item>
+ <p>
+ <tt>(uid_t)(-1) == (gid_t)(-1)</tt> <em>must
+ not</em> be used, because it is the error return
+ sentinel value.
+ </p>
+ </item>
+ </taglist>
+ </p>
+ </sect1>
+ </sect>
+
+ <sect id="sysvinit">
+ <heading>System run levels and <file>init.d</file> scripts</heading>
+
+ <sect1 id="/etc/init.d">
+ <heading>Introduction</heading>
+
+ <p>
+ The <file>/etc/init.d</file> directory contains the scripts
+ executed by <prgn>init</prgn> at boot time and when the
+ init state (or "runlevel") is changed (see <manref
+ name="init" section="8">).
+ </p>
+
+ <p>
+ There are at least two different, yet functionally
+ equivalent, ways of handling these scripts. For the sake
+ of simplicity, this document describes only the symbolic
+ link method. However, it must not be assumed by maintainer
+ scripts that this method is being used, and any automated
+ manipulation of the various runlevel behaviours by
+ maintainer scripts must be performed using
+ <prgn>update-rc.d</prgn> as described below and not by
+ manually installing or removing symlinks. For information
+ on the implementation details of the other method,
+ implemented in the <tt>file-rc</tt> package, please refer
+ to the documentation of that package.
+ </p>
+
+ <p>
+ These scripts are referenced by symbolic links in the
+ <file>/etc/rc<var>n</var>.d</file> directories. When changing
+ runlevels, <prgn>init</prgn> looks in the directory
+ <file>/etc/rc<var>n</var>.d</file> for the scripts it should
+ execute, where <tt><var>n</var></tt> is the runlevel that
+ is being changed to, or <tt>S</tt> for the boot-up
+ scripts.
+ </p>
+
+ <p>
+ The names of the links all have the form
+ <file>S<var>mm</var><var>script</var></file> or
+ <file>K<var>mm</var><var>script</var></file> where
+ <var>mm</var> is a two-digit number and <var>script</var>
+ is the name of the script (this should be the same as the
+ name of the actual script in <file>/etc/init.d</file>).
+ </p>
+
+ <p>
+ When <prgn>init</prgn> changes runlevel first the targets
+ of the links whose names start with a <tt>K</tt> are
+ executed, each with the single argument <tt>stop</tt>,
+ followed by the scripts prefixed with an <tt>S</tt>, each
+ with the single argument <tt>start</tt>. (The links are
+ those in the <file>/etc/rc<var>n</var>.d</file> directory
+ corresponding to the new runlevel.) The <tt>K</tt> links
+ are responsible for killing services and the <tt>S</tt>
+ link for starting services upon entering the runlevel.
+ </p>
+
+ <p>
+ For example, if we are changing from runlevel 2 to
+ runlevel 3, init will first execute all of the <tt>K</tt>
+ prefixed scripts it finds in <file>/etc/rc3.d</file>, and then
+ all of the <tt>S</tt> prefixed scripts in that directory.
+ The links starting with <tt>K</tt> will cause the
+ referred-to file to be executed with an argument of
+ <tt>stop</tt>, and the <tt>S</tt> links with an argument
+ of <tt>start</tt>.
+ </p>
+
+ <p>
+ The two-digit number <var>mm</var> is used to determine
+ the order in which to run the scripts: low-numbered links
+ have their scripts run first. For example, the
+ <tt>K20</tt> scripts will be executed before the
+ <tt>K30</tt> scripts. This is used when a certain service
+ must be started before another. For example, the name
+ server <prgn>bind</prgn> might need to be started before
+ the news server <prgn>inn</prgn> so that <prgn>inn</prgn>
+ can set up its access lists. In this case, the script
+ that starts <prgn>bind</prgn> would have a lower number
+ than the script that starts <prgn>inn</prgn> so that it
+ runs first:
+ <example compact="compact">
+/etc/rc2.d/S17bind
+/etc/rc2.d/S70inn
+ </example>
+ </p>
+
+ <p>
+ The two runlevels 0 (halt) and 6 (reboot) are slightly
+ different. In these runlevels, the links with an
+ <tt>S</tt> prefix are still called after those with a
+ <tt>K</tt> prefix, but they too are called with the single
+ argument <tt>stop</tt>.
+ </p>
+
+ <p>
+ Also, if the script name ends <tt>.sh</tt>, the script
+ will be sourced in runlevel <tt>S</tt> rather that being
+ run in a forked subprocess, but will be explicitly run by
+ <prgn>sh</prgn> in all other runlevels.
+ </p>
+ </sect1>
+
+ <sect1>
+ <heading>Writing the scripts</heading>
+
+ <p>
+ Packages that include daemons for system services should
+ place scripts in <file>/etc/init.d</file> to start or stop
+ services at boot time or during a change of runlevel.
+ These scripts should be named
+ <file>/etc/init.d/<var>package</var></file>, and they should
+ accept one argument, saying what to do:
+
+ <taglist>
+ <tag><tt>start</tt></tag>
+ <item>start the service,</item>
+
+ <tag><tt>stop</tt></tag>
+ <item>stop the service,</item>
+
+ <tag><tt>restart</tt></tag>
+ <item>stop and restart the service if it's already running,
+ otherwise start the service</item>
+
+ <tag><tt>reload</tt></tag>
+ <item><p>cause the configuration of the service to be
+ reloaded without actually stopping and restarting
+ the service,</item>
+
+ <tag><tt>force-reload</tt></tag>
+ <item>cause the configuration to be reloaded if the
+ service supports this, otherwise restart the
+ service.</item>
+ </taglist>
+
+ The <tt>start</tt>, <tt>stop</tt>, <tt>restart</tt>, and
+ <tt>force-reload</tt> options should be supported by all
+ scripts in <file>/etc/init.d</file>, the <tt>reload</tt>
+ option is optional.
+ </p>
+
+ <p>
+ The <file>init.d</file> scripts should ensure that they will
+ behave sensibly if invoked with <tt>start</tt> when the
+ service is already running, or with <tt>stop</tt> when it
+ isn't, and that they don't kill unfortunately-named user
+ processes. The best way to achieve this is usually to use
+ <prgn>start-stop-daemon</prgn>.
+ </p>
+
+ <p>
+ If a service reloads its configuration automatically (as
+ in the case of <prgn>cron</prgn>, for example), the
+ <tt>reload</tt> option of the <file>init.d</file> script
+ should behave as if the configuration has been reloaded
+ successfully.
+ </p>
+
+ <p>
+ The <file>/etc/init.d</file> scripts must be treated as
+ configuration files, either (if they are present in the
+ package, that is, in the .deb file) by marking them as
+ <tt>conffile</tt>s, or, (if they do not exist in the .deb)
+ by managing them correctly in the maintainer scripts (see
+ <ref id="config-files">). This is important since we want
+ to give the local system administrator the chance to adapt
+ the scripts to the local system, e.g., to disable a
+ service without de-installing the package, or to specify
+ some special command line options when starting a service,
+ while making sure her changes aren't lost during the next
+ package upgrade.
+ </p>
+
+ <p>
+ These scripts should not fail obscurely when the
+ configuration files remain but the package has been
+ removed, as configuration files remain on the system after
+ the package has been removed. Only when <prgn>dpkg</prgn>
+ is executed with the <tt>--purge</tt> option will
+ configuration files be removed. In particular, as the
+ <file>/etc/init.d/<var>package</var></file> script itself is
+ usually a <tt>conffile</tt>, it will remain on the system
+ if the package is removed but not purged. Therefore, you
+ should include a <tt>test</tt> statement at the top of the
+ script, like this:
+ <example compact="compact">
+test -f <var>program-executed-later-in-script</var> || exit 0
+ </example>
+ </p>
+
+ <p>
+ Often there are some variables in the <file>init.d</file>
+ scripts whose values control the behaviour of the scripts,
+ and which a system administrator is likely to want to
+ change. As the scripts themselves are frequently
+ <tt>conffile</tt>s, modifying them requires that the
+ administrator merge in their changes each time the package
+ is upgraded and the <tt>conffile</tt> changes. To ease
+ the burden on the system administrator, such configurable
+ values should not be placed directly in the script.
+ Instead, they should be placed in a file in
+ <file>/etc/default</file>, which typically will have the same
+ base name as the <file>init.d</file> script. This extra file
+ should be sourced by the script when the script runs. It
+ must contain only variable settings and comments in POSIX
+ <prgn>sh</prgn> format. It may either be a
+ <tt>conffile</tt> or a configuration file maintained by
+ the package maintainer scripts. See <ref id="config-files">
+ for more details.
+ </p>
+
+ <p>
+ To ensure that vital configurable values are always
+ available, the <file>init.d</file> script should set default
+ values for each of the shell variables it uses, either
+ before sourcing the <file>/etc/default/</file> file or
+ afterwards using something like the <tt>:
+ ${VAR:=default}</tt> syntax. Also, the <file>init.d</file>
+ script must behave sensibly and not fail if the
+ <file>/etc/default</file> file is deleted.
+ </p>
+ </sect1>
+
+ <sect1>
+ <heading>Interfacing with the initscript system</heading>
+
+ <p>
+ Maintainers should use the abstraction layer provided by
+ the <prgn>update-rc.d</prgn> and <prgn>invoke-rc.d</prgn>
+ programs to deal with initscripts in their packages'
+ scripts such as <prgn>postinst</prgn>, <prgn>prerm</prgn>
+ and <prgn>postrm</prgn>.
+ </p>
+
+ <p>
+ Directly managing the /etc/rc?.d links and directly
+ invoking the <file>/etc/init.d/</file> initscripts should
+ be done only by packages providing the initscript
+ subsystem (such as <prgn>sysv-rct</prgn> and
+ <prgn>file-rc</prgn>).
+ </p>
+
+ <sect2>
+ <heading>Managing the links</heading>
+
+ <p>
+ The program <prgn>update-rc.d</prgn> is provided for
+ package maintainers to arrange for the proper creation and
+ removal of <file>/etc/rc<var>n</var>.d</file> symbolic links,
+ or their functional equivalent if another method is being
+ used. This may be used by maintainers in their packages'
+ <prgn>postinst</prgn> and <prgn>postrm</prgn> scripts.
+ </p>
+
+ <p>
+ You must not include any <file>/etc/rc<var>n</var>.d</file>
+ symbolic links in the actual archive or manually create or
+ remove the symbolic links in maintainer scripts; you must
+ use the <prgn>update-rc.d</prgn> program instead. (The
+ former will fail if an alternative method of maintaining
+ runlevel information is being used.) You must not include
+ the <file>/etc/rc<var>n</var>.d</file> directories themselves
+ in the archive either. (Only the <tt>sysvinit</tt>
+ package may do so.)
+ </p>
+
+ <p>
+ By default <prgn>update-rc.d</prgn> will start services in
+ each of the multi-user state runlevels (2, 3, 4, and 5)
+ and stop them in the halt runlevel (0), the single-user
+ runlevel (1) and the reboot runlevel (6). The system
+ administrator will have the opportunity to customize
+ runlevels by simply adding, moving, or removing the
+ symbolic links in <file>/etc/rc<var>n</var>.d</file> if
+ symbolic links are being used, or by modifying
+ <file>/etc/runlevel.conf</file> if the <tt>file-rc</tt> method
+ is being used.
+ </p>
+
+ <p>
+ To get the default behavior for your package, put in your
+ <prgn>postinst</prgn> script
+ <example compact="compact">
+ update-rc.d <var>package</var> defaults
+ </example>
+ and in your <prgn>postrm</prgn>
+ <example compact="compact">
+ if [ "$1" = purge ]; then
+ update-rc.d <var>package</var> remove
+ fi
+ </example>. Note that if your package changes runlevels
+ or priority, you may have to remove and recreate the links,
+ since otherwise the old links may persist. Refer to the
+ documentation of <prgn>update-rc.d</prgn>.
+ </p>
+
+ <p>
+ This will use a default sequence number of 20. If it does
+ not matter when or in which order the <file>init.d</file>
+ script is run, use this default. If it does, then you
+ should talk to the maintainer of the <prgn>sysvinit</prgn>
+ package or post to <tt>debian-devel</tt>, and they will
+ help you choose a number.
+ </p>
+
+ <p>
+ For more information about using <tt>update-rc.d</tt>,
+ please consult its manpage <manref name="update-rc.d"
+ section="8">.
+ </p>
+ </sect2>
+
+ <sect2>
+ <heading>Running initscripts</heading>
+ <p>
+ The program <prgn>invoke-rc.d</prgn> is provided to make
+ it easier for package maintainers to properly invoke an
+ initscript, obeying runlevel and other locally-defined
+ constraints that might limit a package's right to start,
+ stop and otherwise manage services. This program may be
+ used by maintainers in their packages' scripts.
+ </p>
+
+ <p>
+ The use of <prgn>invoke-rc.d</prgn> to invoke the
+ <file>/etc/init.d/*</file> initscripts is strongly
+ recommended<footnote>
+ In the future, the use of invoke-rc.d to invoke
+ initscripts shall be made mandatory. Maintainers are
+ advised to switch to invoke-rc.d as soon as
+ possible.
+ </footnote>, instead of calling them directly.
+ </p>
+
+ <p>
+ By default, <prgn>invoke-rc.d</prgn> will pass any
+ action requests (start, stop, reload, restart...) to the
+ <file>/etc/init.d</file> script, filtering out requests
+ to start or restart a service out of its intended
+ runlevels.
+ </p>
+
+ <p>
+ Most packages will simply need to change:
+ <example compact="compact">/etc/init.d/<package>
+ <action></example> in their <prgn>postinst</prgn>
+ and <prgn>prerm</prgn> scripts to:
+ <example compact="compact">
+ if [ -x /usr/sbin/invoke-rc.d ] ; then
+ invoke-rc.d <var>package</var> <action>
+ else
+ /etc/init.d/<var>package</var> <action>
+ fi
+ </example>
+ </p>
+
+ <p>
+ A package should register its initscript services using
+ <prgn>update-rc.d</prgn> before it tries to invoke them
+ using <prgn>invoke-rc.d</prgn>. Invocation of
+ unregistered services may fail.
+ </p>
+
+ <p>
+ For more information about using
+ <prgn>invoke-rc.d</prgn>, please consult its manpage
+ <manref name="invoke-rc.d" section="8">.
+ </p>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <heading>Boot-time initialization</heading>
+
+ <p>
+ There used to be another directory, <file>/etc/rc.boot</file>,
+ which contained scripts which were run once per machine
+ boot. This has been deprecated in favour of links from
+ <file>/etc/rcS.d</file> to files in <file>/etc/init.d</file> as
+ described in <ref id="/etc/init.d">. Packages must not
+ place files in <file>/etc/rc.boot</file>.
+ </p>
+ </sect1>
+
+ <sect1>
+ <heading>Example</heading>