+++ /dev/null
-<!doctype debiandoc system[
-<!-- include version information so we don't have to hard code it
- within the document -->
-<!entity % versiondata SYSTEM "version.ent"> %versiondata;
-]>
-
-<!--
- Debian GNU/Linux Packaging Manual.
- 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>
- -->
-
-<debiandoc>
- <book>
-
- <titlepag><title>Debian Packaging Manual</title>
- <author>
- <name>Ian Jackson </name>
- <email>ijackson@gnu.ai.mit.edu</email>
- </author>
- <author>
- <name>Revised: David A. Morris</name>
- <email>bweaver@debian.org</email>
- </author>
- <author>
- <name>Maintainer: Christian Schwarz </name>
- <email>schwarz@debian.org</email>
- </author>
- <author>
- <name>Maintainer: Manoj Srivastava </name>
- <email>srivasta@debian.org</email>
- </author>
- <author>
- <name>Maintainer: Julian Gilbey </name>
- <email>J.D.Gilbey@qmw.ac.uk</email>
- </author>
- <author>
- <name>Maintainer: The Debian Policy group </name>
- <email>debian-policy@lists.debian.org</email>
- </author>
- <version>version &version;, &date;</version>
-
- <abstract>
- This manual describes the technical aspects of creating Debian
- binary and source packages. It does not deal with the Debian
- Project policy requirements, and it assumes familiarity with
- <prgn>dpkg</prgn>'s functions from the system administrator's
- perspective. This package itself is maintained by a group of
- maintainers that have no editorial powers. At the moment, the
- list of maintainers is:
- <enumlist>
- <item>
- <p>Michael Alan Dorman <email>mdorman@debian.org</email></p>
- </item>
- <item>
- <p>Richard Braakman <email>dark@xs4all.nl</email></p>
- </item>
- <item>
- <p>Philip Hands <email>phil@hands.com</email></p>
- </item>
- <item>
- <p>Julian Gilbey <email>J.D.Gilbey@qmw.ac.uk</email></p>
- </item>
- <item>
- <p>Manoj Srivastava <email>srivasta@debian.org</email></p>
- </item>
- </enumlist>
- </abstract>
-
-
- <copyright>
- <copyrightsummary>Copyright ©1996 Ian Jackson.</copyrightsummary>
- <p>
- This manual is free software; you may redistribute it and/or
- modify it under the terms of the GNU General Public License
- as published by the Free Software Foundation; either version
- 2, or (at your option) any later version.
- </p>
-
- <p>
- This is distributed in the hope that it will be useful, but
- <em>without any warranty</em>; without even the implied
- warranty of merchantability or fitness for a particular
- purpose. See the GNU General Public License for more
- details.
- </p>
-
- <p>
- A copy of the GNU General Public License is available as
- <tt>/usr/doc/copyright/GPL</tt> in the Debian GNU/Linux
- distribution or on the World Wide Web at
- <tt>http://www.gnu.org/copyleft/gpl.html</tt>. You can also
- obtain it by writing to the Free Software Foundation, Inc.,
- 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
- </p>
- </copyright>
-
- <toc detail="sect">
-
- <!-- Describes the technical interface between a package and dpkg.
-
- How to safely put shared libraries in a package. Details of
- dpkg's handling of individual files. Sections on when to use
- which feature (eg Replaces vs. Replaces/Conflicts
- vs. update-alternatives vs. diversions) Cross-references to the
- policy document (see below) where appropriate. Description of the
- interface between dselect and its access methods. Hints on where
- to start with a new package (ie, the hello package). What to do
- about file aliasing.
-
- file aliasing
-
- Manpages are required for: update-rc.d, diversions,
- update-alternatives, install-info in a package.
-
- -->
-
- <chapt id="scope">
- <heading>Introduction and scope of this manual</heading>
-
- <p>
- <prgn>dpkg</prgn> is a suite of programs for creating binary
- package files and installing and removing them on Unix
- systems.<footnote>
- <p>
- <prgn>dpkg</prgn> is targetted primarily at Debian
- GNU/Linux, but may work on or be ported to other
- systems.
- </p>
- </footnote>
- </p>
-
- <p>
- The binary packages are designed for the management of
- installed executable programs (usually compiled binaries) and
- their associated data, though source code examples and
- documentation are provided as part of some packages.</p>
-
- <p>
- This manual describes the technical aspects of creating Debian
- binary packages (<tt>.deb</tt> files). It documents the
- behaviour of the package management programs
- <prgn>dpkg</prgn>, <prgn>dselect</prgn> et al. and the way
- they interact with packages.</p>
-
- <p>
- It also documents the interaction between
- <prgn>dselect</prgn>'s core and the access method scripts it
- uses to actually install the selected packages, and describes
- how to create a new access method.</p>
-
- <p>
- This manual does not go into detail about the options and
- usage of the package building and installation tools. It
- should therefore be read in conjuction with those programs'
- manpages.
- </p>
-
- <p>
- The utility programs which are provided with <prgn>dpkg</prgn>
- for managing various system configuration and similar issues,
- such as <prgn>update-rc.d</prgn> and
- <prgn>install-info</prgn>, are not described in detail here -
- please see their manpages.
- </p>
-
- <p>
- It does <em>not</em> describe the policy requirements imposed
- on Debian packages, such as the permissions on files and
- directories, documentation requirements, upload procedure, and
- so on. You should see the Debian packaging policy manual for
- these details. (Many of them will probably turn out to be
- helpful even if you don't plan to upload your package and make
- it available as part of the distribution.)
- </p>
-
- <p>
- It is assumed that the reader is reasonably familiar with the
- <prgn>dpkg</prgn> System Administrators' manual.
- Unfortunately this manual does not yet exist.
- </p>
-
- <p>
- The Debian version of the FSF's GNU hello program is provided
- as an example for people wishing to create Debian
- packages. The Debian <prgn>debmake</prgn> package is
- recommended as a very helpful tool in creating and maintaining
- Debian packages. However, while the tools and examples are
- helpful, they do not replace the need to read and follow the
- Policy and Programmer's Manual.</p>
- </chapt>
-
- <chapt id="binarypkg"><heading>Binary packages
- </heading>
-
- <p>
- The binary package has two main sections. The first part
- consists of various control information files and scripts used
- by <prgn>dpkg</prgn> when installing and removing. See <ref
- id="controlarea">.
- </p>
-
- <p>
- The second part is an archive containing the files and
- directories to be installed.
- </p>
-
- <p>
- In the future binary packages may also contain other
- components, such as checksums and digital signatures. The
- format for the archive is described in full in the
- <tt>deb(5)</tt> manpage.
- </p>
-
-
- <sect id="bincreating"><heading>Creating package files -
- <prgn>dpkg-deb</prgn>
- </heading>
-
- <p>
- All manipulation of binary package files is done by
- <prgn>dpkg-deb</prgn>; it's the only program that has
- knowledge of the format. (<prgn>dpkg-deb</prgn> may be
- invoked by calling <prgn>dpkg</prgn>, as <prgn>dpkg</prgn>
- will spot that the options requested are appropriate to
- <prgn>dpkg-deb</prgn> and invoke that instead with the same
- arguments.)
- </p>
-
- <p>
- In order to create a binary package you must make a
- directory tree which contains all the files and directories
- you want to have in the filesystem data part of the package.
- In Debian-format source packages this directory is usually
- <tt>debian/tmp</tt>, relative to the top of the package's
- source tree.
- </p>
-
- <p>
- They should have the locations (relative to the root of the
- directory tree you're constructing) ownerships and
- permissions which you want them to have on the system when
- they are installed.
- </p>
-
- <p>
- With current versions of <prgn>dpkg</prgn> the uid/username
- and gid/groupname mappings for the users and groups being
- used should be the same on the system where the package is
- built and the one where it is installed.
- </p>
-
- <p>
- You need to add one special directory to the root of the
- miniature filesystem tree you're creating:
- <prgn>DEBIAN</prgn>. It should contain the control
- information files, notably the binary package control file
- (see <ref id="controlfile">).
- </p>
-
- <p>
- The <prgn>DEBIAN</prgn> directory will not appear in the
- filesystem archive of the package, and so won't be installed
- by <prgn>dpkg</prgn> when the package is installed.
- </p>
-
- <p>
- When you've prepared the package, you should invoke:
- <example>
- dpkg --build <var>directory</var>
- </example>
- </p>
-
- <p>
- This will build the package in
- <tt><var>directory</var>.deb</tt>. (<prgn>dpkg</prgn> knows
- that <tt>--build</tt> is a <prgn>dpkg-deb</prgn> option, so
- it invokes <prgn>dpkg-deb</prgn> with the same arguments to
- build the package.)
- </p>
-
- <p>
- See the manpage <manref name="dpkg-deb" section="8"> for details of how
- to examine the contents of this newly-created file. You may find the
- output of following commands enlightening:
- <example>
- dpkg-deb --info <var>filename</var>.deb
- dpkg-deb --contents <var>filename</var>.deb
- dpkg --contents <var>filename</var>.deb
- </example>
- To view the copyright file for a package you could use this command:
- <example>
- dpkg --fsys-tarfile <var>filename</var>.deb | tar xof usr/doc/<var>\*</var>copyright | less
- </example>
- </p>
- </sect>
-
- <sect id="controlarea">
- <heading>
- Package control information files
- </heading>
-
- <p>
- The control information portion of a binary package is a
- collection of files with names known to <prgn>dpkg</prgn>.
- It will treat the contents of these files specially - some
- of them contain information used by <prgn>dpkg</prgn> when
- installing or removing the package; others are scripts which
- the package maintainer wants <prgn>dpkg</prgn> to run.
- </p>
-
- <p>
- It is possible to put other files in the package control
- area, but this is not generally a good idea (though they
- will largely be ignored).
- </p>
-
- <p>
- Here is a brief list of the control info files supported by
- <prgn>dpkg</prgn> and a summary of what they're used for.
- </p>
-
- <p>
- <taglist>
- <tag><tt>control</tt>
- <item>
-
- <p>
- This is the key description file used by
- <prgn>dpkg</prgn>. It specifies the package's name
- and version, gives its description for the user,
- states its relationships with other packages, and so
- forth. See <ref id="controlfile">.
- </p>
-
- <p>
- It is usually generated automatically from information
- in the source package by the
- <prgn>dpkg-gencontrol</prgn> program, and with
- assistance from <prgn>dpkg-shlibdeps</prgn>. See <ref
- id="sourcetools">.</p>
- </item>
-
- <tag><tt>postinst</tt>, <tt>preinst</tt>, <tt>postrm</tt>,
- <tt>prerm</tt>
- </tag>
- <item>
-
- <p>
- These are exectuable files (usually scripts) which
- <prgn>dpkg</prgn> runs during installation, upgrade
- and removal of packages. They allow the package to
- deal with matters which are particular to that package
- or require more complicated processing than that
- provided by <prgn>dpkg</prgn>. Details of when and
- how they are called are in <ref
- id="maintainerscripts">.
- </p>
-
- <p>
- It is very important to make these scripts
- idempotent.
- <footnote>
- <p>
- That means that if it runs successfully or fails
- and then you call it again it doesn't bomb out,
- but just ensures that everything is the way it
- ought to be.
- </p>
- </footnote> This is so that if an error occurs, the
- user interrupts <prgn>dpkg</prgn> or some other
- unforeseen circumstance happens you don't leave the
- user with a badly-broken package.
- </p>
-
- <p>
- The maintainer scripts are guaranteed to run with a
- controlling terminal and can interact with the user.
- If they need to prompt for passwords, do full-screen
- interaction or something similar you should do these
- things to and from <tt>/dev/tty</tt>, since
- <prgn>dpkg</prgn> will at some point redirect scripts'
- standard input and output so that it can log the
- installation process. Likewise, because these scripts
- may be executed with standard output redirected into a
- pipe for logging purposes, Perl scripts should set
- unbuffered output by setting <tt>$|=1</tt> so that the
- output is printed immediately rather than being
- buffered.
- </p>
-
- <p>
- Each script should return a zero exit status for
- success, or a nonzero one for failure.</p>
- </item>
-
- <tag><tt>conffiles</tt>
- </tag>
- <item>
-
- <p>
- This file contains a list of configuration files which
- are to be handled automatically by <prgn>dpkg</prgn>
- (see <ref id="conffiles">). Note that not necessarily
- every configuration file should be listed here.</p>
- </item>
-
- <tag><tt>shlibs</tt>
- </tag>
- <item>
-
- <p>
- This file contains a list of the shared libraries
- supplied by the package, with dependency details for
- each. This is used by <prgn>dpkg-shlibdeps</prgn>
- when it determines what dependencies are required in a
- package control file. The <tt>shlibs</tt> file format
- is described on <ref id="shlibs">.
- </p>
- </item>
- </taglist>
- </p>
-
- <sect id="controlfile">
- <heading>
- The main control information file: <tt>control</tt>
- </heading>
- <p>
- The most important control information file used by
- <prgn>dpkg</prgn> when it installs a package is
- <tt>control</tt>. It contains all the package's `vital
- statistics'.
- </p>
-
- <p>
- The binary package control files of packages built from
- Debian sources are made by a special tool,
- <prgn>dpkg-gencontrol</prgn>, which reads
- <tt>debian/control</tt> and <tt>debian/changelog</tt> to
- find the information it needs. See <ref id="sourcepkg"> for
- more details.
- </p>
-
- <p>
- The fields in binary package control files are:
- <list compact="compact">
- <item>
- <p><qref id="f-Package"><tt>Package</tt></qref> (mandatory)</p>
- </item>
- <item>
- <p><qref id="versions"><tt>Version</tt></qref> (mandatory)</p>
- </item>
- <item><p><qref id="f-Architecture"><tt>Architecture</tt></qref>
- (mandatory)
- <footnote>
- <p>
- This field should appear in all packages, though
- <prgn>dpkg</prgn> doesn't require it yet so that
- old packages can still be installed.
- </p>
- </footnote>
- </p>
- </item>
- <item>
- <p><qref id="relationships"><tt>Depends</tt>,
- <tt>Provides</tt> et al.</qref></p>
- </item>
- <item>
- <p><qref id="f-Essential"><tt>Essential</tt></qref></p>
- </item>
- <item>
- <p><qref id="f-Maintainer"><tt>Maintainer</tt></qref></p>
- </item>
- <item>
- <p><qref id="f-classification"><tt>Section</tt>,
- <tt>Priority</tt></qref></p>
- </item>
- <item>
- <p><qref id="f-Source"><tt>Source</tt></qref></p>
- </item>
- <item>
- <p><qref id="descriptions"><tt>Description</tt></qref></p>
- </item>
- <item>
- <p>
- <qref id="f-Installed-Size"><tt>Installed-Size</tt></qref>
- </p>
- </item>
- </list>
-
- <p>
- A description of the syntax of control files and the purpose
- of these fields is available in <ref id="controlfields">.
- </p>
- </sect>
- <sect>
- <heading>Time Stamps</heading>
- <p>
- Maintainers are encouraged to preserve the modification
- times of the upstream source files in a package, as far as
- is reasonably possible.
- <footnote>
- <p>
- The rationale is that there is some information conveyed
- by knowing the age of the file, for example, you could
- recognize that some documentation is very old by looking
- at the modification time, so it would be nice if the
- modification time of the upstream source would be
- preserved.
- </p>
- </footnote>
- </p>
- </sect>
- </chapt>
-
- <chapt id="sourcepkg">
- <heading>Source packages</heading>
-
- <p>
- The Debian binary packages in the distribution are generated
- from Debian sources, which are in a special format to assist
- the easy and automatic building of binaries.
- </p>
-
- <p>
- There was a previous version of the Debian source format,
- which is now being phased out. Instructions for converting an
- old-style package are given in the Debian policy manual.
- </p>
-
- <sect id="sourcetools">
- <heading>Tools for processing source packages</heading>
-
- <p>
- Various tools are provided for manipulating source packages;
- they pack and unpack sources and help build of binary
- packages and help manage the distribution of new versions.
- </p>
-
- <p>
- They are introduced and typical uses described here; see
- <manref name="dpkg-source" section="1"> for full
- documentation about their arguments and operation.
- </p>
-
- <p>
- For examples of how to construct a Debian source package,
- and how to use those utilities that are used by Debian
- source packages, please see the <prgn>hello</prgn> example
- package.
- </p>
-
- <sect1>
- <heading>
- <prgn>dpkg-source</prgn> - packs and unpacks Debian source
- packages
- </heading>
-
- <p>
- This program is frequently used by hand, and is also
- called from package-independent automated building scripts
- such as <prgn>dpkg-buildpackage</prgn>.
- </p>
-
- <p>
- To unpack a package it is typically invoked with
- <example>
- dpkg-source -x <var>.../path/to/filename</var>.dsc
- </example>
- </p>
-
- <p>
- with the <tt><var>filename</var>.tar.gz</tt> and
- <tt><var>filename</var>.diff.gz</tt> (if applicable) in
- the same directory. It unpacks into
- <tt><var>package</var>-<var>version</var></tt>, and if
- applicable
- <tt><var>package</var>-<var>version</var>.orig</tt>, in
- the current directory.
- </p>
-
- <p>
- To create a packed source archive it is typically invoked:
- <example>
- dpkg-source -b <var>package</var>-<var>version</var>
- </example>
- </p>
-
- <p>
- This will create the <tt>.dsc</tt>, <tt>.tar.gz</tt> and
- <tt>.diff.gz</tt> (if appropriate) in the current
- directory. <prgn>dpkg-source</prgn> does not clean the
- source tree first - this must be done separately if it is
- required.
- </p>
-
- <p>
- See also <ref id="sourcearchives">.</p>
- </sect1>
-
-
- <sect1>
- <heading>
- <prgn>dpkg-buildpackage</prgn> - overall package-building
- control script
- </heading>
-
- <p>
- <prgn>dpkg-buildpackage</prgn> is a script which invokes
- <prgn>dpkg-source</prgn>, the <tt>debian/rules</tt>
- targets <prgn>clean</prgn>, <prgn>build</prgn> and
- <prgn>binary</prgn>, <prgn>dpkg-genchanges</prgn> and
- <prgn>pgp</prgn> to build a signed source and binary
- package upload.
- </p>
-
- <p>
- It is usually invoked by hand from the top level of the
- built or unbuilt source directory. It may be invoked with
- no arguments; useful arguments include:
- <taglist compact="compact">
- <tag><tt>-uc</tt>, <tt>-us</tt></tag>
- <item>
- <p>
- Do not PGP-sign the <tt>.changes</tt> file or the
- source package <tt>.dsc</tt> file, respectively.</p>
- </item>
- <tag><tt>-p<var>pgp-command</var></tt></tag>
- <item>
- <p>
- Invoke <var>pgp-command</var> instead of finding
- <tt>pgp</tt> on the <prgn>PATH</prgn>.
- <var>pgp-command</var> must behave just like
- <prgn>pgp</prgn>.</p>
- </item>
- <tag><tt>-r<var>root-command</var></tt></tag>
- <item>
- <p>
- When root privilege is required, invoke the command
- <var>root-command</var>. <var>root-command</var>
- should invoke its first argument as a command, from
- the <prgn>PATH</prgn> if necessary, and pass its
- second and subsequent arguments to the command it
- calls. If no <var>root-command</var> is supplied
- then <var>dpkg-buildpackage</var> will take no
- special action to gain root privilege, so that for
- most packages it will have to be invoked as root to
- start with.</p>
- </item>
- <tag><tt>-b</tt>, <tt>-B</tt></tag>
- <item>
- <p>
- Two types of binary-only build and upload - see
- <manref name="dpkg-source" section="1">.
- </p>
- </item>
- </taglist>
- </p>
- </sect1>
-
- <sect1>
- <heading>
- <prgn>dpkg-gencontrol</prgn> - generates binary package
- control files
- </heading>
-
- <p>
- This program is usually called from <tt>debian/rules</tt>
- (see <ref id="sourcetree">) in the top level of the source
- tree.
- </p>
-
- <p>
- This is usually done just before the files and directories in the
- temporary directory tree where the package is being built have their
- permissions and ownerships set and the package is constructed using
- <prgn>dpkg-deb/</prgn>
- <footnote>
- <p>
- This is so that the control file which is produced has
- the right permissions
- </p>
- </footnote>.
- </p>
-
- <p>
- <prgn>dpkg-gencontrol</prgn> must be called after all the
- files which are to go into the package have been placed in
- the temporary build directory, so that its calculation of
- the installed size of a package is correct.
- </p>
-
- <p>
- It is also necessary for <prgn>dpkg-gencontrol</prgn> to
- be run after <prgn>dpkg-shlibdeps</prgn> so that the
- variable substitutions created by
- <prgn>dpkg-shlibdeps</prgn> in <tt>debian/substvars</tt>
- are available.
- </p>
-
- <p>
- For a package which generates only one binary package, and
- which builds it in <tt>debian/tmp</tt> relative to the top
- of the source package, it is usually sufficient to call
- <prgn>dpkg-gencontrol</prgn>.
- </p>
-
- <p>
- Sources which build several binaries will typically need
- something like:
- <example>
- dpkg-gencontrol -Pdebian/tmp-<var>pkg</var> -p<var>package</var>
- </example> The <tt>-P</tt> tells
- <prgn>dpkg-gencontrol</prgn> that the package is being
- built in a non-default directory, and the <tt>-p</tt>
- tells it which package's control file should be generated.
- </p>
-
- <p>
- <prgn>dpkg-gencontrol</prgn> also adds information to the
- list of files in <tt>debian/files</tt>, for the benefit of
- (for example) a future invocation of
- <prgn>dpkg-genchanges</prgn>.</p>
- </sect1>
-
- <sect1>
- <heading>
- <prgn>dpkg-shlibdeps</prgn> - calculates shared library
- dependencies
- </heading>
-
- <p>
- This program is usually called from <tt>debian/rules</tt>
- just before <prgn>dpkg-gencontrol</prgn> (see <ref
- id="sourcetree">), in the top level of the source tree.
- </p>
-
- <p>
- Its arguments are executables.
- <footnote>
- <p>
- In a forthcoming dpkg version,
- <prgn>dpkg-shlibdeps</prgn> would be required to be
- called on shared libraries as well.
- </p>
- <p>
- They may be specified either in the locations in the
- source tree where they are created or in the locations
- in the temporary build tree where they are installed
- prior to binary package creation.
- </p>
- </footnote> for which shared library dependencies should
- be included in the binary package's control file.
- </p>
-
- <p>
- If some of the found shared libraries should only
- warrant a <tt>Recommends</tt> or <tt>Suggests</tt>, or if
- some warrant a <tt>Pre-Depends</tt>, this can be achieved
- by using the <tt>-d<var>dependency-field</var></tt> option
- before those executable(s). (Each <tt>-d</tt> option
- takes effect until the next <tt>-d</tt>.)
- </p>
-
- <p>
- <prgn>dpkg-shlibdeps</prgn> does not directly cause the
- output control file to be modified. Instead by default it
- adds to the <tt>debian/substvars</tt> file variable
- settings like <tt>shlibs:Depends</tt>. These variable
- settings must be referenced in dependency fields in the
- appropriate per-binary-package sections of the source
- control file.
- </p>
-
- <p>
- For example, the <prgn>procps</prgn> package generates two
- kinds of binaries, simple C binaries like <prgn>ps</prgn>
- which require a predependency and full-screen ncurses
- binaries like <prgn>top</prgn> which require only a
- recommendation. It can say in its <tt>debian/rules</tt>:
- <example>
- dpkg-shlibdeps -dPre-Depends ps -dRecommends top
- </example>
- and then in its main control file <tt>debian/control</tt>:
- <example>
- <var>...</var>
- Package: procps
- Pre-Depends: ${shlibs:Pre-Depends}
- Recommends: ${shlibs:Recommends}
- <var>...</var>
- </example>
- </p>
-
- <p>
- Sources which produce several binary packages with
- different shared library dependency requirements can use
- the <tt>-p<var>varnameprefix</var></tt> option to override
- the default <tt>shlib:</tt> prefix (one invocation of
- <prgn>dpkg-shlibdeps</prgn> per setting of this option).
- They can thus produce several sets of dependency
- variables, each of the form
- <tt><var>varnameprefix</var>:<var>dependencyfield</var></tt>,
- which can be referred to in the appropriate parts of the
- binary package control files.
- </p>
- </sect1>
-
-
- <sect1>
- <heading>
- <prgn>dpkg-distaddfile</prgn> - adds a file to
- <tt>debian/files</tt>
- </heading>
-
- <p>
- Some packages' uploads need to include files other than
- the source and binary package files.
- </p>
-
- <p>
- <prgn>dpkg-distaddfile</prgn> adds a file to the
- <tt>debian/files</tt> file so that it will be included in
- the <tt>.changes</tt> file when
- <prgn>dpkg-genchanges</prgn> is run.
- </p>
-
- <p>
- It is usually invoked from the <prgn>binary</prgn> target of
- <tt>debian/rules</tt>:
- <example>
- dpkg-distaddfile <var>filename</var> <var>section</var> <var>priority</var>
- </example>
- The <var>filename</var> is relative to the directory where
- <prgn>dpkg-genchanges</prgn> will expect to find it - this
- is usually the directory above the top level of the source
- tree. The <tt>debian/rules</tt> target should put the
- file there just before or just after calling
- <prgn>dpkg-distaddfile</prgn>.
- </p>
-
- <p>
- The <var>section</var> and <var>priority</var> are passed
- unchanged into the resulting <tt>.changes</tt> file. See
- <ref id="f-classification">.
- </p>
- </sect1>
-
-
- <sect1><heading><prgn>dpkg-genchanges</prgn> - generates a <tt>.changes</tt> upload
- control file
- </heading>
-
- <p>
- This program is usually called by package-independent
- automatic building scripts such as
- <prgn>dpkg-buildpackage</prgn>, but it may also be called
- by hand.
- </p>
-
- <p>
- It is usually called in the top level of a built source
- tree, and when invoked with no arguments will print out a
- straightforward <tt>.changes</tt> file based on the
- information in the source package's changelog and control
- file and the binary and source packages which should have
- been built.
- </p>
- </sect1>
-
-
- <sect1><heading><prgn>dpkg-parsechangelog</prgn> - produces parsed representation of
- a changelog
- </heading>
-
- <p>
- This program is used internally by
- <prgn>dpkg-source</prgn> et al. It may also occasionally
- be useful in <tt>debian/rules</tt> and elsewhere. It
- parses a changelog, <tt>debian/changelog</tt> by default,
- and prints a control-file format representation of the
- information in it to standard output.
- </p>
- </sect1>
-
- <sect1 id="dpkgarch"><heading><prgn>dpkg-architecture</prgn> -
- information about the build and host system
- </heading>
-
- <p>
- This program can be used manually, but is also invoked by
- <tt>dpkg-buildpackage</tt> or <tt>debian/rules</tt> to set
- to set environment or make variables which specify the build and
- host architecture for the package building process.
- </p>
- </sect1>
- </sect>
-
- <sect id="sourcetree"><heading>The Debianised source tree
- </heading>
-
- <p>
- The source archive scheme described later is intended to
- allow a Debianised source tree with some associated control
- information to be reproduced and transported easily. The
- Debianised source tree is a version of the original program
- with certain files added for the benefit of the
- Debianisation process, and with any other changes required
- made to the rest of the source code and installation
- scripts.
- </p>
-
- <p>
- The extra files created for Debian are in the subdirectory
- <tt>debian</tt> of the top level of the Debianised source
- tree. They are described below.
- </p>
-
- <sect1 id="debianrules"><heading><tt>debian/rules</tt> - the main building
- script
- </heading>
-
- <p>
- This file is an executable makefile, and contains the
- package-specific recipies for compiling the package and
- building binary package(s) out of the source.
- </p>
-
- <p>
- It must start with the line <tt>#!/usr/bin/make -f</tt>,
- so that it can be invoked by saying its name rather than
- invoking <prgn>make</prgn> explicitly.
- </p>
-
- <p>
- Since an interactive <tt>debian/rules</tt> script makes it
- impossible to autocompile that package and also makes it
- hard for other people to reproduce the same binary
- package, all <strong>required targets</strong> have to be
- non-interactive. At a minimul, required targets are the
- ones called by <prgn>dpkg-buildpackage</prgn>, namely,
- <em>clean</em>, <em>binary</em>, <em>binary-arch</em>, and
- <em>build</em>. It also follows that any target that these
- targets depend on must also be non-interactive.
- </p>
-
- <p>
- The targets which are required to be present are:
- <taglist>
- <tag><tt>build</tt></tag>
- <item>
- <p>
- This should perform all non-interactive
- configuration and compilation of the package. If a
- package has an interactive pre-build configuration
- routine, the Debianised source package should be
- built after this has taken place, so that it can be
- built without rerunning the configuration.
- </p>
-
- <p>
- For some packages, notably ones where the same
- source tree is compiled in different ways to produce
- two binary packages, the <prgn>build</prgn> target
- does not make much sense. For these packages it is
- good enough to provide two (or more) targets
- (<tt>build-a</tt> and <tt>build-b</tt> or whatever)
- for each of the ways of building the package, and a
- <prgn>build</prgn> target that does nothing. The
- <prgn>binary</prgn> target will have to build the
- package in each of the possible ways and make the
- binary package out of each.
- </p>
-
- <p>
- The <prgn>build</prgn> target must not do anything
- that might require root privilege.
- </p>
-
- <p>
- The <prgn>build</prgn> target may need to run
- <prgn>clean</prgn> first - see below.
- </p>
-
- <p>
- When a package has a configuration routine that
- takes a long time, or when the makefiles are poorly
- designed, or when <prgn>build</prgn> needs to run
- <prgn>clean</prgn> first, it is a good idea to
- <tt>touch build</tt> when the build process is
- complete. This will ensure that if <tt>debian/rules
- build</tt> is run again it will not rebuild the
- whole program.
- </p>
- </item>
-
- <tag><tt>binary</tt>, <tt>binary-arch</tt>,
- <tt>binary-indep</tt>
- </tag>
- <item>
- <p>
- The <prgn>binary</prgn> target should be all that is
- necessary for the user to build the binary
- package. All these targets are required to be
- non-interactive. It is split into two parts:
- <prgn>binary-arch</prgn> builds the packages' output
- files which are specific to a particular
- architecture, and <prgn>binary-indep</prgn> builds
- those which are not.
- </p>
-
- <p>
- <prgn>binary</prgn> should usually be a target with
- no commands which simply depends on
- <prgn>binary-arch</prgn> and
- <prgn>binary-indep</prgn>.
- </p>
-
- <p>
- Both <prgn>binary-*</prgn> targets should depend on
- the <prgn>build</prgn> target, above, so that the
- package is built if it has not been already. It
- should then create the relevant binary package(s),
- using <prgn>dpkg-gencontrol</prgn> to make their
- control files and <prgn>dpkg-deb</prgn> to build
- them and place them in the parent of the top level
- directory.
- </p>
-
- <p>
- If one of the <prgn>binary-*</prgn> targets has
- nothing to do (this will be always be the case if
- the source generates only a single binary package,
- whether architecture-dependent or not) it
- <em>must</em> still exist, but should always
- succeed.
- </p>
-
- <p>
- <ref id="binarypkg"> describes how to construct
- binary packages.
- </p>
-
- <p>
- The <prgn>binary</prgn> targets must be invoked as
- root.
- </p>
- </item>
-
- <tag><tt>clean</tt></tag>
- <item>
-
- <p>
- This should undo any effects that the
- <prgn>build</prgn> and <prgn>binary</prgn> targets
- may have had, except that it should leave alone any
- output files created in the parent directory by a
- run of <prgn>binary</prgn>. This target is required
- to be non-interactive.
- </p>
-
- <p>
- If a <prgn>build</prgn> file is touched at the end
- of the <prgn>build</prgn> target, as suggested
- above, it must be removed as the first thing that
- <prgn>clean</prgn> does, so that running
- <prgn>build</prgn> again after an interrupted
- <prgn>clean</prgn> doesn't think that everything is
- already done.
- </p>
-
- <p>
- The <prgn>clean</prgn> target must be invoked as
- root if <prgn>binary</prgn> has been invoked since
- the last <prgn>clean</prgn>, or if
- <prgn>build</prgn> has been invoked as root (since
- <prgn>build</prgn> may create directories, for
- example).
- </p>
- </item>
-
- <tag><tt>get-orig-source</tt> (optional)</tag>
- <item>
-
- <p>
- This target fetches the most recent version of the
- original source package from a canonical archive
- site (via FTP or WWW, for example), does any
- necessary rearrangement to turn it into the original
- source tarfile format described below, and leaves it
- in the current directory.
- </p>
-
- <p>
- This target may be invoked in any directory, and
- should take care to clean up any temporary files it
- may have left.
- </p>
-
- <p>
- This target is optional, but providing it if
- possible is a good idea.
- </p>
- </item>
- </taglist>
-
- <p>
- The <prgn>build</prgn>, <prgn>binary</prgn> and
- <prgn>clean</prgn> targets must be invoked with a current
- directory of the package's top-level directory.
- </p>
-
-
- <p>
- Additional targets may exist in <tt>debian/rules</tt>,
- either as published or undocumented interfaces or for the
- package's internal use.
- </p>
-
- <p>
- The architecture we build on and build for is determined by make
- variables via dpkg-architecture (see <ref id="dpkgarch">). You can
- get the Debian architecture and the GNU style architecture
- specification string for the build machine as well as the host
- machine. Here is a list of supported make variables:
- <list compact="compact">
- <item>
- <p><tt>DEB_*_ARCH</tt> (the Debian architecture)</p>
- </item>
- <item>
- <p><tt>DEB_*_GNU_TYPE</tt> (the GNU style architecture
- specification string)</p>
- </item>
- <item>
- <p><tt>DEB_*_GNU_CPU</tt> (the CPU part of DEB_*_GNU_TYPE)</p>
- </item>
- <item>
- <p><tt>DEB_*_GNU_SYSTEM</tt> (the System part of
- DEB_*_GNU_TYPE)</p>
- </list>
- </p>
-
- <p>
- where <tt>*</tt> is either <tt>BUILD</tt> for specification of
- the build machine or <tt>HOST</tt> for specification of the machine
- we build for.
- </p>
-
- <p>
- Backward compatibility can be provided in the rules file
- by setting the needed variables to suitable default
- values, please refer to the documentation of
- dpkg-architecture for details.
- </p>
-
- <p>
- It is important to understand that the <tt>DEB_*_ARCH</tt>
- string does only determine which Debian architecture we
- build on resp. for. It should not be used to get the CPU
- or System information, the GNU style variables should be
- used for that.
- </p>
- </sect1>
-
-
- <sect1><heading><tt>debian/control</tt>
- </heading>
-
- <p>
- This file contains version-independent details about the
- source package and about the binary packages it creates.
- </p>
-
- <p>
- It is a series of sets of control fields, each
- syntactically similar to a binary package control file.
- The sets are separated by one or more blank lines. The
- first set is information about the source package in
- general; each subsequent set describes one binary package
- that the source tree builds.
- </p>
-
- <p>
- The syntax and semantics of the fields are described below
- in <ref id="controlfields">.
- </p>
-
- <p>
- The general (binary-package-independent) fields are:
- <list compact="compact">
- <item>
- <p><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</p>
- </item>
- <item>
- <p><qref id="f-Maintainer"><tt>Maintainer</tt></qref></p>
- </item>
- <item>
- <p>
- <qref id="f-classification"><tt>Section</tt> and
- <tt>Priority</tt></qref>
- (classification, mandatory)
- </p>
- </item>
- <item>
- <p>
- <qref id="relationships"><tt>Build-Depends</tt> et
- al.</qref> (source package interrelationships)
- </p>
- </item>
- <item>
- <p>
- <qref id="f-Standards-Version"><tt>Standards-Version</tt></qref>
- </p>
- </item>
- </list>
-
- <p>
- The per-binary-package fields are:
- <list compact="compact">
- <item>
- <p><qref id="f-Package"><tt>Package</tt></qref> (mandatory)</p>
- </item>
- <item>
- <p>
- <qref id="f-Architecture"><tt>Architecture</tt></qref>
- (mandatory)</p>
- </item>
- <item>
- <p><qref id="descriptions"><tt>Description</tt></qref></p>
- </item>
- <item>
- <p>
- <qref id="f-classification"><tt>Section</tt> and
- <tt>Priority</tt></qref> (classification)</p>
- </item>
- <item>
- <p><qref id="f-Essential"><tt>Essential</tt></qref></p>
- </item>
- <item>
- <p>
- <qref id="relationships"><tt>Depends</tt> et
- al.</qref> (binary package interrelationships)
- </p>
- </item>
- </list>
-
- <p>
- These fields are used by <prgn>dpkg-gencontrol</prgn> to
- generate control files for binary packages (see below), by
- <prgn>dpkg-genchanges</prgn> to generate the
- <tt>.changes</tt> file to accompany the upload, and by
- <prgn>dpkg-source</prgn> when it creates the <tt>.dsc</tt>
- source control file as part of a source archive.
- </p>
-
- <p>
- The fields here may contain variable references - their
- values will be substituted by
- <prgn>dpkg-gencontrol</prgn>, <prgn>dpkg-genchanges</prgn>
- or <prgn>dpkg-source</prgn> when they generate output
- control files. See <ref id="srcsubstvars"> for details.
- </p>
-
- <p> <sect2><heading>User-defined fields
- </heading>
-
- <p>
- Additional user-defined fields may be added to the
- source package control file. Such fields will be
- ignored, and not copied to (for example) binary or
- source package control files or upload control files.
- </p>
-
- <p>
- If you wish to add additional unsupported fields to
- these output files you should use the mechanism
- described here.
- </p>
-
- <p>
- Fields in the main source control information file with
- names starting <tt>X</tt>, followed by one or more of
- the letters <tt>BCS</tt> and a hyphen <tt>-</tt>, will
- be copied to the output files. Only the part of the
- field name after the hyphen will be used in the output
- file. Where the letter <tt>B</tt> is used the field
- will appear in binary package control files, where the
- letter <tt>S</tt> is used in source package control
- files and where <tt>C</tt> is used in upload control
- (<tt>.changes</tt>) files.
- </p>
-
- <p>
- For example, if the main source information control file
- contains the field
- <example>
- XBS-Comment: I stand between the candle and the star.
- </example>
- then the binary and source package control files will contain the
- field
- <example>
- Comment: I stand between the candle and the star.
- </example>
- </p>
- </sect2>
-
- </sect1>
-
- <sect1 id="dpkgchangelog"><heading><tt>debian/changelog</tt>
- </heading>
-
- <p>
- This file records the changes to the Debian-specific parts of the
- package
- <footnote>
- <p>
- Though there is nothing stopping an author who is also
- the Debian maintainer from using it for all their
- changes, it will have to be renamed if the Debian and
- upstream maintainers become different
- people.
- </p>
- </footnote>.
- </p>
-
- <p>
- It has a special format which allows the package building
- tools to discover which version of the package is being
- built and find out other release-specific information.
- </p>
-
- <p>
- That format is a series of entries like this:
- <example>
- <var>package</var> (<var>version</var>) <var>distribution(s)</var>; urgency=<var>urgency</var>
-
- * <var>change details</var>
- <var>more change details</var>
- * <var>even more change details</var>
-
- -- <var>maintainer name and email address</var> <var>date</var>
- </example>
- </p>
-
- <p>
- <var>package</var> and <var>version</var> are the source
- package name and version number.
- </p>
-
- <p>
- <var>distribution(s)</var> lists the distributions where
- this version should be installed when it is uploaded - it
- is copied to the <tt>Distribution</tt> field in the
- <tt>.changes</tt> file. See <ref id="f-Distribution">.
- </p>
-
- <p>
- <var>urgency</var> is the value for the <tt>Urgency</tt>
- field in the <tt>.changes</tt> file for the upload. See
- <ref id="f-Urgency">. It is not possible to specify an
- urgency containing commas; commas are used to separate
- <tt><var>keyword</var>=<var>value</var></tt> settings in
- the <prgn>dpkg</prgn> changelog format (though there is
- currently only one useful <var>keyword</var>,
- <tt>urgency</tt>).
- </p>
-
- <p>
- The change details may in fact be any series of lines
- starting with at least two spaces, but conventionally each
- change starts with an asterisk and a separating space and
- continuation lines are indented so as to bring them in
- line with the start of the text above. Blank lines may be
- used here to separate groups of changes, if desired.
- </p>
-
- <p>
- The maintainer name and email address should <em>not</em>
- necessarily be those of the usual package maintainer.
- They should be the details of the person doing
- <em>this</em> version. The information here will be
- copied to the <tt>.changes</tt> file, and then later used
- to send an acknowledgement when the upload has been
- installed.
- </p>
-
- <p>
- The <var>date</var> should be in RFC822 format
- <footnote>
- <p>
- This is generated by the <prgn>822-date</prgn>
- program.
- </p>
- </footnote>; it should include the timezone specified
- numerically, with the timezone name or abbreviation
- optionally present as a comment.
- </p>
-
- <p>
- The first `title' line with the package name should start
- at the left hand margin; the `trailer' line with the
- maintainer and date details should be preceded by exactly
- one space. The maintainer details and the date must be
- separated by exactly two spaces.
- </p>
-
- <p>
- An Emacs mode for editing this format is available: it is
- called <tt>debian-changelog-mode</tt>. You can have this
- mode selected automatically when you edit a Debian
- changelog by adding a local variables clause to the end of
- the changelog.
- </p>
-
- <sect2><heading>Defining alternative changelog formats
- </heading>
-
- <p>
- It is possible to use a different format to the standard
- one, by providing a parser for the format you wish to
- use.
- </p>
-
- <p>
- In order to have <tt>dpkg-parsechangelog</tt> run your
- parser, you must include a line within the last 40 lines
- of your file matching the Perl regular expression:
- <tt>\schangelog-format:\s+([0-9a-z]+)\W</tt> The part in
- parentheses should be the name of the format. For
- example, you might say:
- <example>
- @@@ changelog-format: joebloggs @@@
- </example>
- Changelog format names are non-empty strings of alphanumerics.
- </p>
-
- <p>
- If such a line exists then <tt>dpkg-parsechangelog</tt>
- will look for the parser as
- <tt>/usr/lib/dpkg/parsechangelog/<var>format-name</var></tt>
- or
- <tt>/usr/local/lib/dpkg/parsechangelog/<var>format-name</var></tt>;
- it is an error for it not to find it, or for it not to
- be an executable program. The default changelog format
- is <tt>dpkg</tt>, and a parser for it is provided with
- the <tt>dpkg</tt> package.
- </p>
-
- <p>
- The parser will be invoked with the changelog open on
- standard input at the start of the file. It should read
- the file (it may seek if it wishes) to determine the
- information required and return the parsed information
- to standard output in the form of a series of control
- fields in the standard format. By default it should
- return information about only the most recent version in
- the changelog; it should accept a
- <tt>-v<var>version</var></tt> option to return changes
- information from all versions present <em>strictly
- after</em> <var>version</var>, and it should then be an
- error for <var>version</var> not to be present in the
- changelog.
- </p>
-
- <p>
- The fields are:
- <list compact="compact">
- <item>
- <p><qref id="f-Source"><tt>Source</tt></qref></p>
- </item>
- <item>
- <p><qref id="versions"><tt>Version</tt></qref> (mandatory)</p>
- </item>
- <item>
- <p>
- <qref id="f-Distribution"><tt>Distribution</tt></qref>
- (mandatory)
- </p>
- </item>
- <item>
- <p><qref id="f-Urgency"><tt>Urgency</tt></qref> (mandatory)</p>
- </item>
- <item>
- <p>
- <qref id="f-Maintainer"><tt>Maintainer</tt></qref>
- (mandatory)
- </p>
- </item>
- <item>
- <p><qref id="f-Date"><tt>Date</tt></qref></p>
- </item>
- <item>
- <p>
- <qref id="f-Changes"><tt>Changes</tt></qref>
- (mandatory)
- </p>
- </item>
- </list>
-
- <p>
- If several versions are being returned (due to the use
- of <tt>-v</tt>), the urgency value should be of the
- highest urgency code listed at the start of any of the
- versions requested followed by the concatenated
- (space-separated) comments from all the versions
- requested; the maintainer, version, distribution and
- date should always be from the most recent version.
- </p>
-
- <p>
- For the format of the <tt>Changes</tt> field see <ref
- id="f-Changes">.
- </p>
-
- <p>
- If the changelog format which is being parsed always or
- almost always leaves a blank line between individual
- change notes these blank lines should be stripped out,
- so as to make the resulting output compact.
- </p>
-
- <p>
- If the changelog format does not contain date or package
- name information this information should be omitted from
- the output. The parser should not attempt to synthesise
- it or find it from other sources.
- </p>
-
- <p>
- If the changelog does not have the expected format the
- parser should exit with a nonzero exit status, rather
- than trying to muddle through and possibly generating
- incorrect output.
- </p>
-
- <p>
- A changelog parser may not interact with the user at
- all.</p></sect2>
- </sect1>
-
- <sect1 id="srcsubstvars"><heading><tt>debian/substvars</tt>
- and variable substitutions
- </heading>
-
- <p>
- When <prgn>dpkg-gencontrol</prgn>,
- <prgn>dpkg-genchanges</prgn> and <prgn>dpkg-source</prgn>
- generate control files they do variable substitutions on
- their output just before writing it. Variable
- substitutions have the form
- <tt>${<var>variable-name</var>}</tt>. The optional file
- <tt>debian/substvars</tt> contains variable substitutions
- to be used; variables can also be set directly from
- <tt>debian/rules</tt> using the <tt>-V</tt> option to the
- source packaging commands, and certain predefined
- variables are available.
- </p>
-
- <p>
- The is usually generated and modified dynamically by
- <tt>debian/rules</tt> targets; in this case it must be
- removed by the <prgn>clean</prgn> target.
- </p>
-
- <p>
- See <manref name="dpkg-source" section="1"> for full
- details about source variable substitutions, including the
- format of <tt>debian/substvars</tt>.</p>
- </sect1>
-
- <sect1><heading><tt>debian/files</tt>
- </heading>
-
- <p>
- This file is not a permanent part of the source tree; it
- is used while building packages to record which files are
- being generated. <prgn>dpkg-genchanges</prgn> uses it
- when it generates a <tt>.changes</tt> file.
- </p>
-
- <p>
- It should not exist in a shipped source package, and so it
- (and any backup files or temporary files such as
- <tt>files.new</tt>
- <footnote>
- <p>
- <tt>files.new</tt> is used as a temporary file by
- <prgn>dpkg-gencontrol</prgn> and
- <prgn>dpkg-distaddfile</prgn> - they write a new
- version of <tt>files</tt> here before renaming it,
- to avoid leaving a corrupted copy if an error
- occurs
- </p>
- </footnote>) should be removed by the
- <prgn>clean</prgn> target. It may also be wise to
- ensure a fresh start by emptying or removing it at the
- start of the <prgn>binary</prgn> target.
- </p>
-
- <p>
- <prgn>dpkg-gencontrol</prgn> adds an entry to this file
- for the <tt>.deb</tt> file that will be created by
- <prgn>dpkg-deb</prgn> from the control file that it
- generates, so for most packages all that needs to be done
- with this file is to delete it in <prgn>clean</prgn>.
- </p>
-
- <p>
- If a package upload includes files besides the source
- package and any binary packages whose control files were
- made with <prgn>dpkg-gencontrol</prgn> then they should be
- placed in the parent of the package's top-level directory
- and <prgn>dpkg-distaddfile</prgn> should be called to add
- the file to the list in <tt>debian/files</tt>.</p>
- </sect1>
-
- <sect1><heading><tt>debian/tmp</tt>
- </heading>
-
- <p>
- This is the canonical temporary location for the
- construction of binary packages by the <prgn>binary</prgn>
- target. The directory <tt>tmp</tt> serves as the root of
- the filesystem tree as it is being constructed (for
- example, by using the package's upstream makefiles install
- targets and redirecting the output there), and it also
- contains the <tt>DEBIAN</tt> subdirectory. See <ref
- id="bincreating">.
- </p>
-
- <p>
- If several binary packages are generated from the same
- source tree it is usual to use several
- <tt>debian/tmp<var>something</var></tt> directories, for
- example <tt>tmp-a</tt> or <tt>tmp-doc</tt>.
- </p>
-
- <p>
- Whatever <tt>tmp</tt> directories are created and used by
- <prgn>binary</prgn> must of course be removed by the
- <prgn>clean</prgn> target.</p></sect1>
- </sect>
-
-
- <sect id="sourcearchives"><heading>Source packages as archives
- </heading>
-
- <p>
- As it exists on the FTP site, a Debian source package
- consists of three related files. You must have the right
- versions of all three to be able to use them.
- </p>
-
- <p>
- <taglist>
- <tag>Debian source control file - <tt>.dsc</tt></tag>
- <item>
-
- <p>
- This file contains a series of fields, identified and
- separated just like the fields in the control file of
- a binary package. The fields are listed below; their
- syntax is described above, in <ref id="controlfields">.
- <list compact="compact">
- <item>
- <p><qref id="f-Source"><tt>Source</tt></qref></p>
- </item>
- <item>
- <p><qref id="versions"><tt>Version</tt></qref></p>
- </item>
- <item>
- <p><qref id="f-Maintainer"><tt>Maintainer</tt></qref></p>
- </item>
- <item>
- <p><qref id="f-Binary"><tt>Binary</tt></qref></p>
- </item>
- <item>
- <p><qref id="f-Architecture"><tt>Architecture</tt></qref></p>
- </item>
- <item>
- <p>
- <qref id="relationships"><tt>Build-Depends</tt> et
- al.</qref> (source package interrelationships)
- </p>
- </item>
- <item>
- <p>
- <qref id="f-Standards-Version"><tt>Standards-Version</tt></qref></p>
- </item>
- <item>
- <p><qref id="f-Files"><tt>Files</tt></qref></p>
- </item>
- </list>
-
- <p>
- The source package control file is generated by
- <prgn>dpkg-source</prgn> when it builds the source
- archive, from other files in the source package,
- described above. When unpacking it is checked against
- the files and directories in the other parts of the
- source package, as described below.</p>
- </item>
-
- <tag>
- Original source archive -
- <tt>
- <var>package</var>_<var>upstream-version</var>.orig.tar.gz
- </tt>
- </tag>
-
- <item>
-
- <p>
- This is a compressed (with <tt>gzip -9</tt>)
- <prgn>tar</prgn> file containing the source code from
- the upstream authors of the program. The tarfile
- unpacks into a directory
- <tt><var>package</var>-<var>upstream-version</var>.orig</tt>,
- and does not contain files anywhere other than in
- there or in its subdirectories.</p>
- </item>
-
- <tag>
- Debianisation diff -
- <tt>
- <var>package</var>_<var>upstream_version-revision</var>.diff.gz
- </tt>
- </tag>
- <item>
-
- <p>
- This is a unified context diff (<tt>diff -u</tt>)
- giving the changes which are required to turn the
- original source into the Debian source. These changes
- may only include editing and creating plain files.
- The permissions of files, the targets of symbolic
- links and the characteristics of special files or
- pipes may not be changed and no files may be removed
- or renamed.
- </p>
-
- <p>
- All the directories in the diff must exist, except the
- <tt>debian</tt> subdirectory of the top of the source
- tree, which will be created by
- <prgn>dpkg-source</prgn> if necessary when unpacking.
- </p>
-
- <p>
- The <prgn>dpkg-source</prgn> program will
- automatically make the <tt>debian/rules</tt> file
- executable (see below).</p></item>
- </taglist>
-
-
- <p>
- If there is no original source code - for example, if the
- package is specially prepared for Debian or the Debian
- maintainer is the same as the upstream maintainer - the
- format is slightly different: then there is no diff, and the
- tarfile is named
- <tt><var>package</var>_<var>version</var>.tar.gz</tt> and
- contains a directory
- <tt><var>package</var>-<var>version</var></tt>.
- </p>
- </sect>
-
- <sect><heading>Unpacking a Debian source package without
- <prgn>dpkg-source</prgn>
- </heading>
-
- <p>
- <tt>dpkg-source -x</tt> is the recommended way to unpack a
- Debian source package. However, if it is not available it
- is possible to unpack a Debian source archive as follows:
- <enumlist compact="compact">
- <item>
- <p>
- Untar the tarfile, which will create a <tt>.orig</tt>
- directory.</p>
- </item>
- <item>
- <p>Rename the <tt>.orig</tt> directory to
- <tt><var>package</var>-<var>version</var></tt>.</p>
- </item>
- <item>
- <p>
- Create the subdirectory <tt>debian</tt> at the top of
- the source tree.</p>
- </item>
- <item><p>Apply the diff using <tt>patch -p0</tt>.</p>
- </item>
- <item><p>Untar the tarfile again if you want a copy of the original
- source code alongside the Debianised version.</p>
- </item>
- </enumlist>
-
- <p>
- It is not possible to generate a valid Debian source archive
- without using <prgn>dpkg-source</prgn>. In particular,
- attempting to use <prgn>diff</prgn> directly to generate the
- <tt>.diff.gz</tt> file will not work.
- </p>
-
- <sect1><heading>Restrictions on objects in source packages
- </heading>
-
- <p>
- The source package may not contain any hard links
- <footnote>
- <p>
- This is not currently detected when building source
- packages, but only when extracting
- them.
- </p>
- </footnote>
- <footnote>
- <p>
- Hard links may be permitted at some point in the
- future, but would require a fair amount of
- work.
- </p>
- </footnote>, device special files, sockets or setuid or
- setgid files.
- <footnote>
- <p>
- Setgid directories are allowed.
- </p>
- </footnote>
- </p>
-
- <p>
- The source packaging tools manage the changes between the
- original and Debianised source using <prgn>diff</prgn> and
- <prgn>patch</prgn>. Turning the original source tree as
- included in the <tt>.orig.tar.gz</tt> into the debianised
- source must not involve any changes which cannot be
- handled by these tools. Problematic changes which cause
- <prgn>dpkg-source</prgn> to halt with an error when
- building the source package are:
- <list compact="compact">
- <item><p>Adding or removing symbolic links, sockets or pipes.</p>
- </item>
- <item><p>Changing the targets of symbolic links.</p>
- </item>
- <item><p>Creating directories, other than <tt>debian</tt>.</p>
- </item>
- <item><p>Changes to the contents of binary files.</p></item>
- </list> Changes which cause <prgn>dpkg-source</prgn> to
- print a warning but continue anyway are:
- <list compact="compact">
- <item>
- <p>
- Removing files, directories or symlinks.
- <footnote>
- <p>
- Renaming a file is not treated specially - it is
- seen as the removal of the old file (which
- generates a warning, but is otherwise ignored),
- and the creation of the new
- one.</p>
- </footnote>
- </p>
- </item>
- <item>
- <p>
- Changed text files which are missing the usual final
- newline (either in the original or the modified
- source tree).
- </p>
- </item>
- </list>
- Changes which are not represented, but which are not detected by
- <prgn>dpkg-source</prgn>, are:
- <list compact="compact">
- <item><p>Changing the permissions of files (other than
- <tt>debian/rules</tt>) and directories.</p></item>
- </list>
- </p>
-
- <p>
- The <tt>debian</tt> directory and <tt>debian/rules</tt>
- are handled specially by <prgn>dpkg-source</prgn> - before
- applying the changes it will create the <tt>debian</tt>
- directory, and afterwards it will make
- <tt>debian/rules</tt> world-exectuable.
- </p>
- </sect1>
- </sect>
- </chapt>
-
- <chapt id="controlfields"><heading>Control files and their fields
- </heading>
-
- <p>
- Many of the tools in the <prgn>dpkg</prgn> suite manipulate
- data in a common format, known as control files. Binary and
- source packages have control data as do the <tt>.changes</tt>
- files which control the installation of uploaded files, and
- <prgn>dpkg</prgn>'s internal databases are in a similar
- format.
- </p>
-
- <sect><heading>Syntax of control files
- </heading>
-
- <p>
- A file consists of one or more paragraphs of fields. The
- paragraphs are separated by blank lines. Some control files
- only allow one paragraph; others allow several, in which
- case each paragraph often refers to a different package.
- </p>
-
- <p>
- Each paragraph is a series of fields and values; each field
- consists of a name, followed by a colon and the value. It
- ends at the end of the line. Horizontal whitespace (spaces
- and tabs) may occur before or after the value and is ignored
- there; it is conventional to put a single space after the
- colon.
- </p>
-
- <p>
- Some fields' values may span several lines; in this case
- each continuation line <em>must</em> start with a space or
- tab. Any trailing spaces or tabs at the end of individual
- lines of a field value are ignored.
- </p>
-
- <p>
- Except where otherwise stated only a single line of data is
- allowed and whitespace is not significant in a field body.
- Whitespace may never appear inside names (of packages,
- architectures, files or anything else), version numbers or
- in between the characters of multi-character version
- relationships.
- </p>
-
- <p>
- Field names are not case-sensitive, but it is usual to
- capitalise the field names using mixed case as shown below.
- </p>
-
- <p>
- Blank lines, or lines consisting only of spaces and tabs,
- are not allowed within field values or between fields - that
- would mean a new paragraph.
- </p>
-
- <p>
- It is important to note that there are several fields which
- are optional as far as <prgn>dpkg</prgn> and the related
- tools are concerned, but which must appear in every Debian
- package, or whose omission may cause problems. When writing
- the control files for Debian packages you <em>must</em> read
- the Debian policy manual in conjuction with the details
- below and the list of fields for the particular file.</p>
- </sect>
-
- <sect><heading>List of fields
- </heading>
-
- <sect1 id="f-Package"><heading><tt>Package</tt>
- </heading>
-
- <p>
- The name of the binary package. Package names consist of
- the alphanumerics and <tt>+</tt> <tt>-</tt> <tt>.</tt>
- (plus, minus and full stop).
- <footnote>
- <p>
- The characters <tt>@</tt> <tt>:</tt> <tt>=</tt>
- <tt>%</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
- </p>
- </footnote>
- </p>
-
- <p>
- They must be at least two characters and must start with
- an alphanumeric. In current versions of dpkg they are
- sort of case-sensitive<footnote><p>This is a
- bug.</p></footnote>; use lowercase package names unless
- the package you're building (or referring to, in other
- fields) is already using uppercase.</p>
- </sect1>
-
- <sect1 id="f-Version"><heading><tt>Version</tt>
- </heading>
-
- <p>
- This lists the source or binary package's version number -
- see <ref id="versions">.
- </p>
-
- </sect1>
-
- <sect1 id="f-Architecture"><heading><tt>Architecture</tt>
- </heading>
-
- <p>
- This is the architecture string; it is a single word for
- the Debian architecture.
- </p>
-
- <p>
- <prgn>dpkg</prgn> will check the declared architecture of
- a binary package against its own compiled-in value before
- it installs it.
- </p>
-
- <p>
- The special value <tt>all</tt> indicates that the package
- is architecture-independent.
- </p>
-
- <p>
- In the main <tt>debian/control</tt> file in the source
- package, or in the source package control file
- <tt>.dsc</tt>, a list of architectures (separated by
- spaces) is also allowed, as is the special value
- <tt>any</tt>. A list indicates that the source will build
- an architecture-dependent package, and will only work
- correctly on the listed architectures. <tt>any</tt>
- indicates that though the source package isn't dependent
- on any particular architecture and should compile fine on
- any one, the binary package(s) produced are not
- architecture-independent but will instead be specific to
- whatever the current build architecture is.
- </p>
-
- <p>
- In a <tt>.changes</tt> file the <tt>Architecture</tt>
- field lists the architecture(s) of the package(s)
- currently being uploaded. This will be a list; if the
- source for the package is being uploaded too the special
- entry <tt>source</tt> is also present.
- </p>
-
- <p>
- See <ref id="debianrules"> for information how to get the
- architecture for the build process.
- </p>
- </sect1>
-
- <sect1 id="f-Maintainer"><heading><tt>Maintainer</tt>
- </heading>
-
- <p>
- The package maintainer's name and email address. The name
- should come first, then the email address inside angle
- brackets <tt><></tt> (in RFC822 format).
- </p>
-
- <p>
- If the maintainer's name contains a full stop then the
- whole field will not work directly as an email address due
- to a misfeature in the syntax specified in RFC822; a
- program using this field as an address must check for this
- and correct the problem if necessary (for example by
- putting the name in round brackets and moving it to the
- end, and bringing the email address forward).
- </p>
-
- <p>
- In a <tt>.changes</tt> file or parsed changelog data this
- contains the name and email address of the person
- responsible for the particular version in question - this
- may not be the package's usual maintainer.
- </p>
-
- <p>
- This field is usually optional in as far as the
- <prgn>dpkg</prgn> are concerned, but its absence when
- building packages usually generates a warning.</p>
- </sect1>
-
- <sect1 id="f-Source"><heading><tt>Source</tt>
- </heading>
-
- <p>
- This field identifies the source package name.
- </p>
-
- <p>
- In a main source control information or a
- <tt>.changes</tt> or <tt>.dsc</tt> file or parsed
- changelog data this may contain only the name of the
- source package.
- </p>
-
- <p>
- In the control file of a binary package (or in a
- <tt>Packages</tt> file) it may be followed by a version
- number in parentheses.
- <footnote>
- <p>
- It is usual to leave a space after the package name if
- a version number is specified.
- </p>
- </footnote> This version number may be omitted (and is, by
- <prgn>dpkg-gencontrol</prgn>) if it has the same value as
- the <tt>Version</tt> field of the binary package in
- question. The field itself may be omitted from a binary
- package control file when the source package has the same
- name and version as the binary package.
- </p>
- </sect1>
-
- <sect1><heading>Package interrelationship fields:
- <tt>Depends</tt>, <tt>Pre-Depends</tt>,
- <tt>Recommends</tt> <tt>Suggests</tt>, <tt>Conflicts</tt>,
- <tt>Provides</tt>, <tt>Replaces</tt>
- </heading>
-
- <p>
- These fields describe the package's relationships with
- other packages. Their syntax and semantics are described
- in <ref id="relationships">.</p>
- </sect1>
-
- <sect1 id="f-Description"><heading><tt>Description</tt>
- </heading>
-
- <p>
- In a binary package <tt>Packages</tt> file or main source
- control file this field contains a description of the
- binary package, in a special format. See <ref
- id="descriptions"> for details.
- </p>
-
- <p>
- In a <tt>.changes</tt> file it contains a summary of the
- descriptions for the packages being uploaded. The part of
- the field before the first newline is empty; thereafter
- each line has the name of a binary package and the summary
- description line from that binary package. Each line is
- indented by one space.</p>
- </sect1>
-
- <sect1 id="f-Essential"><heading><tt>Essential</tt>
- </heading>
-
- <p>
- This is a boolean field which may occur only in the
- control file of a binary package (or in the
- <tt>Packages</tt> file) or in a per-package fields
- paragraph of a main source control data file.
- </p>
-
- <p>
- If set to <tt>yes</tt> then <prgn>dpkg</prgn> and
- <prgn>dselect</prgn> will refuse to remove the package
- (though it can be upgraded and/or replaced). The other
- possible value is <tt>no</tt>, which is the same as not
- having the field at all.</p>
- </sect1>
-
- <sect1 id="f-classification"><heading><tt>Section</tt> and
- <tt>Priority</tt>
- </heading>
-
- <p>
- These two fields classify the package. The
- <tt>Priority</tt> represents how important that it is that
- the user have it installed; the <tt>Section</tt>
- represents an application area into which the package has
- been classified.
- </p>
-
- <p>
- When they appear in the <tt>debian/control</tt> file these
- fields give values for the section and priority subfields
- of the <tt>Files</tt> field of the <tt>.changes</tt> file,
- and give defaults for the section and priority of the
- binary packages.
- </p>
-
- <p>
- The section and priority are represented, though not as
- separate fields, in the information for each file in the
- <qref id="f-Files"><tt>-File</tt></qref>field of a
- <tt>.changes</tt> file. The section value in a
- <tt>.changes</tt> file is used to decide where to install
- a package in the FTP archive.
- </p>
-
- <p>
- These fields are not used by by <prgn>dpkg</prgn> proper,
- but by <prgn>dselect</prgn> when it sorts packages and
- selects defaults. See the Debian policy manual for the
- priorities in use and the criteria for selecting the
- priority for a Debian package, and look at the Debian FTP
- archive for a list of currently in-use priorities.
- </p>
-
- <p>
- These fields may appear in binary package control files,
- in which case they provide a default value in case the
- <tt>Packages</tt> files are missing the information.
- <prgn>dpkg</prgn> and <prgn>dselect</prgn> will only use
- the value from a <tt>.deb</tt> file if they have no other
- information; a value listed in a <tt>Packages</tt> file
- will always take precedence. By default
- <prgn>dpkg-gencontrol</prgn> does not include the section
- and priority in the control file of a binary package - use
- the <tt>-isp</tt>, <tt>-is</tt> or <tt>-ip</tt> options to
- achieve this effect.</p>
- </sect1>
-
- <sect1 id="f-Binary"><heading><tt>Binary</tt>
- </heading>
-
- <p>
- This field is a list of binary packages.
- </p>
-
- <p>
- When it appears in the <tt>.dsc</tt> file it is the list
- of binary packages which a source package can produce. It
- does not necessarily produce all of these binary packages
- for every architecture. The source control file doesn't
- contain details of which architectures are appropriate for
- which of the binary packages.
- </p>
-
- <p>
- When it appears in a <tt>.changes</tt> file it lists the
- names of the binary packages actually being uploaded.
- </p>
-
- <p>
- The syntax is a list of binary packages separated by
- commas.
- <footnote>
- <p>
- A space after each comma is conventional.
- </p>
- </footnote> Currently the packages must be separated using
- only spaces in the <tt>.changes</tt> file.</p>
- </sect1>
-
- <sect1 id="f-Installed-Size"><heading><tt>Installed-Size</tt>
- </heading>
-
- <p>
- This field appears in the control files of binary
- packages, and in the <tt>Packages</tt> files. It gives
- the total amount of disk space required to install the
- named package.
- </p>
-
- <p>
- The disk space is represented in kilobytes as a simple
- decimal number.</p>
- </sect1>
-
- <sect1 id="f-Files"><heading><tt>Files</tt>
- </heading>
-
- <p>
- This field contains a list of files with information about
- each one. The exact information and syntax varies with
- the context. In all cases the the part of the field
- contents on the same line as the field name is empty. The
- remainder of the field is one line per file, each line
- being indented by one space and containing a number of
- sub-fields separated by spaces.
- </p>
-
- <p>
- In the <tt>.dsc</tt> (Debian source control) file each
- line contains the MD5 checksum, size and filename of the
- tarfile and (if applicable) diff file which make up the
- remainder of the source package.
- <footnote>
- <p>
- That is, the parts which are not the
- <tt>.dsc</tt>.
- </p>
- </footnote> The exact forms of the filenames are described
- in <ref id="sourcearchives">.
- </p>
-
- <p>
- In the <tt>.changes</tt> file this contains one line per
- file being uploaded. Each line contains the MD5 checksum,
- size, section and priority and the filename. The section
- and priority are the values of the corresponding fields in
- the main source control file - see <ref
- id="f-classification">. If no section or priority is
- specified then <tt>-</tt> should be used, though section
- and priority values must be specified for new packages to
- be installed properly.
- </p>
-
- <p>
- The special value <tt>byhand</tt> for the section in a
- <tt>.changes</tt> file indicates that the file in question
- is not an ordinary package file and must by installed by
- hand by the distribution maintainers. If the section is
- <tt>byhand</tt> the priority should be <tt>-</tt>.
- </p>
-
- <p>
- If a new Debian revision of a package is being shipped and
- no new original source archive is being distributed the
- <tt>.dsc</tt> must still contain the <tt>Files</tt> field
- entry for the original source archive
- <tt><var>package</var>-<var>upstream-version</var>.orig.tar.gz</tt>,
- but the <tt>.changes</tt> file should leave it out. In
- this case the original source archive on the distribution
- site must match exactly, byte-for-byte, the original
- source archive which was used to generate the
- <tt>.dsc</tt> file and diff which are being uploaded.</p>
- </sect1>
-
-
- <sect1
- id="f-Standards-Version"><heading><tt>Standards-Version</tt>
- </heading>
-
- <p>
- The most recent version of the standards (the
- <prgn>dpkg</prgn> programmers' and policy manuals and
- associated texts) with which the package complies. This
- is updated manually when editing the source package to
- conform to newer standards; it can sometimes be used to
- tell when a package needs attention.
- </p>
-
- <p>
- Its format is the same as that of a version number except
- that no epoch or Debian revision is allowed - see <ref
- id="versions">.</p>
- </sect1>
-
-
- <sect1 id="f-Distribution"><heading><tt>Distribution</tt>
- </heading>
-
- <p>
- In a <tt>.changes</tt> file or parsed changelog output
- this contains the (space-separated) name(s) of the
- distribution(s) where this version of the package should
- be or was installed. Distribution names follow the rules
- for package names. (See <ref id="f-Package">).
- </p>
-
- <p>
- Current distribution values are:
- <taglist>
- <tag><em>stable</em></tag>
- <item>
- <p>
- This is the current `released' version of Debian
- GNU/Linux. A new version is released approximately
- every 3 months after the <em>development</em> code has
- been <em>frozen</em> for a month of testing. Once the
- distribution is <em>stable</em> only major bug fixes
- are allowed. When changes are made to this
- distribution, the release number is increased
- (for example: 1.2r1 becomes 1.2r2 then 1.2r3, etc).
- </p>
- </item>
-
- <tag><em>unstable</em></tag>
- <item>
- <p>
- This distribution value refers to the
- <em>developmental</em> part of the Debian distribution
- tree. New packages, new upstream versions of packages
- and bug fixes go into the <em>unstable</em> directory
- tree. Download from this distribution at your own
- risk.</p>
- </item>
-
- <tag><em>contrib</em></tag>
- <item>
- <p>
- The packages with this distribution value do not meet
- the criteria for inclusion in the main Debian
- distribution as defined by the Policy Manual, but meet
- the criteria for the <em>contrib</em>
- Distribution. There is currently no distinction
- between stable and unstable packages in the
- <em>contrib</em> or <em>non-free</em>
- distributions. Use your best judgement in downloading
- from this Distribution.</p>
- </item>
-
- <tag><em>non-free</em></tag>
- <item>
- <p>
- Like the packages in the <em>contrib</em> seciton,
- the packages in <em>non-free</em> do not meet the
- criteria for inclusion in the main Debian distribution
- as defined by the Policy Manual. Again, use your best
- judgement in downloading from this Distribution.</p>
-
- <tag><em>experimental</em></tag>
- <item>
- <p>
- The packages with this distribution value are deemed
- by their maintainers to be high risk. Oftentimes they
- represent early beta or developmental packages from
- various sources that the maintainers want people to
- try, but are not ready to be a part of the other parts
- of the Debian distribution tree. Download at your own
- risk.</p>
- </item>
-
- <tag><em>frozen</em></tag>
- <item>
- <p>
- From time to time, (currently, every 3 months) the
- <em>unstable</em> distribution enters a state of
- `code-freeze' in anticipation of release as a
- <em>stable</em> version. During this period of testing
- (usually 4 weeks) only fixes for existing or
- newly-discovered bugs will be allowed.
- </p>
- </item>
- </taglist> You should list <em>all</em> distributions that
- the package should be installed into. Except in unusual
- circumstances, installations to <em>stable</em> should also
- go into <em>frozen</em> (if it exists) and
- <em>unstable</em>. Likewise, installations into
- <em>frozen</em> should also go into <em>unstable</em>.</p>
- </sect1>
-
- <sect1 id="f-Urgency"><heading><tt>Urgency</tt>
- </heading>
-
- <p>
- This is a description of how important it is to upgrade to
- this version from previous ones. It consists of a single
- keyword usually taking one of the values <tt>LOW</tt>,
- <tt>MEDIUM</tt> or <tt>HIGH</tt>) followed by an optional
- commentary (separated by a space) which is usually in
- parentheses. For example:
- <example>
- Urgency: LOW (HIGH for diversions users)
- </example>
- </p>
-
- <p>
- This field appears in the <tt>.changes</tt> file and in
- parsed changelogs; its value appears as the value of the
- <tt>urgency</tt> attribute in a <prgn>dpkg</prgn>-style
- changelog (see <ref id="dpkgchangelog">).
- </p>
-
- <p>
- Urgency keywords are not case-sensitive.</p>
- </sect1>
-
- <sect1 id="f-Date"><heading><tt>Date</tt>
- </heading>
-
- <p>
- In <tt>.changes</tt> files and parsed changelogs, this
- gives the date the package was built or last edited.</p>
- </sect1>
-
- <sect1 id="f-Format"><heading><tt>Format</tt>
- </heading>
-
- <p>
- This field occurs in <tt>.changes</tt> files, and
- specifies a format revision for the file. The format
- described here is version <tt>1.5</tt>. The syntax of the
- format value is the same as that of a package version
- number except that no epoch or Debian revision is allowed
- - see <ref id="versions">.</p>
- </sect1>
-
- <sect1 id="f-Changes"><heading><tt>Changes</tt>
- </heading>
-
- <p>
- In a <tt>.changes</tt> file or parsed changelog this field
- contains the human-readable changes data, describing the
- differences between the last version and the current one.
- </p>
-
- <p>
- There should be nothing in this field before the first
- newline; all the subsequent lines must be indented by at
- least one space; blank lines must be represented by a line
- consiting only of a space and a full stop.
- </p>
-
- <p>
- Each version's change information should be preceded by a
- `title' line giving at least the version, distribution(s)
- and urgency, in a human-readable way.
- </p>
-
- <p>
- If data from several versions is being returned the entry
- for the most recent version should be returned first, and
- entries should be separated by the representation of a
- blank line (the `title' line may also be followed by the
- representation of blank line).</p>
- </sect1>
-
- <sect1 id="f-Filename"><heading><tt>Filename</tt> and
- <tt>MSDOS-Filename</tt>
- </heading>
-
- <p>
- These fields in <tt>Packages</tt> files give the
- filename(s) of (the parts of) a package in the
- distribution directories, relative to the root of the
- Debian hierarchy. If the package has been split into
- several parts the parts are all listed in order, separated
- by spaces.</p>
- </sect1>
-
- <sect1 id="f-Size"><heading><tt>Size</tt> and <tt>MD5sum</tt>
- </heading>
-
- <p>
- These fields in <tt>Packages</tt> files give the size (in
- bytes, expressed in decimal) and MD5 checksum of the
- file(s) which make(s) up a binary package in the
- distribution. If the package is split into several parts
- the values for the parts are listed in order, separated by
- spaces.</p>
- </sect1>
-
- <sect1 id="f-Status"><heading><tt>Status</tt>
- </heading>
-
- <p>
- This field in <prgn>dpkg</prgn>'s status file records
- whether the user wants a package installed, removed or
- left alone, whether it is broken (requiring
- reinstallation) or not and what its current state on the
- system is. Each of these pieces of information is a
- single word.</p>
- </sect1>
-
- <sect1 id="f-Config-Version"><heading><tt>Config-Version</tt>
- </heading>
-
- <p>
- If a package is not installed or not configured, this
- field in <prgn>dpkg</prgn>'s status file records the last
- version of the package which was successfully
- configured.</p>
- </sect1>
-
- <sect1 id="f-Conffiles"><heading><tt>Conffiles</tt>
- </heading>
-
- <p>
- This field in <prgn>dpkg</prgn>'s status file contains
- information about the automatically-managed configuration
- files held by a package. This field should <em>not</em>
- appear anywhere in a package!</p>
- </sect1>
-
- <sect1><heading>Obsolete fields
- </heading>
-
- <p>
- These are still recognised by <prgn>dpkg</prgn> but should
- not appear anywhere any more.
- <taglist compact="compact">
-
- <tag><tt>Revision</tt></tag>
- <tag><tt>Package-Revision</tt></tag>
- <tag><tt>Package_Revision</tt></tag>
- <item>
- <p>
- The Debian revision part of the package version was
- at one point in a separate control file field. This
- field went through several names.</p>
- </item>
-
- <tag><tt>Recommended</tt></tag>
- <item><p>Old name for <tt>Recommends</tt></p>
- </item>
-
- <tag><tt>Optional</tt></tag>
- <item><p>Old name for <tt>Suggests</tt>.</p>
- </item>
- <tag><tt>Class</tt></tag>
- <item><p>Old name for <tt>Priority</tt>.</p>
- </item>
- </taglist>
- </p>
- </sect1>
- </sect>
- </chapt>
-
- <chapt id="versions"><heading>Version numbering
- </heading>
-
- <p>
- Every package has a version number, in its <tt>Version</tt>
- control file field.
- </p>
-
- <p>
- <prgn>dpkg</prgn> imposes an ordering on version numbers, so
- that it can tell whether packages are being up- or downgraded
- and so that <prgn>dselect</prgn> can tell whether a package it
- finds available is newer than the one installed on the system.
- The version number format has the most significant parts (as
- far as comparison is concerned) at the beginning.
- </p>
-
- <p>
- The version number format is:
- &lsqb<var>epoch/<tt>:</tt>]<var>upstream-version</var>[<tt>-/<var>debian-revision</var>].</tt></var>
- </p>
-
- <p>
- The three components here are:
- <taglist>
- <tag><var>epoch</var></tag>
- <item>
-
- <p>
- This is a single unsigned integer, which should usually
- be small. It may be omitted, in which case zero is
- assumed. If it is omitted then the
- <var>upstream-version</var> may not contain any colons.
- </p>
-
- <p>
- It is provided to allow mistakes in the version numbers
- of older versions of a package, and also a package's
- previous version numbering schemes, to be left behind.
- </p>
-
- <p>
- <prgn>dpkg</prgn> will not usually display the epoch
- unless it is essential (non-zero, or if the
- <var>upstream-version</var> contains a colon);
- <prgn>dselect</prgn> does not display epochs at all in
- the main part of the package selection display.</p>
- </item>
-
- <tag><var>upstream-version</var></tag>
- <item>
-
- <p>
- This is the main part of the version. It is usually
- version number of the original (`upstream') package of
- which the <tt>.deb</tt> file has been made, if this is
- applicable. Usually this will be in the same format as
- that specified by the upstream author(s); however, it
- may need to be reformatted to fit into
- <prgn>dpkg</prgn>'s format and comparison scheme.
- </p>
-
- <p>
- The comparison behaviour of <prgn>dpkg</prgn> with
- respect to the <var>upstream-version</var> is described
- below. The <var>upstream-version</var> portion of the
- version number is mandatory.
- </p>
-
- <p>
- The <var>upstream-version</var> may contain only
- alphanumerics and the characters <tt>.</tt> <tt>+</tt>
- <tt>-</tt> <tt>:</tt> (full stop, plus, hyphen, colon)
- and should start with a digit. If there is no
- <var>debian-revision</var> then hyphens are not allowed;
- if there is no <var>epoch</var> then colons are not
- allowed.</p>
- </item>
-
- <tag><var>debian-revision</var></tag>
- <item>
-
- <p>
- This part of the version represents the version of the
- modifications that were made to the package to make it a
- Debian binary package. It is in the same format as the
- <var>upstream-version</var> and <prgn>dpkg</prgn>
- compares it in the same way.
- </p>
-
- <p>
- It is optional; if it isn't present then the
- <var>upstream-version</var> may not contain a hyphen.
- This format represents the case where a piece of
- software was written specifically to be turned into a
- Debian binary package, and so there is only one
- `debianization' of it and therefore no revision
- indication is required.
- </p>
-
- <p>
- It is conventional to restart the
- <var>debian-revision</var> at <tt>1</tt> each time the
- <var>upstream-version</var> is increased.
- </p>
-
- <p>
- <prgn>dpkg</prgn> will break the
- <var>upstream-version</var> and
- <var>debian-revision</var> apart at the last hyphen in
- the string. The absence of a <var>debian-revision</var>
- compares earlier than the presence of one (but note that
- the <var>debian-revision</var> is the least significant
- part of the version number).
- </p>
-
- <p>
- The <var>debian-revision</var> may contain only
- alphanumerics and the characters <tt>+</tt> and
- <tt>.</tt> (plus and full stop).
- </p>
- </item>
- </taglist>
- The <var>upstream-version</var> and <var>debian-revision</var> parts are
- compared by <prgn>dpkg</prgn> using the same algorithm:
- </p>
-
- <p>
- The strings are compared from left to right.
- </p>
-
- <p>
- First the initial part of each string consisting entirely of
- non-digit characters is determined. These two parts (one of
- which may be empty) are compared lexically. If a difference
- is found it is returned. The lexical comparison is a
- comparison of ASCII values modified so that all the letters
- sort earlier than all the non-letters.
- </p>
-
- <p>
- Then the initial part of the remainder of each string which
- consists entirely of digit characters is determined. The
- numerical values of these two parts are compared, and any
- difference found is returned as the result of the comparison.
- For these purposes an empty string (which can only occur at
- the end of one or both version strings being compared) counts
- as zero.
- </p>
-
- <p>
- These two steps are repeated (chopping initial non-digit
- strings and initial digit strings off from the start) until a
- difference is found or both strings are exhausted.
- </p>
-
- <p>
- Note that the purpose of epochs is to allow us to leave behind
- mistakes in version numbering, and to cope with situations
- where the version numbering changes. It is <em>not</em> there
- to cope with version numbers containing strings of letters
- which <prgn>dpkg</prgn> cannot interpret (such as
- <tt>ALPHA</tt> or <tt>pre-</tt>), or with silly orderings (the
- author of this manual has heard of a package whose versions
- went <tt>1.1</tt>, <tt>1.2</tt>, <tt>1.3</tt>, <tt>1</tt>,
- <tt>2.1</tt>, <tt>2.2</tt>, <tt>2</tt> and so forth).
- </p>
-
- <p>
- If an upstream package has problematic version numbers they
- should be converted to a sane form for use in the
- <tt>Version</tt> field.
- </p>
-
- <p>
- If you need to compare version numbers in a script, you may use
- <tt>dpkg --compare-versions ...</tt>. Type <tt>dpkg
- --help</tt> for details on arguments.
- </p>
-
- <sect>
- <heading>Version numbers based on dates</heading>
- <p>
- In general, Debian packages should use the same version
- numbers as the upstream sources.</p>
-
- <p>
- However, in some cases where the upstream version number is
- based on a date (e.g., a development `snapshot' release)
- dpkg cannot handle these version numbers currently, without
- epochs. For example, dpkg will consider `96May01' to be
- greater than `96Dec24'.</p>
-
- <p>
- To prevent having to use epochs for every new upstream
- version, the version number should be changed to the
- following format in such cases: `19960501', `19961224'. It
- is up to the maintainer whether he/she wants to bother the
- upstream maintainer to change the version numbers upstream,
- too.</p>
-
- <p>
- Note, that other version formats based on dates which are
- parsed correctly by dpkg should <em>not</em> be changed.</p>
-
- <p>
- Native Debian packages (i.e., packages which have been
- written especially for Debian) whose version numbers include
- dates should always use the `YYYYMMDD' format.</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
- <prgn>dpkg</prgn> will run for you when your package is
- installed, upgraded or removed.
- </p>
-
- <p>
- These scripts should be the files <tt>preinst</tt>,
- <tt>postinst</tt>, <tt>prerm</tt> and <tt>postrm</tt> in the
- control area of the package. They must be proper exectuable
- files; if they are scripts (which is recommended) they must
- start with the usual <tt>#!</tt> convention. They should be
- readable and executable to anyone, and not world-writeable.
- </p>
-
- <p>
- <prgn>dpkg</prgn> looks at the exit status from these
- scripts. It is important that they exit with a non-zero
- status if there is an error, so that <prgn>dpkg</prgn> can
- stop its processing. For shell scripts this means that you
- <em>almost always</em> need to use <tt>set -e</tt> (this is
- usually true when writing shell scripts, in fact). It is
- also important, of course, that they don't exit with a
- non-zero status if everything went well.
- </p>
-
- <p>
- It is necessary for the error recovery procedures that the
- scripts be idempotent: ie, invoking the same script several
- times in the same situation should do no harm. If the first
- call failed, or aborted half way through for some reason,
- the second call should merely do the things that were left
- undone the first time, if any, and exit with a success
- status.
- </p>
-
- <p>
- When a package is upgraded a combination of the scripts from
- the old and new packages is called in amongst the other
- steps of the upgrade procedure. If your scripts are going
- to be at all complicated you need to be aware of this, and
- may need to check the arguments to your scripts.
- </p>
-
- <p>
- Broadly speaking the <prgn>preinst</prgn> is called before
- (a particular version of) a package is installed, and the
- <prgn>postinst</prgn> afterwards; the <prgn>prerm</prgn>
- before (a version of) a package is removed and the
- <prgn>postrm</prgn> afterwards.
- </p>
- <!--
- next paragraph by Guy Maor to close bug #2481
- -->
-
- <p> Programs called from maintainer scripts should not
- normally have a path prepended to them. Before installation
- is started <prgn>dpkg</prgn> checks to see if the programs
- <prgn>ldconfig</prgn>, <prgn>start-stop-daemon</prgn>,
- <prgn>install-info</prgn>, and <prgn>update-rc.d</prgn> can
- be found via the <tt>PATH</tt> environment variable. Those
- programs, and any other program that one would expect to on
- the <tt>PATH</tt>, should thus be invoked without an
- absolute pathname. Maintainer scripts should also not reset
- the <tt>PATH</tt>, though they might choose to modify it by
- pre- or appending package-specific directories. These
- considerations really apply to all shell scripts.</p>
- </sect>
-
- <sect id="mscriptsinstact"><heading>Summary of ways maintainer
- scripts are called
- </heading>
-
- <p>
- <list compact="compact">
- <item>
- <p><var>new-preinst</var> <tt>install</tt></p>
- </item>
- <item>
- <p><var>new-preinst</var> <tt>install</tt>
- <var>old-version</var></p>
- </item>
- <item>
- <p><var>new-preinst</var> <tt>upgrade</tt>
- <var>old-version</var></p>
- </item>
- <item>
- <p><var>old-preinst</var> <tt>abort-upgrade</tt>
- <var>new-version</var>
- </p>
- </item>
- </list>
-
- <p>
- <list compact="compact">
- <item>
- <p><var>postinst</var> <tt>configure</tt>
- <var>most-recently-configured-version</var></p>
- </item>
- <item>
- <p><var>old-postinst</var> <tt>abort-upgrade</tt>
- <var>new version</var></p>
- </item>
- <item>
- <p><var>conflictor's-postinst</var> <tt>abort-remove</tt>
- <tt>in-favour</tt> <var>package</var>
- <var>new-version</var></p>
- </item>
- <item>
- <p>
- <var>deconfigured's-postinst</var>
- <tt>abort-deconfigure</tt> <tt>in-favour</tt>
- <var>failed-install-package</var> <var>version</var>
- <tt>removing</tt> <var>conflicting-package</var>
- <var>version</var>
- </p>
- </item>
- </list>
-
- <p>
- <list compact="compact">
- <item>
- <p><var>prerm</var> <tt>remove</tt></p>
- </item>
- <item>
- <p><var>old-prerm</var> <tt>upgrade</tt>
- <var>new-version</var></p>
- </item>
- <item>
- <p><var>new-prerm</var> <tt>failed-upgrade</tt>
- <var>old-version</var></p>
- </item>
- <item>
- <p><var>conflictor's-prerm</var> <tt>remove</tt>
- <tt>in-favour</tt> <var>package</var>
- <var>new-version</var></p>
- </item>
- <item>
- <p>
- <var>deconfigured's-prerm</var> <tt>deconfigure</tt>
- <tt>in-favour</tt> <var>package-being-installed</var>
- <var>version</var> <tt>removing</tt>
- <var>conflicting-package</var>
- <var>version</var>
- </p>
- </item>
- </list>
-
- <p>
- <list compact="compact">
- <item>
- <p><var>postrm</var> <tt>remove</tt></p>
- </item>
- <item>
- <p><var>postrm</var> <tt>purge</tt></p>
- </item>
- <item>
- <p>
- <var>old-postrm</var> <tt>upgrade</tt>
- <var>new-version</var></p>
- </item>
- <item>
- <p><var>new-postrm</var> <tt>failed-upgrade</tt>
- <var>old-version</var></p>
- </item>
- <item>
- <p><var>new-postrm</var> <tt>abort-install</tt></p>
- </item>
- <item>
- <p><var>new-postrm</var> <tt>abort-install</tt>
- <var>old-version</var></p>
- </item>
- <item>
- <p><var>new-postrm</var> <tt>abort-upgrade</tt>
- <var>old-version</var></p>
- </item>
- <item>
- <p>
- <var>disappearer's-postrm</var> <tt>disappear</tt>
- <var>overwriter</var>
- <var>overwriter-version</var></p></item>
- </list>
- </p>
-
-
- <sect id="unpackphase"><heading>Details of unpack phase of
- installation or upgrade
- </heading>
-
- <p>
- The procedure on installation/upgrade/overwrite/disappear
- (ie, when running <tt>dpkg --unpack</tt>, or the unpack
- stage of <tt>dpkg
- --install</tt>) is as follows. In each case if an error occurs the
- actions in are general run backwards - this means that the maintainer
- scripts are run with different arguments in reverse order. These are
- the `error unwind' calls listed below.
-
- <enumlist>
- <item>
- <p>
- <enumlist>
- <item>
- <p>If a version the package is already
- installed, call
- <example>
- <var>old-prerm</var> upgrade <var>new-version</var>
- </example></p>
- </item>
- <item>
- <p>
- If this gives an error (ie, a non-zero exit
- status), dpkg will attempt instead:
- <example>
- <var>new-prerm</var> failed-upgrade <var>old-version</var>
- </example>
- Error unwind, for both the above cases:
- <example>
- <var>old-postinst</var> abort-upgrade <var>new-version</var>
- </example>
- </p>
- </item>
- </enumlist>
- </p>
- </item>
- <item>
- <p>If a `conflicting' package is being removed at the same time:
- <enumlist>
- <item>
- <p>
- If any packages depended on that conflicting
- package and <tt>--auto-deconfigure</tt> is
- specified, call, for each such package:
- <example>
- <var>deconfigured's-prerm</var> deconfigure \
- in-favour <var>package-being-installed</var> <var>version</var> \
- removing <var>conflicting-package</var> <var>version</var>
- </example>
- Error unwind:
- <example>
- <var>deconfigured's-postinst</var> abort-deconfigure \
- in-favour <var>package-being-installed-but-failed</var> <var>version</var> \
- removing <var>conflicting-package</var> <var>version</var>
- </example>
- The deconfigured packages are marked as
- requiring configuration, so that if
- <tt>--install</tt> is used they will be
- configured again if possible.</p>
- </item>
- <item>
- <p>To prepare for removal of the conflicting package, call:
- <example>
- <var>conflictor's-prerm</var> remove in-favour <var>package</var> <var>new-version</var>
- </example>
- Error unwind:
- <example>
- <var>conflictor's-postinst</var> abort-remove \
- in-favour <var>package</var> <var>new-version</var>
- </example>
- </p>
- </item>
- </enumlist>
- </p>
- </item>
- <item>
- <p>
- <enumlist>
- <item>
- <p>If the package is being upgraded, call:
- <example>
- <var>new-preinst</var> upgrade <var>old-version</var>
- </example></p>
- </item>
- <item>
- <p>
- Otherwise, if the package had some configuration
- files from a previous version installed (ie, it
- is in the `configuration files only' state):
- <example>
- <var>new-preinst</var> install <var>old-version</var>
- </example></p>
-
- <item>
- <p>Otherwise (ie, the package was completely purged):
- <example>
- <var>new-preinst</var> install
- </example>
- Error unwind versions, respectively:
- <example>
- <var>new-postrm</var> abort-upgrade <var>old-version</var>
- <var>new-postrm</var> abort-install <var>old-version</var>
- <var>new-postrm</var> abort-install
- </example>
- </p>
- </item>
- </enumlist>
- </p>
- </item>
- <item>
-
- <p>
- The new package's files are unpacked, overwriting any
- that may be on the system already, for example any
- from the old version of the same package or from
- another package (backups of the old files are left
- around, and if anything goes wrong dpkg will attempt
- to put them back as part of the error unwind).
- </p>
-
- <p>
- It is an error for a package to contains files which
- are on the system in another package, unless
- <tt>Replaces</tt> is used (see <ref id="replaces">).
- Currently the <tt>--force-overwrite</tt> flag is
- enabled, downgrading it to a warning, but this may not
- always be the case.
- </p>
-
- <p>
- It is a more serious error for a package to contain a
- plain file or other kind of nondirectory where another
- package has a directory (again, unless
- <tt>Replaces</tt> is used). This error can be
- overridden if desired using
- <tt>--force-overwrite-dir</tt>, but this is not
- advisable.
- </p>
-
- <p>
- Packages which overwrite each other's files produce
- behaviour which though deterministic is hard for the
- system administrator to understand. It can easily
- lead to `missing' programs if, for example, a package
- is installed which overwrites a file from another
- package, and is then removed again.
- <footnote>
- <p>
- Part of the problem is due to what is arguably a
- bug in <prgn>dpkg</prgn>.
- </p>
- </footnote>
- </p>
-
- <p>
- A directory will never be replaced by a symbolic links
- to a directory or vice versa; instead, the existing
- state (symlink or not) will be left alone and
- <prgn>dpkg</prgn> will follow the symlink if there is
- one.</p>
- </item>
-
- <item>
-
- <p><enumlist>
- <item>
- <p>If the package is being upgraded, call
- <example>
- <var>old-postrm</var> upgrade <var>new-version</var>
- </example></p>
- </item>
- <item>
- <p>If this fails, <prgn>dpkg</prgn> will attempt:
- <example>
- <var>new-postrm</var> failed-upgrade <var>old-version</var>
- </example>
- Error unwind, for both cases:
- <example>
- <var>old-preinst</var> abort-upgrade <var>new-version</var>
- </example>
- </p>
- </item>
- </enumlist>
- This is the point of no return - if <prgn>dpkg</prgn>
- gets this far, it won't back off past this point if an
- error occurs. This will leave the package in a fairly
- bad state, which will require a successful
- reinstallation to clear up, but it's when
- <prgn>dpkg</prgn> starts doing things that are
- irreversible.</p>
- </item>
- <item>
- <p>
- Any files which were in the old version of the package
- but not in the new are removed.</p>
- </item>
- <item>
- <p>The new file list replaces the old.</p>
- </item>
- <item>
- <p>The new maintainer scripts replace the old.</p>
- </item>
-
- <item>
- <p>Any packages all of whose files have been overwritten during the
- installation, and which aren't required for
- dependencies, are considered to have been removed.
- For each such package,
- <enumlist>
- <item>
- <p><prgn>dpkg</prgn> calls:
- <example>
- <var>disappearer's-postrm</var> disappear \
- <var>overwriter</var> <var>overwriter-version</var>
- </example>
- </p>
- </item>
- <item>
- <p>The package's maintainer scripts are removed.
- </p>
- </item>
- <item>
- <p>
- It is noted in the status database as being in a
- sane state, namely not installed (any conffiles
- it may have are ignored, rather than being
- removed by <prgn>dpkg</prgn>). Note that
- disappearing packages do not have their prerm
- called, because <prgn>dpkg</prgn> doesn't know
- in advance that the package is going to
- vanish.
- </p>
- </item>
- </enumlist>
- </p>
- </item>
- <item>
- <p>
- Any files in the package we're unpacking that are also
- listed in the file lists of other packages are removed
- from those lists. (This will lobotomise the file list
- of the `conflicting' package if there is one.)
- </p>
- </item>
- <item>
- <p>
- The backup files made during installation, above, are
- deleted.
- </p>
- </item>
-
- <item>
- <p>
- The new package's status is now sane, and recorded as
- `unpacked'. Here is another point of no return - if
- the conflicting package's removal fails we do not
- unwind the rest of the installation; the conflicting
- package is left in a half-removed limbo.
- </p>
- </item>
- <item>
- <p>
- If there was a conflicting package we go and do the
- removal actions (described below), starting with the
- removal of the conflicting package's files (any that
- are also in the package being installed have already
- been removed from the conflicting package's file list,
- and so do not get removed now).
- </p>
- </item>
- </enumlist>
- </p>
- </sect>
-
- <sect><heading>Details of configuration
- </heading>
-
- <p>
- When we configure a package (this happens with <tt>dpkg
- --install</tt>, or with <tt>--configure</tt>), we first
- update the conffiles and then call:
- <example>
- <var>postinst</var> configure <var>most-recently-configured-version</var>
- </example>
- </p>
-
- <p>
- No attempt is made to unwind after errors during
- configuration.
- </p>
-
- <p>
- If there is no most recently configured version
- <prgn>dpkg</prgn> will pass a null argument; older versions
- of dpkg may pass <tt><unknown></tt> (including the
- angle brackets) in this case. Even older ones do not pass a
- second argument at all, under any circumstances.
- </p>
- </sect>
-
- <sect><heading>Details of removal and/or configuration purging
- </heading>
-
- <p>
- <enumlist>
- <item>
- <p>
- <example>
- <var>prerm</var> remove
- </example>
- </p>
- </item>
- <item>
- <p>
- The package's files are removed (except conffiles).
- </p>
- </item>
- <item>
- <p><example>
- <var>postrm</var> remove
- </example></p>
- </item>
- <item>
- <p>All the maintainer scripts except the postrm are removed.
- </p>
-
- <p>
- If we aren't purging the package we stop here. Note
- that packages which have no postrm and no conffiles
- are automatically purged when removed, as there is no
- difference except for the <prgn>dpkg</prgn>
- status.</p>
- </item>
- <item>
- <p>
- The conffiles and any backup files (<tt>~</tt>-files,
- <tt>#*#</tt> files, <tt>%</tt>-files,
- <tt>.dpkg-{old,new,tmp}</tt>, etc.) are removed.</p>
- </item>
- <item>
- <p><example>
- <var>postrm</var> purge
- </example></p>
- </item>
- <item>
- <p>The package's file list is removed.</p>
- </item>
- </enumlist>
- No attempt is made to unwind after errors during
- removal.</p>
- </sect>
- </chapt>
-
- <chapt id="descriptions"><heading>Descriptions of packages - the
- <tt>Description</tt> field
- </heading>
-
- <p>
- The <tt>Description</tt> control file field is used by
- <prgn>dselect</prgn> when the user is selecting which packages
- to install and by <prgn>dpkg</prgn> when it displays
- information about the status of packages and so forth. It is
- included on the FTP site in the <prgn>Packages</prgn> files,
- and may also be used by the Debian WWW pages.
- </p>
-
- <p>
- The description is intended to describe the program to a user
- who has never met it before so that they know whether they
- want to install it. It should also give information about the
- significant dependencies and conflicts between this package
- and others, so that the user knows why these dependencies and
- conflicts have been declared.
- </p>
-
- <p>
- The field's format is as follows:
- <example>
- Description: <var>single line synopsis</var>
- <var>extended description over several lines</var>
- </example>
- </p>
-
- <p>
- The synopsis is often printed in lists of packages and so
- forth, and should be as informative as possible. Every
- package should also have an extended description.
- </p>
-
- <sect><heading>Types of formatting line in the extended
- description
- </heading>
-
- <p>
- <list>
- <item>
- <p>
- Those starting with a single space are part of a
- paragraph. Successive lines of this form will be
- word-wrapped when displayed. The leading space will
- usually be stripped off.
- </p>
- </item>
-
- <item>
- <p>
- Those starting with two or more spaces. These will be
- displayed verbatim. If the display cannot be panned
- horizontally the displaying program will linewrap them
- `hard' (ie, without taking account of word breaks).
- If it can they will be allowed to trail off to the
- right. None, one or two initial spaces may be
- deleted, but the number of spaces deleted from each
- line will be the same (so that you can have indenting
- work correctly, for example).
- </p>
- </item>
-
- <item>
- <p>Those containing a single space followed by a single full stop
- character. These are rendered as blank lines. This
- is the <em>only</em> way to get a blank line - see
- below.</p>
- </item>
-
- <item>
- <p>
- Those containing a space, a full stop and some more
- characters. These are for future expansion. Do not
- use them.</p>
- </item>
- </list>
- </p>
- </sect>
-
- <sect><heading>Notes about writing descriptions
- </heading>
-
- <p>
- <em>Always</em> start extended description lines with at least one
- whitespace character. Fields in the control file and in the Packages
- file are separated by field names starting in the first column, just
- as message header fields are in RFC822. Forgetting the whitespace
- will cause <prgn>dpkg-deb</prgn>
- <footnote>
- <p>
- Version 0.93.23 or later.
- </p>
- </footnote> to produce a syntax error when trying to build
- the package. If you force it to build anyway
- <prgn>dpkg</prgn> will refuse to install the resulting
- mess.
- </p>
-
- <p>
- <em>Do not</em> include any completely <em>empty</em>
- lines. These separate different records in the Packages file
- and different packages in the <tt>debian/control</tt> file,
- and are forbidden in package control files. See the
- previous paragraph for what happens if you get this wrong.
- </p>
-
- <p>
- The single line synopsis should be kept brief - certainly
- under 80 characters. <prgn>dselect</prgn> displays between
- 25 and 49 characters without panning if you're using an
- 80-column terminal, depending on what display options are in
- effect.
- </p>
-
- <p>
- Do not include the package name in the synopsis line. The
- display software knows how to display this already, and you
- do not need to state it. Remember that in many situations
- the user may only see the synopsis line - make it as
- informative as you can.
- </p>
-
- <p>
- The extended description should describe what the package
- does and how it relates to the rest of the system (in terms
- of, for example, which subsystem it is which part of).
- </p>
-
- <p>
- The blurb that comes with a program in its announcements
- and/or <prgn>README</prgn> files is rarely suitable for use
- in a description. It is usually aimed at people who are
- already in the community where the package is used. The
- description field needs to make sense to anyone, even people
- who have no idea about any of the things the package deals
- with.
- </p>
-
- <p>
- Put important information first, both in the synopis and
- extended description. Sometimes only the first part of the
- synopsis or of the description will be displayed. You can
- assume that there will usually be a way to see the whole
- extended description.
- </p>
-
- <p>
- You may include information about dependencies and so forth
- in the extended description, if you wish.
- </p>
-
- <p>
- Do not use tab characters. Their effect is not predictable.
- </p>
-
- <p>
- Do not try to linewrap the summary (the part on the same
- line as the field name <tt>Description</tt>) into the
- extended description. This will not work correctly when the
- full description is displayed, and makes no sense where only
- the summary is available.</p>
- </sect>
-
- <sect><heading>Example description in control file for Smail
- </heading>
-
- <p>
- <example>
- Package: smail
- Version: 3.1.29.1-13
- Maintainer: Ian Jackson <iwj10@cus.cam.ac.uk>
- Recommends: pine | mailx | elm | emacs | mail-user-agent
- Suggests: metamail
- Depends: cron, libc5
- Conflicts: sendmail
- Provides: mail-transport-agent
- Description: Electronic mail transport system.
- Smail is the recommended mail transport agent (MTA) for Debian.
- .
- An MTA is the innards of the mail system - it takes messages from
- user-friendly mailer programs and arranges for them to be delivered
- locally or passed on to other systems as required.
- .
- In order to make use of it you must have one or more user level
- mailreader programs such as elm, pine, mailx or Emacs (which has Rmail
- and VM as mailreaders) installed. If you wish to send messages other
- than just to other users of your system you must also have appropriate
- networking support, in the form of IP or UUCP.
- </example>
- </p>
- </sect>
- </chapt>
-
- <chapt id="relationships"><heading>Declaring relationships between
- packages
- </heading>
-
- <p>
- Packages can declare in their control file that they have
- certain relationships to other packages - for example, that
- they may not be installed at the same time as certain other
- packages, and/or that they depend on the presence of others,
- or that they should overwrite files in certain other packages
- if present.
- </p>
-
- <p>
- This is done using the <tt>Depends</tt>, <tt>Recommends</tt>,
- <tt>Suggests</tt>, <tt>Conflicts</tt>, <tt>Provides</tt> and
- <tt>Replaces</tt> control file fields.
- </p>
-
- <p>
- Source packages may declare relationships to binary packages,
- saying that they require certain binary packages being
- installed or absent at the time of building the package.
- </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>
-
- <sect id="depsyntax"><heading>Syntax of relationship fields
- </heading>
-
- <p>
- These fields all have a uniform syntax. They are a list of
- package names separated by commas.
- </p>
-
- <p>
- In <tt>Depends</tt>, <tt>Recommends</tt>, <tt>Suggests</tt>,
- <tt>Pre-Depends</tt>, <tt>Build-Depends</tt> and
- <tt>Build-Depends-Indep</tt>(the fields which declare
- dependencies of the package in which they occur on other
- packages) these package names may also be lists of
- alternative package names, separated by vertical bar symbols
- <tt>|</tt> (pipe symbols).
- </p>
-
- <p>
- All the fields except <tt>Provides</tt> may restrict their
- applicability to particular versions of each named package.
- This is done in parentheses after each individual package
- name; the parentheses should contain a relation from the
- list below followed by a version number, in the format
- described in <ref id="versions">.
- </p>
-
- <p>
- The relations allowed are <tt><<</tt>, <tt><=</tt>,
- <tt>=</tt>, <tt>>=</tt> and <tt>>></tt> for
- strictly earlier, earlier or equal, exactly equal, later or
- equal and strictly later, respectively. The forms
- <tt><</tt> and <tt>></tt> were used to mean
- earlier/later or equal, rather than strictly earlier/later,
- so they should not appear in new packages (though
- <prgn>dpkg</prgn> still supports them).
- </p>
-
- <p>
- Whitespace may appear at any point in the version
- specification, and must appear where it's necessary to
- disambiguate; it is not otherwise significant. For
- consistency and in case of future changes to
- <prgn>dpkg</prgn> it is recommended that a single space be
- used after a version relationship and before a version
- number; it is usual also to put a single space after each
- comma, on either side of each vertical bar, and before each
- open parenthesis.
- </p>
-
- <p>
- For example:
- <example>
- Package: metamail
- Version: 2.7-3
- Depends: libc5 (>= 5.2.18-4), mime-support, csh | tcsh
- </example>
- </p>
-
- <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 done in brackets after each individual package name and
- the optional version specification. The brackets enclose a
- list of Debian architecture names separated by whitespace.
- An exclamation mark may be prepended to each name. 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>
- 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>
- </sect>
-
- <sect>
- <heading>Binary Dependencies - <tt>Depends</tt>,
- <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Pre-Depends</tt>
- </heading>
-
- <p>
- These four fields are used to declare a dependency by one
- package on another. They appear in the depending package's
- control file.
- </p>
-
- <p>
- All but <tt>Pre-Depends</tt> (discussed below) take effect
- <em>only</em> when a package is to be configured. They do
- not prevent a package being on the system in an unconfigured
- state while its dependencies are unsatisfied, and it is
- possible to replace a package whose dependencies are
- satisfied and which is properly installed with a different
- version whose dependencies are not and cannot be satisfied;
- when this is done the depending package will be left
- unconfigured (since attempts to configure it will give
- errors) and will not function properly.
- </p>
-
- <p>
- For this reason packages in an installation run are usually
- all unpacked first and all configured later; this gives
- later versions of packages with dependencies on later
- versions of other packages the opportunity to have their
- dependencies satisfied.
- </p>
-
- <p>
- Thus <tt>Depends</tt> allows package maintainers to impose
- an order in which packages should be configured.
- <taglist>
- <tag><tt>Depends</tt></tag>
- <item>
-
- <p>This declares an absolute dependency.
- </p>
-
- <p>
- <prgn>dpkg</prgn> will not configure packages whose
- dependencies aren't satisfied. If it is asked to make
- an installation which would cause an installed
- package's dependencies to become unsatisfied it will
- complain
- <footnote>
- <p>
- Current versions (1.2.4) of <prgn>dpkg</prgn> have
- a bug in this area which will cause some of these
- problems to be ignored.
- </p>
- </footnote>, unless <tt>--auto-deconfigure</tt> is
- specified, in which case those packages will be
- deconfigured before the installation proceeds.
- </p>
-
- <p>
- <prgn>dselect</prgn> makes it hard for the user to
- select packages for installation, removal or upgrade
- in a way that would mean that packages'
- <prgn>Depends</prgn> fields would be unsatisfied. The
- user can override this if they wish, for example if
- they know that <prgn>dselect</prgn> has an out-of-date
- view of the real package relationships.
- </p>
-
- <p>
- The <tt>Depends</tt> field should be used if the
- depended-on package is required for the depending
- package to provide a significant amount of
- functionality.</p>
- </item>
-
- <tag><tt>Recommends</tt></tag>
- <item>
- <p>This declares a strong, but not absolute, dependency.
- </p>
-
- <p>
- <tt>Recommends</tt> is ignored by <prgn>dpkg</prgn>,
- so that users using the command-line (who are presumed
- to know what they're doing) will not be impeded.
- </p>
-
- <p>
- It is treated by <prgn>dselect</prgn> exactly as
- <tt>Depends</tt> is; this makes it hard for the user
- to select things so as to leave <tt>Recommends</tt>
- fields unsatisfied, but they are able to do so by
- being persistent.
- </p>
-
- <p>
- The <tt>Recommends</tt> field should list packages
- that would be found together with this one in all but
- unusual installations.</p>
- </item>
-
- <tag><tt>Suggests</tt></tag>
- <item>
-
- <p>
- This is used to declare that one package may be more
- useful with one or more others. Using this field
- tells the packaging system and the user that the
- listed packages are related to this one and can
- perhaps enhance its usefulness, but that installing
- this one without them is perfectly reasonable.
- </p>
-
- <p>
- <prgn>dselect</prgn> will offer suggsted packages to
- the system administrator when they select the
- suggesting package, but the default is not to install
- the suggested package.</p>
- </item>
-
- <tag><tt>Pre-Depends</tt></tag>
- <item>
-
- <p>This field is like <tt>Depends</tt>, except that it also forces
- <prgn>dpkg</prgn> to complete installation of the
- packages named before even starting the installation
- of the package which declares the predependency.
- </p>
-
- <p>
- <prgn>dselect</prgn> checks for predependencies when
- it is doing an installation run, and will attempt to
- find the packages which are required to be installed
- first and do so in the right order.
- </p>
-
- <p>
- However, this process is slow (because it requires
- repeated invocations of <prgn>dpkg</prgn>) and
- troublesome (because it requires guessing where to
- find the appropriate files).
- </p>
-
- <p>
- For these reasons, and because this field imposes
- restrictions on the order in which packages may be
- unpacked (which can be difficult for installations
- from multipart media, for example),
- <tt>Pre-Depends</tt> should be used sparingly,
- preferably only by packages whose premature upgrade or
- installation would hamper the ability of the system to
- continue with any upgrade that might be in progress.
- </p>
-
- <p>
- When the package declaring it is being configured, a
- <tt>Pre-Dependency</tt> will be considered satisfied
- only if the depending package has been correctly
- configured, just as if an ordinary <tt>Depends</tt>
- had been used.
- </p>
-
- <p>
- However, when a package declaring a predependency is
- being unpacked the predependency can be satisfied even
- if the depended-on package(s) are only unpacked or
- half-configured, provided that they have been
- configured correctly at some point in the past (and
- not removed or partially removed since). In this case
- both the previously-configured and currently unpacked
- or half-configured versions must satisfy any version
- clause in the <tt>Pre-Depends</tt> field.
- </p>
- </item>
- </taglist>
- </p>
- <p>
- When selecting which level of dependency to use you should
- consider how important the depended-on package is to the
- functionality of the one declaring the dependency. Some
- packages are composed of components of varying degrees of
- importance. Such a package should list using
- <tt>Depends</tt> the package(s) which are required by the
- more important components. The other components'
- requirements may be mentioned as Suggestions or
- Recommendations, as appropriate to the components' relative
- importance.
- </p>
-
- <sect1><heading>Dependencies on shared libraries
- </heading>
-
- <p>
- The dependency fields listed above are used by packages
- which need shared libraries to declare dependencies on the
- appropriate packages.
- </p>
-
- <p>
- These dependencies are usually determined automatically
- using <prgn>dpkg-shlibdeps</prgn> and inserted in the
- package control file using the control file substitution
- variables mechanism; see <ref id="srcsubstvars"> and
- <ref id="sourcetools">.
- </p>
- </sect1>
-
- <sect1><heading>Deconfiguration due to removal during bulk
- installations
- </heading>
-
- <p>
- If <prgn>dpkg</prgn> would like to remove a package due to a
- conflict, as described above, but this would violate a
- dependency of some other package on the system,
- <prgn>dpkg</prgn> will usually not remove the conflicting
- package and halt with an error.
- </p>
-
- <p>
- However, if the <tt>--auto-deconfigure</tt> (<tt>-B</tt>)
- option is used <prgn>dpkg</prgn> will automatically
- `deconfigure' the package with the problematic dependency,
- so that the conflicting package can be removed and the
- package we're trying to install can be installed. If
- <prgn>dpkg</prgn> is being asked to install packages (rather
- than just unpacking them) it will try to reconfigure the
- package when it has unpacked all its arguments, in the hope
- that one of the other packages it is installing will satisfy
- the problematic dependency.
- </p>
-
- <p>
- <prgn>dselect</prgn> supplies this argument to
- <prgn>dpkg</prgn> when it invokes it, so that bulk
- installations proceed smoothly.
- </p>
- </sect1>
-
- <sect id="conflicts"><heading>Alternative binary packages -
- <tt>Conflicts</tt> and <tt>Replaces</tt>
- </heading>
-
- <p>
- When one binary package declares a conflict with another
- <prgn>dpkg</prgn> will refuse to allow them to be installed
- on the system at the same time.
- </p>
-
- <p>
- If one package is to be installed, the other must be removed
- first - if the package being installed is marked as
- replacing (<ref id="replaces">) the one on the system, or
- the one on the system is marked as deselected, or both
- packages are marked <tt>Essential</tt>, then
- <prgn>dpkg</prgn> will automatically remove the package
- which is causing the conflict, otherwise it will halt the
- installation of the new package with an error. This
- mechanism specifically doesn't work when the installed
- package is <tt>Essential</tt>, but the new package is not.
- </p>
-
- <p>
- <prgn>dselect</prgn> makes it hard to select conflicting
- packages, though the user can override this if they wish.
- If they do not override it then <prgn>dselect</prgn> will
- select one of the packages for removal, and the user must
- make sure it is the right one. In the future
- <prgn>dselect</prgn> will look for the presence of a
- <tt>Replaces</tt> field to help decide which package should
- be installed and which removed.
- </p>
-
- <p>
- A package will not cause a conflict merely because its
- configuration files are still installed; it must be at least
- half-installed.
- </p>
-
- <p>
- A special exception is made for packages which declare a
- conflict with their own package name, or with a virtual
- package which they provide (see below): this does not
- prevent their installation, and allows a package to conflict
- with others providing a replacement for it. You use this
- feature when you want the package in question to be the only
- package providing something.
- </p>
-
- <p>
- A <tt>Conflicts</tt> entry should almost never have an
- `earlier than' version clause. This would prevent
- <prgn>dpkg</prgn> from upgrading or installing the package
- which declared such a conflict until the upgrade or removal
- of the conflicted-with package had been completed. This
- aspect of installation ordering is not handled by
- <prgn>dselect</prgn>, so that the use <tt>Conflicts</tt> in
- this way is likely to cause problems for `bulk run' upgrades
- and installations.
- </p>
- </sect>
-
- <sect id="virtual"><heading>Virtual packages - <tt>Provides</tt>
- </heading>
-
- <p>
- As well as the names of actual (`concrete') packages, the
- package relationship fields <tt>Depends</tt>,
- <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
- <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Conflicts</tt>,
- <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt> may
- mention virtual packages.
- </p>
-
- <p>
- A virtual package is one which appears in the
- <tt>Provides</tt> control file field of another package.
- The effect is as if the package(s) which provide a
- particular virtual package name had been listed by name
- everywhere the virtual package name appears.
- </p>
-
- <p>
- If there are both a real and a virtual package of the same
- name then the dependency may be satisfied (or the conflict
- caused) by either the real package or any of the virtual
- packages which provide it. This is so that, for example,
- supposing we have
- <example>
- Package: vm
- Depends: emacs
- </example>
- and someone else releases an xemacs package they can say
- <example>
- Package: xemacs
- Provides: emacs
- </example> and all will work in the interim (until a purely
- virtual package name is decided on and the <tt>emacs</tt>
- and <tt>vm</tt> packages are changed to use it).
- </p>
-
- <p>
- If a dependency or a conflict has a version number attached
- then only real packages will be considered to see whether
- the relationship is satisfied (or the prohibition violated,
- for a conflict) - it is assumed that a real package which
- provides virtual package is not of the `right' version. So,
- a <tt>Provides</tt> field may not contain version numbers,
- and the version number of the concrete package which
- provides a particular virtual package will not be looked at
- when considering a dependency on or conflict with the
- virtual package name.
- </p>
-
- <p>
- It is likely that the ability will be added in a future
- release of <prgn>dpkg</prgn> to specify a version number for
- each virtual package it provides. This feature is not yet
- present, however, and is expected to be used only
- infrequently.
- </p>
-
- <p>
- If you want to specify which of a set of real packages should be the
- default to satisfy a particular dependency on a virtual package, you
- should list the real package as an alternative before the virtual.
- </p>
- </sect>
-
-
- <sect id="replaces"><heading><tt>Replaces</tt> - overwriting
- files and replacing packages
- </heading>
-
- <p>
- The <tt>Replaces</tt> control file field has two purposes,
- which come into play in different situations.
- </p>
-
- <p>
- Virtual packages (<ref id="virtual">) are not considered
- when looking at a <tt>Replaces</tt> field - the packages
- declared as being replaced must be mentioned by their real
- names.
- </p>
-
- <sect1><heading>Overwriting files in other packages
- </heading>
-
- <p>
- Firstly, as mentioned before, it is usually an error for a
- package to contains files which are on the system in
- another package, though currently the
- <tt>--force-overwrite</tt> flag is enabled by default,
- downgrading the error to a warning,
- </p>
-
- <p>
- If the overwriting package declares that it replaces the
- one containing the file being overwritten then
- <prgn>dpkg</prgn> will proceed, and replace the file from
- the old package with that from the new. The file will no
- longer be listed as `owned' by the old package.
- </p>
-
- <p>
- If a package is completely replaced in this way, so that
- <prgn>dpkg</prgn> does not know of any files it still
- contains, it is considered to have disappeared. It will
- be marked as not wanted on the system (selected for
- removal) and not installed. Any conffiles details noted
- in the package will be ignored, as they will have been
- taken over by the replacing package(s). The package's
- <prgn>postrm</prgn> script will be run to allow the
- package to do any final cleanup required. See <ref
- id="mscriptsinstact">.
- </p>
-
- <p>
- In the future <prgn>dpkg</prgn> will discard files which
- overwrite those from another package which declares that
- it replaces the one being installed (so that you can
- install an older version of a package without problems).
- </p>
-
- <p>
- This usage of <tt>Replaces</tt> only takes effect when
- both packages are at least partially on the system at
- once, so that it can only happen if they do not conflict
- or if the conflict has been overridden.</p>
- </sect1>
-
- <sect1><heading>Replacing whole packages, forcing their
- removal
- </heading>
-
- <p>
- Secondly, <tt>Replaces</tt> allows <prgn>dpkg</prgn> and
- <prgn>dselect</prgn> to resolve which package should be
- removed when 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 effects do not interfere with
- each other.
- </p>
- </sect1>
- </sect>
-
- <sect><heading>Defaults for satisfying dependencies - ordering
- </heading>
-
- <p>
- Ordering is significant in dependency fields.
- </p>
-
- <p>
- Usually dselect will suggest to the user that they select
- the package with the most `fundamental' class (eg, it will
- prefer Base packages to Optional ones), or the one that they
- `most wanted' to select in some sense.
- </p>
-
- <p>
- In the absence of other information <prgn>dselect</prgn>
- will offer a default selection of the first named package in
- a list of alternatives.
- </p>
-
- <p>
- However, there is no way to specify the `order' of several
- packages which all provide the same thing, when that thing
- is listed as a dependency.
- </p>
-
- <p>
- Therefore a dependency on a virtual package should contain a
- concrete package name as the first alternative, so that this
- is the default.
- </p>
-
- <p>
- For example, consider the set of packages:
- <example>
- Package: glibcdoc
- Recommends: info-browser
-
- Package: info
- Provides: info-browser
-
- Package: emacs
- Provides: info-browser
- </example>
- </p>
-
- <p>
- If <prgn>emacs</prgn> and <prgn>info</prgn> both have the
- same priority then <prgn>dselect</prgn>'s choice is
- essentially random. Better would be
- <example>
- Package: glibcdoc
- Recommends: info | info-browser
- </example>
- so that <prgn>dselect</prgn> defaults to selecting the
- lightweight standalone info browser.
- </p>
- </sect>
-
-
- <sect><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>
- A source package may declare a dependency or a conflict on a
- binary package. This is done with the control file fields
- <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
- <tt>Build-Conflicts</tt>, and <tt>Build-Conflicts-Indep</tt>. Their
- semantics is that the dependencies and conflicts they define
- must be satisfied (as defined earlier for binary packages),
- when one of the targets in <tt>debian/rules</tt> that the
- particular field applies to is invoked.
-
- <taglist>
- <tag><tt>Build-Depends</tt>, <tt>Build-Conflicts</tt></tag>
- <item>
- <p>
- The <tt>Build-Depends</tt> and
- <tt>Build-Conflicts</tt> fields apply to the targets
- <tt>build</tt>, <tt>binary</tt>, <tt>binary-arch</tt>
- and <tt>binary-indep</tt>.
- </p>
- </item>
- <tag><tt>Build-Depends-Indep</tt>, <tt>Build-Conflicts-Indep</tt></tag>
- <item>
- <p>
- The <tt>Build-Depends-Indep</tt> and
- <tt>Build-Conflicts-Indep</tt> fields apply to the
- targets <tt>binary</tt> and <tt>binary-indep</tt>.
- </p>
- </item>
- </taglist>
-
- </p>
-
- </sect>
- </chapt>
-
-
- <chapt id="conffiles"><heading>Configuration file handling
- </heading>
-
- <p>
- <prgn>dpkg</prgn> can do a certain amount of automatic
- handling of package configuration files.
- </p>
-
- <p>
- Whether this mechanism is appropriate depends on a number of
- factors, but basically there are two approaches to any
- particular configuration file.
- </p>
-
- <p>
- The easy method is to ship a best-effort configuration in the
- package, and use <prgn>dpkg</prgn>'s conffile mechanism to
- handle updates. If the user is unlikely to want to edit the
- file, but you need them to be able to without losing their
- changes, and a new package with a changed version of the file
- is only released infrequently, this is a good approach.
- </p>
-
- <p>
- The hard method is to build the configuration file from
- scratch in the <prgn>postinst</prgn> script, and to take the
- responsibility for fixing any mistakes made in earlier
- versions of the package automatically. This will be
- appropriate if the file is likely to need to be different on
- each system.
- </p>
-
- <sect><heading>Automatic handling of configuration files by
- <prgn>dpkg</prgn>
- </heading>
-
- <p>
- A package may contain a control area file called
- <tt>conffiles</tt>. This file should be a list of filenames
- of configuration files needing automatic handling, separated
- by newlines. The filenames should be absolute pathnames,
- and the files referred to should actually exist in the
- package.
- </p>
-
- <p>
- When a package is upgraded <prgn>dpkg</prgn> will process
- the configuration files during the configuration stage,
- shortly before it runs the package's <prgn>postinst</prgn>
- script,
- </p>
-
- <p>
- For each file it checks to see whether the version of the
- file included in the package is the same as the one that was
- included in the last version of the package (the one that is
- being upgraded from); it also compares the version currently
- installed on the system with the one shipped with the last
- version.
- </p>
-
- <p>
- If neither the user nor the package maintainer has changed
- the file, it is left alone. If one or the other has changed
- their version, then the changed version is preferred - i.e.,
- if the user edits their file, but the package maintainer
- doesn't ship a different version, the user's changes will
- stay, silently, but if the maintainer ships a new version
- and the user hasn't edited it the new version will be
- installed (with an informative message). If both have
- changed their version the user is prompted about the problem
- and must resolve the differences themselves.
- </p>
-
- <p>
- The comparisons are done by calculating the MD5 message
- digests of the files, and storing the MD5 of the file as it
- was included in the most recent version of the package.
- </p>
-
- <p>
- When a package is installed for the first time
- <prgn>dpkg</prgn> will install the file that comes with it,
- unless that would mean overwriting a file already on the
- filesystem.
- </p>
-
- <p>
- However, note that <prgn>dpkg</prgn> will <em>not</em>
- replace a conffile that was removed by the user (or by a
- script). This is necessary because with some programs a
- missing file produces an effect hard or impossible to
- achieve in another way, so that a missing file needs to be
- kept that way if the user did it.
- </p>
-
- <p>
- Note that a package should <em>not</em> modify a
- <prgn>dpkg</prgn>-handled conffile in its maintainer
- scripts. Doing this will lead to <prgn>dpkg</prgn> giving
- the user confusing and possibly dangerous options for
- conffile update when the package is upgraded.</p>
- </sect>
-
- <sect><heading>Fully-featured maintainer script configuration
- handling
- </heading>
-
- <p>
- For files which contain site-specific information such as
- the hostname and networking details and so forth, it is
- better to create the file in the package's
- <prgn>postinst</prgn> script.
- </p>
-
- <p>
- This will typically involve examining the state of the rest
- of the system to determine values and other information, and
- may involve prompting the user for some information which
- can't be obtained some other way.
- </p>
-
- <p>
- When using this method there are a couple of important
- issues which should be considered:
- </p>
-
- <p>
- If you discover a bug in the program which generates the
- configuration file, or if the format of the file changes
- from one version to the next, you will have to arrange for
- the postinst script to do something sensible - usually this
- will mean editing the installed configuration file to remove
- the problem or change the syntax. You will have to do this
- very carefully, since the user may have changed the file,
- perhaps to fix the very problem that your script is trying
- to deal with - you will have to detect these situations and
- deal with them correctly.
- </p>
-
- <p>
- If you do go down this route it's probably a good idea to
- make the program that generates the configuration file(s) a
- separate program in <tt>/usr/sbin</tt>, by convention called
- <tt><var>package</var>config</tt> and then run that if
- appropriate from the post-installation script. The
- <tt><var>package</var>config</tt> program should not
- unquestioningly overwrite an existing configuration - if its
- mode of operation is geared towards setting up a package for
- the first time (rather than any arbitrary reconfiguration
- later) you should have it check whether the configuration
- already exists, and require a <tt>--force</tt> flag to
- overwrite it.</p></sect>
- </chapt>
-
-
-
- <chapt id="alternatives"><heading>Alternative versions of an interface -
- <prgn>update-alternatives</prgn>
- </heading>
-
- <p>
- When several packages all provide different versions of the
- same program or file it is useful to have the system select a
- default, but to allow the system administrator to change it
- and have their decisions respected.
- </p>
-
- <p>
- For example, there are several versions of the <prgn>vi</prgn>
- editor, and there is no reason to prevent all of them from
- being installed at once, each under their own name
- (<prgn>nvi</prgn>, <prgn>vim</prgn> or whatever).
- Nevertheless it is desirable to have the name <tt>vi</tt>
- refer to something, at least by default.
- </p>
-
- <p>
- If all the packages involved cooperate, this can be done with
- <prgn>update-alternatives</prgn>.
- </p>
-
- <p>
- Each package provides its own version under its own name, and
- calls <prgn>update-alternatives</prgn> in its postinst to
- register its version (and again in its prerm to deregister
- it).
- </p>
-
- <p>
- See the manpage <manref name="update-alternatives"
- section="8"> for details.
- </p>
-
- <p>
- If <prgn>update-alternatives</prgn> does not seem appropriate
- you may wish to consider using diversions instead.</p>
- </chapt>
-
-
- <chapt id="diversions"><heading>Diversions - overriding a
- package's version of a file
- </heading>
-
- <p>
- It is possible to have <prgn>dpkg</prgn> not overwrite a file
- when it reinstalls the package it belongs to, and to have it
- put the file from the package somewhere else instead.
- </p>
-
- <p>
- This can be used locally to override a package's version of a
- file, or by one package to override another's version (or
- provide a wrapper for it).
- </p>
-
- <p>
- Before deciding to use a diversion, read <ref
- id="alternatives"> to see if you really want a diversion
- rather than several alternative versions of a program.
- </p>
-
- <p>
- There is a diversion list, which is read by <prgn>dpkg</prgn>,
- and updated by a special program <prgn>dpkg-divert</prgn>.
- Please see <manref name="dpkg-divert" section="8"> for full
- details of its operation.
- </p>
-
- <p>
- When a package wishes to divert a file from another, it should
- call <prgn>dpkg-divert</prgn> in its preinst to add the
- diversion and rename the existing file. For example,
- supposing that a <prgn>smailwrapper</prgn> package wishes to
- install a wrapper around <tt>/usr/sbin/smail</tt>:
- <example>
- if [ install = "$1" -o upgrade = "$1" ]; then
- dpkg-divert --package smailwrapper --add --rename \
- --divert /usr/sbin/smail.real /usr/sbin/smail
- fi
- </example> Testing <tt>$1</tt> is necessary so that the script
- doesn't try to add the diversion again when
- <prgn>smailwrapper</prgn> is upgraded. The <tt>--package
- smailwrapper</tt> ensures that <prgn>smailwrapper</prgn>'s
- copy of <tt>/usr/sbin/smail</tt> can bypass the diversion and
- get installed as the true version.
- </p>
-
- <p>
- The postrm has to do the reverse:
- <example>
- if [ remove = "$1" ]; then
- dpkg-divert --package smailwrapper --remove --rename \
- --divert /usr/sbin/smail.real /usr/sbin/smail
- fi
- </example>
- </p>
-
- <p>
- Do not attempt to divert a file which is vitally important for
- the system's operation - when using <prgn>dpkg-divert</prgn>
- there is a time, after it has been diverted but before
- <prgn>dpkg</prgn> has installed the new version, when the file
- does not exist.</p>
- </chapt>
-
-
- <chapt id="sharedlibs"><heading>Shared libraries
- </heading>
-
- <p>
- Packages containing shared libraries must be constructed with
- a little care to make sure that the shared library is always
- available. This is especially important for packages whose
- shared libraries are vitally important, such as the libc.
- </p>
-
- <p>
- Firstly, your package should install the shared libraries
- under their normal names. For example, the
- <prgn>libgdbm1</prgn> package should install
- <tt>libgdbm.so.1.7.3</tt> as
- <tt>/usr/lib/libgdbm.so.1.7.3</tt>. The files should not be
- renamed or relinked by any prerm or postrm scripts;
- <prgn>dpkg</prgn> will take care of renaming things safely
- without affecting running programs, and attempts to interfere
- with this are likely to lead to problems.
- </p>
-
- <p>
- Secondly, your package should include the symlink that
- <prgn>ldconfig</prgn> would create for the shared libraries.
- For example, the <prgn>libgdbm1</prgn> package should include
- a symlink from <tt>/usr/lib/libgdbm.so.1</tt> to
- <tt>libgdbm.so.1.7.3</tt>. This is needed so that
- <prgn>ld.so</prgn> can find the library in between the time
- <prgn>dpkg</prgn> installs it and <prgn>ldconfig</prgn> is run
- in the <prgn>postinst</prgn> script. Futhermore, older
- versions of the package management system required the library
- must be placed before the symlink pointing to it in the
- <tt>.deb</tt> file. This is so that by the time
- <prgn>dpkg</prgn> comes to install the symlink (overwriting
- the previous symlink pointing at an older version of the
- library) the new shared library is already in place.
- Unfortunately, this was not not always possible, since it
- highly depends on the behaviour of the filesystem. Some
- filesystems (such as reisefs) will reorder the files so it
- doesn't matter in what order you create them. Starting with
- release <tt>1.7.0</tt> <prgn>dpkg</prgn> will reorder the
- files itself when building a package.
- </p>
-
- <!--
- next Paragraph added to close Bug #5299, Guy Maor
- -->
-
- <p>
- Thirdly, the development package should contain a symlink for
- the shared library without a version number. For example, the
- <tt>libgdbm1-dev</tt> package should include a symlink from
- <tt>/usr/lib/libgdm.so</tt> to <tt>libgdm.so.1.7.3</tt>. This
- symlink is needed by <prgn>ld</prgn> when compiling packages
- as it will only look for <tt>libgdm.so</tt> and
- <tt>libgdm.a</tt> when compiling dynamically or statically,
- respectively.
- </p>
-
- <!--
- next paragraph changed by Christian Schwarz (see policy weekly #6)
- -->
-
- <p>
- Any package installing shared libraries in a directory that's listed
- in <tt>/etc/ld.so.conf</tt> or in one of the default library
- directories of <prgn>ld.so</prgn> (currently, these are <tt>/usr/lib</tt>
- and <tt>/lib</tt>) must call <prgn>ldconfig</prgn> in its <prgn>postinst</prgn>
- script if and only if the first argument is `configure'. However, it
- is important not to call <prgn>ldconfig</prgn> in the postrm or preinst
- scripts in the case where the package is being upgraded (see <ref
- id="unpackphase">), as <prgn>ldconfig</prgn> will see the temporary names
- that <prgn>dpkg</prgn> uses for the files while it is
- installing them and will make the shared library links point
- to them, just before <prgn>dpkg</prgn> continues the
- installation and removes the links!
- </p>
-
- <!--
- moved from section 2.2 , DMorris
- -->
-
- <sect id="shlibs"><heading>The <tt>shlibs</tt> File Format
- </heading>
-
- <p>
- This file is for use by <prgn>dpkg-shlibdeps</prgn> and is
- required when your package provides shared libraries.
- </p>
-
- <p>
- Each line is of the form:
- <example>
- <var>library-name</var> <var>version-or-soname</var> <var>dependencies ...</var>
- </example>
- </p>
-
- <p>
- <var>library-name</var> is the name of the shared library,
- for example <tt>libc5</tt>.
- </p>
-
- <p>
- <var>version-or-soname</var> is the soname of the library -
- ie, the thing that must exactly match for the library to be
- recognised by <prgn>ld.so</prgn>. Usually this is major
- version number of the library.
- </p>
-
- <p>
- <var>dependencies</var> has the same syntax as a dependency
- field in a binary package control file. It should give
- details of which package(s) are required to satisfy a binary
- built against the version of the library contained in the
- package. See <ref id="depsyntax">.
- </p>
-
- <p>
- For example, if the package <tt>foo</tt> contains
- <tt>libfoo.so.1.2.3</tt>, where the soname of the library is
- <tt>libfoo.so.1</tt>, and the first version of the package
- which contained a minor number of at least <tt>2.3</tt> was
- <var>1.2.3-1</var>, then the package's <var>shlibs</var>
- could say:
- <example>
- libfoo 1 foo (>= 1.2.3-1)
- </example>
- </p>
-
- <p>
- The version-specific dependency is to avoid warnings from
- <prgn>ld.so</prgn> about using older shared libraries with
- newer binaries.</p>
- </sect>
-
- <sect><heading>Further Technical information on
- <tt>shlibs</tt></heading>
-
-
- <!--
- following section mostly provided by Heiko Schlittermann
- edited by DMorris
- -->
-
- <sect1><heading><em>What</em> are the <tt>shlibs</tt> files?
- </heading>
-
- <p>
- The <tt>debian/shlibs</tt> file provides a way of checking
- for shared library dependencies on packaged binaries.
- They are intended to be used by package maintainers to
- make their lives easier.
- </p>
-
- <p>
- Other <tt>shlibs</tt> files that exist on a Debian system are
- <list>
- <item> <p><tt>/etc/dpkg/shlibs.default</tt></p></item>
- <item> <p><tt>/etc/dpkg/shlibs.override</tt></p></item>
- <item> <p><tt>/var/lib/dpkg/info/*.shlibs</tt></p></item>
- <item> <p><tt>debian/shlibs.local</tt></p></item>
- </list>
- These files are used by <prgn>dpkg-shlibdeps</prgn> when
- creating a binary package.</p>
- </sect1>
-
- <sect1><heading><em>How</em> does <prgn>dpkg-shlibdeps</prgn>
- work?
- </heading>
- <p>
- <prgn>dpkg-shlibdeps</prgn>
- determines the shared libraries directly
- <footnote>
- <p>
- Currently, it calls <prgn>ldd</prgn>, but in a
- forthcoming version it shall call <prgn>objdump</prgn>
- to to this. This however changes will need a couple of
- changes in the way that packages are build.
- </p>
- <p>
- Suppose a binary <tt>foo</tt> directly use a library
- <tt>libbar</tt> if it is linked with that
- library. Other libraries that are needed by
- <tt>libbar</tt> are linked indirectly to <tt>foo</tt>,
- and the dynamic linker will load the automatically
- when it loads <tt>libbar</tt>. Using <prgn>ldd</prgn>
- lists all the libraries, used direcly and indirectly;
- but <prgn>objdump</prgn> only lists the directly
- linked libraries. A package only needs to depend on
- the libraries it is directly linked to, since the
- dependencies for those libraries should automatically
- pull in the other libraries.</p>
-
- <p>
- This change does mean a change in the way packages are
- build though: currently dpkg-shlibdeps is only run on
- binaries. But since we will now depend on the
- libraries to depend on the libraries they need the
- packages containing those libraries will need to run
- dpkg-shlibdeps on the libraries.
- </p>
- <p>
- A good example where this would help us is the current
- mess with multiple version of the mesa library. With
- the ldd-based system every package that uses mesa need
- to add a dependency on svgalib|svgalib-dummy in order
- to handle the glide mesa variant. With an
- objdump-based system this isn't necessary anymore and
- would have saved everyone a lot of work.
- </p>
- <p>
- Another example: we could update libimlib with a new
- version that supports a new graphics format called
- dgf. If we use the old ldd method every package that
- uses libimlib would need to be recompiled so it would
- also depend on libdgf or it wouldn't run due to
- missing symbols. However with the new system packages
- using libimlib can depend on libimlib itself having
- the dependency on libgdh and wouldn't need to be
- updated.
- </p>
- </footnote>
- used by the compiled binaries (and libraries, in a version
- of <prgn>dpkg-shlibdeps</prgn> coming soon) passed through
- on its command line.
- </p>
-
- <p>
- For each shared library, <prgn>dpkg-shlibdeps</prgn> needs to know
- <list compact="compact">
- <item><p>the package containing the library, and</p></item>
- <item><p>the library version number,</p></item>
-
- </list> <p>
- it scans the following files in this order.
- <enumlist compact="compact">
- <item><p><tt>debian/shlibs.local</tt></p></item>
- <item><p><tt>/etc/dpkg/shlibs.override</tt></p></item>
- <item><p><tt>/var/lib/dpkg/info/*.shlibs</tt></p></item>
- <item><p><tt>/etc/dpkg/shlibs.default</tt></p></item>
- </enumlist></p>
- </sect1>
-
- <sect1><heading><em>Who</em> maintains the various
- <tt>shlibs</tt> files?
- </heading>
-
- <p>
- <list compact="compact">
- <item>
- <p><tt>/etc/dpkg/shlibs.default</tt> - the maintainer
- of dpkg</p>
- </item>
- <item>
- <p>
- <tt>/var/lib/dpkg/info/<var>package</var>.shlibs</tt>
- - the maintainer of each package</p>
- </item>
- <item>
- <p>
- <tt>/etc/dpkg/shlibs.override</tt> - the local
- system administrator</p>
- </item>
- <item>
- <p><tt>debian/shlibs.local</tt> - the maintainer of
- the package
- </p>
- </item>
- </list>
- The <tt>shlibs.default</tt> file is managed by
- <prgn>dpkg</prgn>. The entries in <tt>shlibs.default</tt>
- that are provided by <prgn>dpkg</prgn> are just there to
- fix things until the shared library packages all have
- <tt>shlibs</tt> files.
- </p>
- </sect1>
-
- <sect1><heading><em>How</em> to use <prgn>dpkg-shlibdeps</prgn> and
- the <tt>shlibs</tt> files?
- </heading>
-
- <sect2><heading>If your package doesn't provide a shared
- library
- </heading>
-
- <p>
- Put a call to <prgn>dpkg-shlibdeps</prgn> into your
- <tt>debian/rules</tt> file. If your package contains
- only binaries (e.g. no scripts) use:
- <example>
- dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/*
- </example>
- If <prgn>dpkg-shlibdeps</prgn> doesn't complain, you're
- done. If it does complain you might need to create your
- own <tt>debian/shlibs.local</tt> file.</p>
- </sect2>
-
- <sect2><heading>If your package provides a shared library
- </heading>
-
- <p>
- Create a <tt>debian/shlibs</tt> file and let
- <tt>debian/rules</tt> install it in the control area:
- <example>
- install -m644 debian/shlibs debian/tmp/DEBIAN
- </example>
- If your package contains additional binaries see above.
- </p>
- </sect2>
- </sect1>
-
- <sect1><heading><em>How</em> to write
- <tt>debian/shlibs.local</tt>
- </heading>
-
- <p>
- This file is intended only as a <em>temporary</em> fix if
- your binaries depend on a library which doesn't provide
- its own <tt>/var/lib/dpkg/info/*.shlibs</tt> file yet.
- </p>
-
- <p>
- Let's assume you are packaging a binary <tt>foo</tt>. Your
- output in building the package might look like this.
- <example>
- $ ldd foo
- libbar.so.1 => /usr/X11R6/lib/libbar.so.1.0
- libc.so.5 => /lib/libc.so.5.2.18
- libX11.so.6 => /usr/X11R6/lib/libX11.so.6.0
- </example>
- And when you ran <prgn>dpkg-shlibdeps</prgn>
- <example>
- $ dpkg-shlibdeps -o foo
- dpkg-shlibdeps: warning: unable to find dependency information
- for shared library libbar
- (soname 1, path /usr/X11R6/lib/libbar.so.1.0, dependency field Depends)
- shlibs:Depends=elf-x11r6lib, libc5 (>= 5.2.18)
- </example>
- The <prgn>foo</prgn> binary depends on the
- <prgn>libbar</prgn> shared library, but no package seems
- to provide a <tt>*.shlibs</tt> file in
- <tt></tt>var/lib/dpkg/info/. Let's determine the package
- responsible:
- </p>
-
- <p>
- <example>
- $ dpkg -S /usr/X11R6/lib/libbar.so.1.0
- bar1: /usr/X11R6/lib/libbar.so.1.0
- $ dpkg -s bar1 | grep Version
- Version: 1.0-1
- </example>
- This tells us that the <prgn>bar1</prgn> package, version
- 1.0-1 is the one we are using. Now we can create our own
- <tt>debian/shlibs.local</tt> to temporarly fix the above
- problem. Include the following line into your
- <tt>debian/shlibs.local</tt> file.
- <example>
- libbar 1 bar1 (>= 1.0-1)
- </example>
- Now your package build should work. As soon as the
- maintainer of <prgn>libbar1</prgn> provides a
- <tt>shlibs</tt> file, you can remove your
- <tt>debian/shlibs.local</tt> file.
- </p>
- </sect1>
- </sect>
- </chapt>
-
- <chapt id="methif"><heading><prgn>dselect</prgn>'s interface to
- its installation methods
- </heading>
-
- <p>
- <prgn>dselect</prgn> calls scripts from its installation
- methods when it needs to actually access data from the
- distribution. The core program <prgn>dselect</prgn> itself
- just calls these scripts and provides the package and access
- method selection interfaces. The installation methods are
- responsible for invoking <prgn>dpkg</prgn> as appropriate.
- </p>
-
- <p>
- Each installation method has three scripts:
- <list compact="compact">
- <item><p>Setup installation parameters.</p></item>
- <item><p>Update list of available packages.</p></item>
- <item><p>Install.</p></item>
- </list>
-
- <p>
- <prgn>dselect</prgn> searches for methods in
- <tt>/usr/lib/dpkg/methods</tt> and
- <tt>/usr/local/lib/dpkg/methods</tt>.
- </p>
-
- <sect><heading>Functions of the method scripts
- </heading>
-
- <p>
- The setup script is run just after the user has chosen an
- installation method. It should prompt the user for
- parameters like the site to NFS-mount or FTP from, the
- directory to use, or the directory or filesystem where the
- <tt>.deb</tt> files can be found, or the tape or floppy
- device to install from. It should store the responses under
- <tt>/var/lib/dpkg/methods</tt> - see below. If no available
- packages list is available it should perhaps offer to scan
- the available packages.
- </p>
-
- <p>
- The update script should obtain a list of available packages
- if possible, and run <tt>dpkg --update-avail</tt>, <tt>dpkg
- --merge-avail</tt> and/or <tt>dpkg --forget-old-unavail</tt>
- to load it into <prgn>dpkg</prgn> and <prgn>dselect</prgn>'s
- database of available packages. If no packages list was
- available and the user was offered and accepted the option
- of scanning the actual files available this scan should be
- done here, using <tt>dpkg --record-avail</tt>.
- </p>
-
- <p>
- The install script should feed all the available
- <tt>.deb</tt> files to <tt>dpkg --iGOEB</tt> (this is
- equivalent to <tt>dpkg --install
- --refuse-downgrade --selected-only --skip-same-version
- --auto-deconfigure</tt>). The <tt>-R</tt>
- (<tt>--recursive</tt>) option for traversing subdirectories
- may also be useful here).
- </p>
-
- <p>
- If any of these scripts needs to display a message for the
- user, it should wait for the user to hit `return' before
- exiting so that dselect doesn't immediately rewrite the
- screen.
- </p>
-
- <p>
- If a method script succeeds (returns a zero exit status)
- <prgn>dselect</prgn> will return immediately to the main
- menu, with the `next' option highlighted ready for the user
- to select it. If it fails <prgn>dselect</prgn> will display
- a message and wait for the user to hit return.</p>
- </sect>
-
- <sect><heading>Location and arguments of the method scripts
- </heading>
-
- <p>
- A set of scripts (henceforth known as a group) may provide
- several methods on the `main menu' with different behaviour.
- For example, there might be a generic get-packages-by-FTP
- group which might provide methods in the main menu for
- installation directly from one of the Debian mirror sites as
- well as for installation from a user-specified site.
- </p>
-
- <p>
- Each group of methods implemented by the same set of scripts
- should have a subdirectory
- <tt>/usr/lib/dpkg/methods/<var>group</var></tt> or
- <tt>/usr/local/lib/dpkg/methods/<var>group</var></tt>,
- containing:
- <taglist compact="compact">
- <tag><tt>names</tt></tag>
- <item><p>a list of user-visible methods provided by these scripts.</p>
- </item>
- <tag><tt>setup</tt></tag>
- <tag><tt>update</tt></tag>
- <tag><tt>install</tt></tag>
- <item><p>executable programs, the scripts themselves.</p>
- </item>
- <tag><tt>desc.<var>option</var></tt></tag>
- <item><p>description file.</p></item>
- </taglist>
- </p>
-
- <p>
- <tt>names</tt> will be formatted as a list of lines, each containing:
- <example>
- <var>sequence</var> <var>method</var> <var>summary</var>
- </example>
- </p>
- <p>
- <var>sequence</var> is a two-digit number that will be used
- much like <tt>rc.d</tt> prefixes to control the order in the
- main menu. If in doubt use 50.
- </p>
-
- <p>
- <var>method</var> is a name which is displayed by
- <prgn>dselect</prgn> as the name of the method, and which
- will be passed to <tt>setup</tt>, <tt>update</tt> and
- <tt>unpack</tt> as their first argument.
- </p>
-
- <p>
- <var>summary</var> is the brief description string for
- <prgn>dselect</prgn>'s menu.
- </p>
-
- <p>
- Each of the three scripts gets the same three arguments:
- <var>vardir</var>, <var>group</var> and <var>method</var>.
- <var>vardir</var> is the base directory for storing
- <prgn>dpkg</prgn> and <prgn>dselect</prgn>'s state, usually
- <tt>/var/lib/dpkg</tt>; this is passed in so that the
- <tt>--admindir</tt> option to <prgn>dselect</prgn> is
- honoured).
- </p>
-
- <p>
- Each option may have an extended description in
- <tt>desc.<var>option</var></tt>. This should be formatted
- like the extended description part of a <tt>Description</tt>
- field entry <em>shifted one character to the left</em>.
- </p>
-
- <p>
- <tt><var>vardir</var>/methods</tt> will exist, and a method
- group may use a
- <tt><var>vardir</var>/methods/<var>group</var></tt>
- directory to store its state.
- </p>
-
- <p>
- The group name and method name must follow the rules for C
- identifiers.
- </p>
- </sect>
- </chapt>
-
- <chapt id="conversion"><heading>Conversion procedure from old
- source packages
- </heading>
-
- <p>
- This is a brief summary of the procedure for converting a
- pre-2.0.0.0-format source package into the new format.
- </p>
-
- <p>
- You are strongly advised to download and examine the <prgn>hello</prgn>
- package, and to read the section in the <prgn>dpkg</prgn> programmers'
- manual describing the source packaging tools. More detail about the
- exact functionality of these tools is available in
- <manref name="dpkg-source" section="1">.
- </p>
-
- <p>
- <list>
- <item>
- <p>
- Download the original source code from wherever it can
- be found and do any rearrangement required to make it
- look like the original tree of the Debian source. Put
- it in
- <tt><var>package</var>-<var>upstream-version</var>.orig/</tt>
- or
- <tt><var>package</var>_<var>upstream-version</var>.orig.tar.gz</tt>.
- </p>
- </item>
-
- <item>
- <p>
- Rename all files <tt>debian.*</tt> to <tt>debian/*</tt>.
- There may be some exceptions to this, but this is a good
- start.</p>
- </item>
-
- <item>
- <p>
- Edit the <tt>debian/changelog</tt> - create or rename it
- if necessary. Add a new revision to the top with the
- appropriate details, and a local variables entry to the
- bottom to set Emacs to the right mode:
- <example>
- Local variables:
- mode: debian-changelog
- End:
- </example>
- </p>
- </item>
-
- <item>
- <p>
- Edit/create <tt>debian/control</tt>:
- <list compact="compact">
- <item>
- <p>
- Remove the <tt>Version</tt> field. If it is
- generated unusually (not equal to the source
- version) you must use the -v option to
- dpkg-gencontrol (see below). <tt>Section</tt>,
- <tt>Priority</tt>, <tt>Maintainer</tt> go above
- the first blank line, most of the rest
- below.
- </p>
- </item>
-
- <item>
- <p>
- Reorder the fields and add a blank line at an
- appropriate point, separating the source package
- fields from the binary package fields.
- </p>
- </item>
-
- <item>
- <p>Add the <tt>Source</tt> field.</p></item>
-
- <item>
- <p>
- Add the <tt>Standards-Version</tt> field. (Please
- check out the Debian Policy Manual for details
- about this field.)</p>
- </item>
-
- <item>
- <p>
- Change the <tt>Architecture</tt> field for each
- package to <tt>any</tt>, <tt>all</tt> or whatever.
- If there isn't an <tt>Architecture</tt> field add
- one.</p>
- </item>
-
- <item>
- <p>
- If any other use of sed or things used to happen
- to make the binary control files use
- <prgn>dpkg-gencontrol</prgn>'s variable
- substitution features to achieve the same effect.
- Use <tt>debian/substvars</tt> if you need to put
- unusally-generated information (apart from details
- of <tt>.deb</tt> files) in the <tt>.changes</tt>
- file too.</p>
- </item>
- </list>
- </p>
- </item>
-
- <item>
- <p>Edit the <tt>debian/rules</tt>:
- <list compact="compact">
- <item>
- <p>
- Remove the <prgn>source</prgn> and
- <prgn>diff</prgn> and any <prgn>changes</prgn> and
- <prgn>dist</prgn> targets. These things now
- happen in a package-independent way and are not
- done by <tt>debian/rules</tt>.</p>
- </item>
- <item>
- <p>
- Split the <prgn>binary</prgn> target into
- <prgn>binary-arch</prgn> and
- <prgn>binary-indep</prgn>; in many cases all of
- <prgn>binary</prgn> should go into
- <prgn>binary-arch</prgn>. Create the
- <prgn>binary</prgn> target and the unused of the
- two other <prgn>binary-*</prgn> targets if there
- is one - you can copy the ones from the
- <prgn>hello</prgn> package.</p>
- </item>
- <item>
- <p>
- Change the <prgn>binary</prgn> target to use
- <prgn>dpkg-gencontrol</prgn> to make the package
- control file(s). Move it to after all the files
- have been installed but just before the last
- <prgn>chown</prgn> and <prgn>chmod</prgn> in the
- target.</p>
- </item>
- <item>
- <p>
- Change occurrences of <tt>debian-tmp</tt> to
- <tt>debian/tmp</tt>.</p>
- </item>
- <item>
- <p>
- Change occurrences of
- <tt>debian.{post,pre}{inst,rm}</tt> to
- <tt>debian/*</tt>.</p>
- </item>
- <item>
- <p>
- Remove the version number setting at the top, if
- there is one.</p>
- </item>
- <item>
- <p>
- Ensure that the package's Debian-specific and
- upstream changelogs are installed.</p>
- </item>
- </list>
- </p>
- </item>
-
- <item>
- <p>
- Change the package to use <prgn>dpkg-shlibdeps</prgn> to
- determine its shared library dependencies and substitute
- them in. Shared library dependencies should no longer
- be hardwired in the source package.</p>
- </item>
-
- <item>
- <p>
- Check that the <tt>debian/README</tt> is really the
- copyright file, and if so rename it to
- <tt>debian/copyright</tt> and edit <tt>debian/rules</tt>
- to cope with this and to change the installation of the
- copyright file from
- <tt>/usr/doc/<var>package</var>/copyright</tt> to
- <tt>/usr/doc/copyright/<var>package</var></tt>. If it
- isn't then find <tt>debian/copyright</tt> and decide
- what to do with the <tt>README</tt>.</p>
- </item>
-
- <item>
- <p>Check for various other anachronisms and problems:
- <list compact="compact">
- <item>
- <p>
- Remove any <tt>Package_Revision</tt>,
- <tt>Package-Revision</tt> or <tt>Revision</tt>
- fields.</p>
- </item>
- <item>
- <p>
- Rename <tt>Optional</tt> to <tt>Suggests</tt>,
- <tt>Recommended</tt> to
- <tt>Recommends</tt>.</p>
- </item>
- <item>
- <p>
- Change
- <tt>/usr/doc/examples/<var>package</var></tt> to
- <tt>/usr/doc/<var>package</var>/examples</tt>.</p>
- </item>
- <item>
- <p>
- Make sure that manpages are installed
- compressed.</p>
- </item>
- <item>
- <p>
- Check that the description has an extended
- description, is well-formatted and meaningful and
- helpful to people wanting to know whether to
- install a package.</p>
- </item>
- </list>
- </p>
- </item>
-
- <item>
- <p>Look everything over.</p></item>
-
- <item>
- <p>
- Do a test build using <tt>dpkg-buildpackage -us -uc -sa
- -r<var>whatever</var></tt>. Check the permissions and
- locations of files in the resulting package by examining
- the output of <tt>dpkg-deb --contents</tt>, and check
- that the source build happened OK. Test install the
- binary package(s) and test extract the source
- package(s).</p>
- </item>
-
- <item>
- <p>
- Sign the release: either rebuild everything with
- <tt>dpkg-buildpackage -sa</tt>, or PGP-sign the
- <tt>.dsc</tt>, rebuild the <tt>.changes</tt> using
- <tt>dpkg-genchanges -sa</tt>, and then PGP-sign the
- <tt>.changes</tt>.</p>
- </item>
-
- </list>
- </p>
-
- <p>
- The use of <tt>-sa</tt> on <prgn>dpkg-buildpackage</prgn> and
- <prgn>dpkg-genchanges</prgn> is important when doing the first
- build/uploading of a new-format source package. Unless this
- happens to be Debian revision <tt>0</tt> or <tt>1</tt> by
- default the original source tarfile will not be included in
- the uploaded files listed in the <tt>.changes</tt> file, and
- so it won't be installed on the FTP site. <tt>-sa</tt>
- requests that the original source be included
- regardless.</p>
- </chapt>
-
- </book>
-</debiandoc>
<tt>/usr/share/common-licences/GPL</tt> in the Debian GNU/Linux
distribution or on the World Wide Web at
<url id="http://www.gnu.org/copyleft/gpl.html"
- name="The GNU Public Licence">. You can also obtain it by writing to the
+ name="The GNU Public Licence">. You can also obtain it by writing to the
Free Software Foundation, Inc., 59 Temple Place - Suite 330,
Boston, MA 02111-1307, USA.
</p>
operating system, as well as technical requirements that
each package must satisfy to be included in the
distribution.
- </p>
+ </p>
+
+
+ <p>
+ This manual also describes Debian policy as it relates to
+ creating Debian packages. It is not a tutorial on how to build
+ packages, nor is it exhaustive where it comes to describing
+ the behavior of the packaging system. Instead, this manual
+ attempts to define the interface to the package management
+ system that the developers have to be conversant with.
+ <footnote>
+ <p>
+ Informally, the criteria used for inclusion is that the
+ material meet one of the following requirements:
+ <taglist>
+ <tag>Standard interfaces</tag>
+ <item>
+ <p>
+ The material presented represents an interface to
+ the packaging system that is mandated for use, and
+ is used by, a significant number of packages, and
+ should not be changed without peer review. Package
+ maintainers can then rely on this interfaces not
+ changing, and the package management software
+ authors need to ensure compatibility with these
+ interface definitions. (control file and and
+ changelog file formats are one example)
+ </p>
+ </item>
+ <tag>Chosen Convention</tag>
+ <item>
+ <p>
+ If there are a number of technically viable choices
+ that can be made, but one needs to select one of
+ these options for inter-operability. The version
+ number format is one example.
+ </p>
+ </item>
+ </taglist>
+ Please note that these are not mutually exclusive;
+ selected conventions often become parts of standard
+ interfaces.
+ </p>
+ </footnote>
+ </p>
+
+ <p>
+ Please note that the footnotes present in this manual are
+ merely informative, and are not part of Debian policy itself.
+ </p>
+
+
<p>
In this manual, the words <em>must</em>, <em>should</em> and
- <em>may</em>, and the adjectives <em>required></em>,
+ <em>may</em>, and the adjectives <em>required</em>,
<em>recommended</em> and <em>optional</em>, are used to
distinguish the significance of the various guidelines in
this policy document. Packages that do not conform the the
<p>Also see RFC 2119.</p>
</footnote>
</p>
- <p>
- This manual does <em>not</em> describe the technical
- mechanisms involved in package creation, installation, and
- removal. This information can be found in the <em>Debian
- Packaging Manual</em> and the <em>Debian System
- Administrators' Manual</em>. Please note that the
- footnotes present in this manual are merely informative,
- and are not part of Debian policy itself.
- </p>
- <p>
- This document assumes familiarity with these other two
- manuals. Unfortunately, the <em>System Administrators'
- Manual</em> does not exist yet.
- </p>
<p>
Much of the information presented in this manual will be
useful even when building a package which is to be
<ftppath>/debian/doc/package-developer/debian-policy.html.tar.gz</ftppath>
or from the Debian WWW server at
<url id="http://www.debian.org/doc/debian-policy/"
- name="The Debian Policy Manual">.</p>
+ name="The Debian Policy Manual">.</p>
<p>
In addition, this manual is distributed via the Debian package
<p>
The Debian GNU/Linux system is maintained and distributed as a
collection of <em>packages</em>. Since there are so many of them (over
- 2600) they are split into <em>sections</em> and <em>priorities</em> to
+ 5000) they are split into <em>sections</em> and <em>priorities</em> to
simplify handling of them.
</p>
<p>
<em>free</em> in our sense (see Debian Free Software
Guidelines, below), or may be imported/exported without
restrictions. Thus, the archive is split into the sections
- <em>main</em>, <em>non-free</em>, <em>contrib</em>,
- <em>non-US/main</em>, <em>non-US/non-free</em>, and
- <em>non-US/contrib</em>.</p>
+ <em>main</em>, <em>non-free</em>, <em>contrib</em>,
+ <em>non-US/main</em>, <em>non-US/non-free</em>, and
+ <em>non-US/contrib</em>.</p>
<p>
The <em>main</em> and the <em>non-US/main</em> sections form
<p>We want to encourage everyone to write free software.</p>
</item>
<item>
-
<p> We want to make it easy for people to produce
+ <p> We want to make it easy for people to produce
CD-ROMs of our system without violating any licenses,
import/export restrictions, or any other laws.</p>
</item>
</list>
</p>
- <sect1>
- <heading>The Debian Free Software Guidelines</heading>
- <p>
- The Debian Free Software Guidelines (DFSG) is our
- definition of `free' software.
- <taglist>
- <tag>Free Redistribution
- </tag>
- <item>
- <p>
- The license of a Debian component may not restrict any
- party from selling or giving away the software as a
- component of an aggregate software distribution
- containing programs from several different
- sources. The license may not require a royalty or
- other fee for such sale.
- </p>
- </item>
- <tag>Source Code
- </tag>
- <item>
- <p>
- The program must include source code, and must allow
- distribution in source code as well as compiled form.
- </p>
- </item>
- <tag>Derived Works
- </tag>
- <item>
- <p>
- The license must allow modifications and derived
- works, and must allow them to be distributed under the
- same terms as the license of the original software.
- </p>
- </item>
- <tag>Integrity of The Author's Source Code
- </tag>
- <item>
- <p>
- The license may restrict source-code from being
- distributed in modified form <em>only</em> if the
- license allows the distribution of ``patch files''
- with the source code for the purpose of modifying the
- program at build time. The license must explicitly
- permit distribution of software built from modified
- source code. The license may require derived works to
- carry a different name or version number from the
- original software. (This is a compromise. The Debian
- group encourages all authors to not restrict any
- files, source or binary, from being modified.)
- </p>
- </item>
- <tag>No Discrimination Against Persons or Groups
- </tag>
- <item>
- <p>
- The license must not discriminate against any person
- or group of persons.
- </p>
- </item>
- <tag>No Discrimination Against Fields of Endeavor
- </tag>
- <item>
- <p>
- The license must not restrict anyone from making use
- of the program in a specific field of endeavor. For
- example, it may not restrict the program from being
- used in a business, or from being used for genetic
- research.
- </p>
- </item>
- <tag>Distribution of License
- </tag>
- <item>
- <p>
- The rights attached to the program must apply to all
- to whom the program is redistributed without the need
- for execution of an additional license by those
- parties.
- </p>
- </item>
- <tag>License Must Not Be Specific to Debian
- </tag>
- <item>
- <p>
- The rights attached to the program must not depend on
- the program's being part of a Debian system. If the
- program is extracted from Debian and used or
- distributed without Debian but otherwise within the
- terms of the program's license, all parties to whom
- the program is redistributed must have the same
- rights as those that are granted in conjunction with
- the Debian system.
- </p>
- </item>
- <tag>License Must Not Contaminate Other Software
- </tag>
- <item>
- <p>
- The license must not place restrictions on other
- software that is distributed along with the licensed
- software. For example, the license must not insist
- that all other programs distributed on the same medium
- must be free software.
- </p>
- </item>
- <tag>Example Licenses
- </tag>
- <item>
- <p>
- The ``GPL,'' ``BSD,'' and ``Artistic'' licenses are
- examples of licenses that we consider <em>free</em>.
- </p>
- </item>
- </taglist>
- </p>
- </sect1>
- <sect1>
- <heading>The main section</heading>
- <p>
- Every package in "main" must comply with the DFSG (Debian
- Free Software Guidelines).</p>
-
- <p>
- In addition, the packages in "main"
- <list compact="compact">
- <item>
- <p>
- must not require a package outside of "main" for
- compilation or execution (thus, the package must not
- declare a "Depends" or "Recommends" relationship on a
- non-main package),
- </p>
- </item>
- <item>
- <p>
- should not be so buggy that we refuse to support them,
- </p>
- </item>
- <item>
- <p>
- should meet all policy requirements presented in this
- manual.
- </p>
- </item>
- </list>
- </p>
- </sect1>
- <sect1>
- <heading>The contrib section</heading>
- <p>
- Every package in "contrib" must comply with the DFSG.
- </p>
+ <sect1>
+ <heading>The Debian Free Software Guidelines</heading>
+ <p>
+ The Debian Free Software Guidelines (DFSG) is our
+ definition of `free' software.
+ <taglist>
+ <tag>Free Redistribution
+ </tag>
+ <item>
+ <p>
+ The license of a Debian component may not restrict any
+ party from selling or giving away the software as a
+ component of an aggregate software distribution
+ containing programs from several different
+ sources. The license may not require a royalty or
+ other fee for such sale.
+ </p>
+ </item>
+ <tag>Source Code
+ </tag>
+ <item>
+ <p>
+ The program must include source code, and must allow
+ distribution in source code as well as compiled form.
+ </p>
+ </item>
+ <tag>Derived Works
+ </tag>
+ <item>
+ <p>
+ The license must allow modifications and derived
+ works, and must allow them to be distributed under the
+ same terms as the license of the original software.
+ </p>
+ </item>
+ <tag>Integrity of The Author's Source Code
+ </tag>
+ <item>
+ <p>
+ The license may restrict source-code from being
+ distributed in modified form <em>only</em> if the
+ license allows the distribution of ``patch files''
+ with the source code for the purpose of modifying the
+ program at build time. The license must explicitly
+ permit distribution of software built from modified
+ source code. The license may require derived works to
+ carry a different name or version number from the
+ original software. (This is a compromise. The Debian
+ group encourages all authors to not restrict any
+ files, source or binary, from being modified.)
+ </p>
+ </item>
+ <tag>No Discrimination Against Persons or Groups
+ </tag>
+ <item>
+ <p>
+ The license must not discriminate against any person
+ or group of persons.
+ </p>
+ </item>
+ <tag>No Discrimination Against Fields of Endeavor
+ </tag>
+ <item>
+ <p>
+ The license must not restrict anyone from making use
+ of the program in a specific field of endeavor. For
+ example, it may not restrict the program from being
+ used in a business, or from being used for genetic
+ research.
+ </p>
+ </item>
+ <tag>Distribution of License
+ </tag>
+ <item>
+ <p>
+ The rights attached to the program must apply to all
+ to whom the program is redistributed without the need
+ for execution of an additional license by those
+ parties.
+ </p>
+ </item>
+ <tag>License Must Not Be Specific to Debian
+ </tag>
+ <item>
+ <p>
+ The rights attached to the program must not depend on
+ the program's being part of a Debian system. If the
+ program is extracted from Debian and used or
+ distributed without Debian but otherwise within the
+ terms of the program's license, all parties to whom
+ the program is redistributed must have the same
+ rights as those that are granted in conjunction with
+ the Debian system.
+ </p>
+ </item>
+ <tag>License Must Not Contaminate Other Software
+ </tag>
+ <item>
+ <p>
+ The license must not place restrictions on other
+ software that is distributed along with the licensed
+ software. For example, the license must not insist
+ that all other programs distributed on the same medium
+ must be free software.
+ </p>
+ </item>
+ <tag>Example Licenses
+ </tag>
+ <item>
+ <p>
+ The ``GPL,'' ``BSD,'' and ``Artistic'' licenses are
+ examples of licenses that we consider <em>free</em>.
+ </p>
+ </item>
+ </taglist>
+ </p>
+ </sect1>
+ <sect1>
+ <heading>The main section</heading>
+ <p>
+ Every package in "main" and "non-US/main" must comply with
+ the DFSG (Debian Free Software Guidelines).</p>
+
+ <p>
+ In addition, the packages in "main"
+ <list compact="compact">
+ <item>
+ <p>
+ must not require a package outside of "main" for
+ compilation or execution (thus, the package must not
+ declare a "Depends", "Recommends", or "Build-Depends"
+ relationship on a non-main package),
+ </p>
+ </item>
+ <item>
+ <p>
+ must not be so buggy that we refuse to support them,
+ </p>
+ </item>
+ <item>
+ <p>
+ must meet all policy requirements presented in this
+ manual.
+ </p>
+ </item>
+ </list>
+ </p>
+ <p>
+ Similarly, the packages in "non-US/main"
+ <list compact="compact">
+ <item>
+ <p>
+ must not require a package outside of "main" or
+ "non-US/main" for compilation or execution,
+ </p>
+ </item>
+ <item>
+ <p>
+ must not be so buggy that we refuse to support them,
+ </p>
+ </item>
+ <item>
+ <p>
+ must meet all policy requirements presented in this
+ manual.
+ </p>
+ </item>
+ </list>
+ </p>
+ </sect1>
+ <sect1>
+ <heading>The contrib section</heading>
+ <p>
+ Every package in "contrib" and "non-US/contrib" must
+ comply with the DFSG.
+ </p>
- <p>
- Examples of packages which would be included in "contrib" are
- <list compact="compact">
- <item>
- <p>
- free packages which require "contrib", "non-free", or
- "non-US" packages or packages which are not in our
- archive at all for compilation or execution,
- </p>
- </item>
- <item>
- <p>
- wrapper packages or other sorts of free accessories for
- non-free programs,
- </p>
- </item>
- </list>
- </p>
- </sect1>
- <sect1>
- <heading>The non-free section</heading>
- <p>
- `Non-free' contains packages which are not compliant with
- the DFSG.</p>
- <p>
- All packages in `non-free' must be electronically
- distributable across international borders.
- </p>
- </sect1>
- <sect1>
- <heading>The non-us server</heading>
- <p>
- Some programs with cryptographic program code need to be stored
- on the "non-us" server because of export restrictions of the
- U.S.</p>
- <p>
- This applies only to packages which contain cryptographic
- code. A package containing a program with an interface to a
- cryptographic program or a program that's dynamically linked
- against a cryptographic library should not be distributed
- via the non-us server if it is capable of running without the
- cryptography library or program.
- </p>
- </sect1>
- <sect1>
- <heading>Further copyright considerations</heading>
- <p>
- Every package must be accompanied by a verbatim copy of its
- copyright and distribution license in the file
- /usr/share/doc/<package-name>/copyright (see <ref
- id="copyrightfile"> for details).</p>
- <p>
- We reserve the right to restrict files from being included
- anywhere in our archives if
- <list compact="compact">
- <item>
- <p>
- their use or distribution would break a law,
- </p>
- </item>
- <item>
- <p>
- there is an ethical conflict in their distribution or
- use,
- </p>
- </item>
- <item>
- <p>
- we would have to sign a license for them, or
- </p>
- </item>
- <item>
- <p>
- their distribution would conflict with other project
- policies.
- </p>
- </item>
- </list>
- </p>
+ <p>
+ Examples of packages which would be included in "contrib"
+ or "non-US/contrib" are
+ <list compact="compact">
+ <item>
+ <p>
+ free packages which require "contrib", "non-free"
+ packages or packages which are not in our
+ archive at all for compilation or execution,
+ </p>
+ </item>
+ <item>
+ <p>
+ wrapper packages or other sorts of free accessories for
+ non-free programs,
+ </p>
+ </item>
+ </list>
+ </p>
+ </sect1>
+ <sect1>
+ <heading>The non-free section and non-US/non-free </heading>
+ <p>
+ Packages must be placed in "non-free" or "non-US/non-free"
+ if they are not compliant with the DFSG or are encumbered
+ by patents or other legal issues that make their
+ distribution problematic.
+ </p>
+ </sect1>
+ <sect1>
+ <heading>The non-US sections</heading>
+ <p>
+ Some programs with cryptographic program code need to be stored
+ on the "non-US" server because of export restrictions of the
+ U.S. Such programs must be distributed in the appropriate
+ non-US section, either non-US/main, non-US/contrib or
+ non-US/non-free. </p>
+ <p>
+ This applies only to packages which contain cryptographic
+ code. A package containing a program with an interface to a
+ cryptographic program or a program that's dynamically linked
+ against a cryptographic library should not be distributed
+ via the non-us server if it is capable of running without the
+ cryptography library or program.
+ </p>
+ </sect1>
+ <sect1>
+ <heading>Further copyright considerations</heading>
+ <p>
+ Every package must be accompanied by a verbatim copy of its
+ copyright and distribution license in the file
+ /usr/share/doc/<package-name>/copyright (see
+ <ref id="copyrightfile"> for details).</p>
+ <p>
+ We reserve the right to restrict files from being included
+ anywhere in our archives if
+ <list compact="compact">
+ <item>
+ <p>
+ their use or distribution would break a law,
+ </p>
+ </item>
+ <item>
+ <p>
+ there is an ethical conflict in their distribution or
+ use,
+ </p>
+ </item>
+ <item>
+ <p>
+ we would have to sign a license for them, or
+ </p>
+ </item>
+ <item>
+ <p>
+ their distribution would conflict with other project
+ policies.
+ </p>
+ </item>
+ </list>
+ </p>
- <p>
- Programs whose authors encourage the user to make donations
- are fine for the main distribution, provided that the
- authors do not claim that not donating is immoral,
- unethical, illegal or something similar; otherwise they must
- go in non-free.</p>
+ Programs whose authors encourage the user to make donations
+ are fine for the main distribution, provided that the
+ authors do not claim that not donating is immoral,
+ unethical, illegal or something similar; otherwise they must
+ go in non-free.</p>
- <p>
- Packages whose copyright permission notices (or patent
- problems) do not allow redistribution even of only binaries,
- and where no special permission has been obtained, must not be
- placed on the Debian FTP site and its mirrors at all.</p>
+ Packages whose copyright permission notices (or patent
+ problems) do not allow redistribution even of only binaries,
+ and where no special permission has been obtained, must not be
+ placed on the Debian FTP site and its mirrors at all.</p>
- <p>
- Note, that under international copyright law (this applies
- in the United States, too) <em>no</em> distribution or
- modification of a work is allowed without an explicit notice
- saying so. Therefore a program without a copyright notice
- <em>is</em> copyrighted and you may not do anything to it
- without risking being sued! Likewise if a program has a
- copyright notice but no statement saying what is permitted
- then nothing is permitted.</p>
+ Note, that under international copyright law (this applies
+ in the United States, too) <em>no</em> distribution or
+ modification of a work is allowed without an explicit notice
+ saying so. Therefore a program without a copyright notice
+ <em>is</em> copyrighted and you may not do anything to it
+ without risking being sued! Likewise if a program has a
+ copyright notice but no statement saying what is permitted
+ then nothing is permitted.</p>
- <p>
- Many authors are unaware of the problems that restrictive
- copyrights (or lack of copyright notices) can cause for the
- users of their supposedly-free software. It is often
- worthwhile contacting such authors diplomatically to ask
- them to modify their license terms. However, this is a
- politically difficult thing to do and you should ask for
- advice on <tt>debian-legal</tt> first.</p>
+ Many authors are unaware of the problems that restrictive
+ copyrights (or lack of copyright notices) can cause for the
+ users of their supposedly-free software. It is often
+ worthwhile contacting such authors diplomatically to ask
+ them to modify their license terms. However, this is a
+ politically difficult thing to do and you should ask for
+ advice on <tt>debian-legal</tt> first.</p>
- <p>
- When in doubt, send mail to
- <email>debian-legal@lists.debian.org</email>. Be prepared
- to provide us with the copyright statement. Software
- covered by the GPL, public domain software and BSD-like
- copyrights are safe; be wary of the phrases `commercial use
- prohibited' and `distribution restricted'.</p>
- </sect1>
- <sect1>
- <heading>Subsections</heading>
+ When in doubt, send mail to
+ <email>debian-legal@lists.debian.org</email>. Be prepared
+ to provide us with the copyright statement. Software
+ covered by the GPL, public domain software and BSD-like
+ copyrights are safe; be wary of the phrases `commercial use
+ prohibited' and `distribution restricted'.</p>
+ </sect1>
+ <sect1>
+ <heading>Subsections</heading>
- <p>
- The packages in all the sections (<em>main</em>,
- <em>contrib</em>, <em>non-US/main</em>, <em>non-free</em>,
- <em>non-US/contrib</em>, and <em>non-US/non-free</em>) are
- grouped further into <em>subsections</em> to simplify
- handling.</p>
+ The packages in all the sections (<em>main</em>,
+ <em>contrib</em>, <em>non-US/main</em>, <em>non-free</em>,
+ <em>non-US/contrib</em>, and <em>non-US/non-free</em>) are
+ grouped further into <em>subsections</em> to simplify
+ handling.</p>
- <p>
- The section for each package should be specified in the
- package's <em>control record</em>. However, the maintainer of
- the Debian archive may override this selection to assure the
- consistency of the Debian distribution. </p>
+ The section for each package should be specified in the
+ package's <em>control record</em>. However, the maintainer of
+ the Debian archive may override this selection to assure the
+ consistency of the Debian distribution. </p>
- <p>
- Please check the current Debian distribution to see which
- sections are available.</p>
- </sect1>
+ Please check the current Debian distribution to see which
+ sections are available.</p>
+ </sect1>
<sect>
<heading>Priorities</heading>
-
+
<p>
Each package should have a <em>priority</em> value,
which is included in the package's <em>control
- record</em>. This information is used in the Debian package
+ record</em>. This information is used in the Debian package
management tool to separate high-priority packages from
less-important packages.</p>
-
+
<p>
The following <em>priority levels</em> are supported by the
Debian package management system, <prgn>dpkg</prgn>.
</p>
</item>
</taglist></p>
-
+
<p>
Packages must not depend on packages with lower priority
values (excluding build-time dependencies). In order to
be adjusted.
</p>
</sect>
-
+
<sect>
<heading>Binary packages</heading>
-
+
<p>
The Debian GNU/Linux distribution is based on the Debian
package management system, called <prgn>dpkg</prgn>. Thus,
all packages in the Debian distribution must be provided
in the <tt>.deb</tt> file format.</p>
-
+
<sect1>
<heading>The package name</heading>
-
+
<p>
Every package must have a name that's unique within the Debian
archive.</p>
-
+
<p>
Package names must only consist of lower case letters, digits (0-9),
plus (+) or minus (-) signs, and periods (.).</p>
-
+
<p>
The package name is part of the file name of the
<tt>.deb</tt> file and is included in the control field
information.
</p>
</sect1>
-
+
<sect1>
<heading>The maintainer of a package</heading>
-
+
<p>
Every package should have exactly one maintainer at a
time. This person is responsible that the license of the
package's software complies with the policy of the
distribution this package is included in.</p>
-
+
<p>
The maintainer must be specified in the
<tt>Maintainer</tt> control field with the correct name
he/she should try to avoid having different forms of their
name and email address in different <tt>Maintainer</tt>
fields.</p>
-
+
<p>
If the maintainer of a package quits from the Debian
project the Debian QA Group
<em>orphaned packages</em>.
</p>
</sect1>
-
-
+
+
<sect1>
<heading>The description of a package</heading>
-
+
<p>
Every Debian package must have an extended description
stored in the appropriate field of the control record.</p>
-
+
<p>
The description should be written so that it tells the user
what they need to know to decide whether to install the
not be included -- that is what the copyright file is
for.</p>
</sect1>
-
-
+
+
<sect1>
<heading>Dependencies</heading>
-
+
<p>
Every package must specify the dependency information
about other packages that are required for the first to
work correctly.</p>
-
+
<p>
For example, a dependency entry must be provided for any
shared libraries required by a dynamically-linked executable
binary in a package.</p>
-
+
<p>
Packages are not required to declare any dependencies they
have on other packages which are marked <tt>Essential</tt>
(see below), and should not do so unless they depend on a
particular version of that package.</p>
-
+
<p>
Sometimes, a package requires another package to be installed
<em>and</em> configured before it can be installed. In this
case, you must specify a <tt>Pre-Depends</tt> entry for
the package.</p>
-
+
<p>
You should not specify a <tt>Pre-Depends</tt> entry for a
package before this has been discussed on the
<tt>debian-devel</tt> mailing list and a consensus about
doing that has been reached.</p></sect1>
-
-
+
+
<sect1>
<heading>Virtual packages</heading>
-
+
<p>
Sometimes, there are several packages doing more-or-less
the same job. In this case, it's useful to define a
package. Thus, any other package requiring that function
can simply depend on the virtual package without having to
specify all possible packages individually.</p>
-
+
<p>
All packages should use virtual package names where
appropriate, and arrange to create new ones if necessary.
amongst a cooperating group of packages) unless they have
been agreed upon and appear in the list of virtual package
names.</p>
-
+
<p>
The latest version of the authoritative list of virtual
package names can be found on
or your local mirror. In addition, it is included in the
<tt>debian-policy</tt> package. The procedure for updating
the list is described at the top of the file.</p></sect1>
-
-
+
+
<sect1>
<heading>Base packages</heading>
-
+
<p>
The packages included in the <tt>base</tt> section have a
special function. They form a minimum subset of the Debian
on a new system. Thus, only very few packages are allowed
to go into the <tt>base</tt> section to keep the required
disk usage very small.</p>
-
+
<p>
Most of these packages will have the priority value
<tt>required</tt> or at least <tt>important</tt>, and many
of them will be tagged <tt>essential</tt> (see below).</p>
-
+
<p>
You must not place any packages into the <tt>base</tt>
section before this has been discussed on the
<tt>debian-devel</tt> mailing list and a consensus about
doing that has been reached.</p></sect1>
-
-
+
+
<sect1>
<heading>Essential packages</heading>
-
+
<p>
Some packages are tagged <tt>essential</tt>. (They have
<tt>Essential: yes</tt> in their package control record.)
This flag is used for packages that are <em>essential</em>
for a system.</p>
-
+
<p>
Since these packages can not easily be removed (you'll
have to specify an extra <em>force option</em> to
prevent its premature removal, and we need to be able to
remove it when it has been superseded.
</p>
-
+
<p>
Since dpkg will not prevent upgrading of other packages
while an <tt>essential</tt> package is in an unconfigured
this has been discussed on the <tt>debian-devel</tt>
mailing and a consensus about doing that has been
reached.</p></sect1>
-
-
+
+
<sect1>
<heading>Maintainer scripts</heading>
-
+
<p>
The package installation scripts should avoid producing
output which it is unnecessary for the user to see and
the part of a user installing many packages. This means,
amongst other things, using the <tt>--quiet</tt> option on
<prgn>install-info</prgn>.</p>
-
+
<p>
Packages should try to minimize the amount of prompting
they need to do, and they should ensure that the user will
configuration files (such as <tt>/etc/papersize</tt> and
<tt>/etc/news/server</tt>), rather than each prompting for
their own list of required pieces of information.</p>
-
+
<p>
It also means that an upgrade should not ask the same
questions again, unless the user has used <tt>dpkg
- --purge</tt> to remove the package's configuration. The
+ --purge</tt> to remove the package's configuration. The
answers to configuration questions should be stored in an
appropriate place in <tt>/etc</tt> so that the user can
modify them, and how this has been done should be
documented.</p>
-
+
<p>
If a package has a vitally important piece of information
to pass to the user (such as "don't run me as I am, you
do instructions on how to use a program (these should be
in on line documentation, where all the users can see
them).</p>
-
+
<p>
Any necessary prompting should almost always be confined
to the post-installation script, and should be protected
<prgn>postinst</prgn> is called with
<tt>abort-upgrade</tt>, <tt>abort-remove</tt> or
<tt>abort-deconfigure</tt>.</p>
-
+
<p>
Errors which occur during the execution of an installation
script should be checked and the installation should not
continue after an error.</p>
-
+
<p>
Note, that <ref id="scripts">, in general applies to
package maintainer scripts, too.</p>
-
+
<p>
You should not use <prgn>dpkg-divert</prgn> on a file
belonging to another package without consulting the maintainer
of that package first.</p>
-
+
<p>
All packages which supply an instance of a common command
name (or, in general, filename) should generally use
</sect>
<sect>
<heading>Source packages</heading>
-
+
<sect1>
<heading>Standards conformance</heading>
-
+
<p>
You should specify the most recent version of the
packaging standards with which your package complies in
the source package's <tt>Standards-Version</tt> field.</p>
-
+
<p>
This value will be used to file bug reports automatically
if your package becomes too much out of date.</p>
-
+
<p>
The value corresponds to a version of the Debian manuals,
as can be found on the title page or page headers and
footers (depending on the format).</p>
-
+
<p>
The version number has four components--major and minor
number and major and minor patch level. When the
which do not change the meaning are made, or changes which
do not affect the contents of packages.</p>
- <p>
- For package maintainers, only the first 3 digits of the
- manual version are significant in representing the
- <em>Standards-Version</em>, and either these 3 digits or
- the complete 4 digits may be specified.
- <footnote>
+ <p>
+ For package maintainers, only the first 3 digits of the
+ manual version are significant in representing the
+ <em>Standards-Version</em>, and either these 3 digits or
+ the complete 4 digits may be specified.
+ <footnote>
+ <p>
+ In the past, people specified 4 digits in the
+ Standards-Version field, like `2.3.0.0'. Since any
+ `patch-level changes' don't introduce new policy, it
+ was thought it would be better to relax policy and
+ only require that the first 3 digits are specified. (4
+ digits may still be used if someone wants to do so.)
+ </p>
+ </footnote>
+ </p>
+
+ <p>
+ You should regularly, and especially if your package has
+ become out of date, check for the newest Policy Manual
+ available and update your package, if necessary. When your
+ package complies with the new standards you should update the
+ <tt>Standards-Version</tt> source package field and
+ release it.</p></sect1>
+
+
+ <sect1>
+ <heading>Package relationships</heading>
+
+ <p>
+ Source packages should specify which binary packages they
+ require to be installed or not to be installed in order to
+ build correctly. For example, if building a package
+ requires a certain compiler, then the compiler should be
+ specified as a build-time dependency.
+ </p>
+
+ <p>
+ It is not necessary to explicitly specify build-time
+ relationships on a minimal set of packages that are always
+ needed to compile, link and put in a Debian package a
+ standard "Hello World!" program written in C or C++. The
+ required packages are called <em>build-essential</em>, and
+ an informational list can be found in
+ <tt>/usr/share/doc/build-essential/list</tt> (which is
+ contained in the <tt>build-essential</tt>
+ package).
+ <footnote>
+ <p>Rationale:
+ <list>
+ <item>
+ <p>This allows maintaining the list separately
+ from the policy documents (the list does not
+ need the kind of control that the policy
+ documents do)
+ </p>
+ </item>
+ <item>
+ <p>
+ Having a separate package allows one to nistall
+ the build essential packages on a machine, as
+ well as allowing other packages (think task
+ packages) to bring in the build-essential
+ packages using the depends relation
+ </p>
+ </item>
+ <item>
+ <p>
+ The separate package allows bug reports against
+ the package to be categorized separately from
+ the policy management process that uses the BTS
+ </p>
+ </item>
+ </list>
+ </p>
+
+ </footnote>
+ </p>
+
+ <p>
+ When specifying the set of build-time dependencies, one
+ should list only those packages explicitly required by the
+ build. It is not necessary to list packages which are
+ required merely because some other package in the list of
+ build-time dependencies depends on them. The reason is
+ that dependencies change, and you should list only those
+ <em>you</em> need. What others need is their business.
+ </p>
+
+ <p>
+ If build-time dependencies are specified, it must be
+ possible to build the package and produce working binaries
+ on a system with the build-essential packages installed
+ and satisfying the build-time relationships (including any
+ implied relationships). This
+ means in particular that version clauses should be used
+ rigorously in build-time relationships so that one cannot
+ produce bad or inconsistently configured packages when the
+ relationships are properly satisfied.
+ </p>
+
+ <sect1>
+ <heading>Changes to the upstream sources</heading>
+
+ <p>
+ If changes to the source code are made that are generally
+ applicable, they should be sent to the upstream authors
+ in whatever form they prefer so as to be included in the
+ upstream version of the package.</p>
+
+ <p>
+ If you need to configure the package differently for
+ Debian or for Linux, and the upstream source doesn't
+ provide a way to configure it the way you need to, you
+ should add such configuration facilities (for example, a new
+ <prgn>autoconf</prgn> test or <tt>#define</tt>) and send
+ the patch to the upstream authors, with the default set to
+ the way they originally had it. You can then easily
+ override the default in your <tt>debian/rules</tt> or
+ wherever is appropriate.</p>
+
+ <p>
+ You should make sure that the <prgn>configure</prgn> utility
+ detects the correct architecture specification string
+ (refer to <ref id="arch-spec"> for details).</p>
+
+ <p>
+ If you need to edit a <prgn>Makefile</prgn> where
+ GNU-style <prgn>configure</prgn> scripts are used, you
+ should edit the <tt>.in</tt> files rather than editing the
+ <prgn>Makefile</prgn> directly. This allows the user to
+ reconfigure the package if necessary. You should
+ <em>not</em> configure the package and edit the generated
+ <prgn>Makefile</prgn>! This makes it impossible for
+ someone else to later reconfigure the package.</p></sect1>
+
+
+ <sect1>
+ <heading>Documenting your changes</heading>
+
+ <p>
+ You should document your changes and updates to the source
+ package properly in the <tt>debian/changelog</tt> file. (Note
+ that mistakes in changelogs are usually best rectified by
+ making a new changelog entry rather than "rewriting history"
+ by editing old changelog entries)</p>
+
+ <p>
+ A copy of the file which will be installed in
+ <tt>/usr/share/doc/<var>package</var>/copyright</tt> should be
+ in <tt>debian/copyright</tt>.</p>
+
+ <p>
+ In non-experimental packages you must only use a format for
+ <tt>debian/changelog</tt> which is supported by the most
+ recent released version of <prgn>dpkg</prgn>. If your
+ format is not supported and there is general support for
+ it you should contact the <prgn>dpkg</prgn> maintainer to
+ have the parser script for your format included in the
+ <prgn>dpkg</prgn> package. (You will need to agree that
+ the parser and its manpage may be distributed under the
+ GNU GPL, just as the rest of <prgn>dpkg</prgn>
+ is.)</p></sect1>
+
+
+ <sect1>
+ <heading>Error trapping in makefiles</heading>
+
+ <p>
+ When <prgn>make</prgn> invokes a command in a makefile
+ (including your package's upstream makefiles and the
+ <tt>debian/rules</tt>) it does so using <tt>sh</tt>. This
+ means that <tt>sh</tt>'s usual bad error handling
+ properties apply: if you include a miniature script as one
+ of the commands in your makefile you'll find that if you
+ don't do anything about it then errors are not detected
+ and <prgn>make</prgn> will blithely continue after
+ problems.</p>
+
+ <p>
+ Every time you put more than one shell command (this
+ includes using a loop) in a makefile command you
+ must make sure that errors are trapped. For
+ simple compound commands, such as changing directory and
+ then running a program, using <tt>&&</tt> rather
+ than semicolon as a command separator is sufficient. For
+ more complex commands including most loops and
+ conditionals you should include a separate <tt>set -e</tt>
+ command at the start of every makefile command that's
+ actually one of these miniature shell scripts.</p></sect1>
+
+
+ <sect1>
+ <heading>Obsolete constructs and libraries</heading>
+
+ <p>
+ The include file <prgn><varargs.h></prgn> is
+ provided to support end-users compiling very old software;
+ the library <tt>libtermcap</tt> is provided to support the
+ execution of software which has been linked against it
+ (either old programs or those such as Netscape which are
+ only available in binary form).</p>
+
+ <p>
+ Debian packages should be ported to include
+ <prgn><stdarg.h></prgn> and <tt>ncurses</tt> when
+ they are built.</p>
+ </sect1>
+ </sect>
+ </chapt>
+
+ <chapt id="controlfields"><heading>Control files and their fields</heading>
+
+ <p>
+ Many of the tools in the package management suite manipulate
+ data in a common format, known as control files. Binary and
+ source packages have control data as do the <tt>.changes</tt>
+ files which control the installation of uploaded files, and
+ <prgn>dpkg</prgn>'s internal databases are in a similar
+ format.
+ </p>
+
+ <sect><heading>Syntax of control files</heading>
+
+ <p>
+ A file consists of one or more paragraphs of fields. The
+ paragraphs are separated by blank lines. Some control files
+ only allow one paragraph; others allow several, in which
+ case each paragraph often refers to a different package.
+ </p>
+
+ <p>
+ Each paragraph is a series of fields and values; each field
+ consists of a name, followed by a colon and the value. It
+ ends at the end of the line. Horizontal whitespace (spaces
+ and tabs) may occur immediately before or after the value
+ and is ignored there; it is conventional to put a single
+ space after the colon.
+ </p>
+
+ <p>
+ Some fields' values may span several lines; in this case
+ each continuation line <em>must</em> start with a space or
+ tab. Any trailing spaces or tabs at the end of individual
+ lines of a field value are ignored.
+ </p>
+
+ <p>
+ Except where otherwise stated only a single line of data is
+ allowed and whitespace is not significant in a field body.
+ Whitespace may never appear inside names (of packages,
+ architectures, files or anything else), version numbers or
+ in between the characters of multi-character version
+ relationships.
+ </p>
+
+ <p>
+ Field names are not case-sensitive, but it is usual to
+ capitalize the field names using mixed case as shown below.
+ </p>
+
+ <p>
+ Blank lines, or lines consisting only of spaces and tabs,
+ are not allowed within field values or between fields - that
+ would mean a new paragraph.
+ </p>
+
+ <p>
+ It is important to note that there are several fields which
+ are optional as far as <prgn>dpkg</prgn> and the related
+ tools are concerned, but which must appear in every Debian
+ package, or whose omission may cause problems. When writing
+ the control files for Debian packages you <em>must</em> read
+ the Debian policy manual in conjunction with the details
+ below and the list of fields for the particular file.</p>
+ </sect>
+
+ <sect><heading>List of fields</heading>
+ <p>
+ This list here is not supposed to be exhaustive. Typically
+ only fields for whom policy exists are mentioned here.
+ </p>
+ <sect1 id="f-Package"><heading><tt>Package</tt>
+ </heading>
+
+ <p>
+ The name of the binary package. Package names consist of
+ the alphanumerics and <tt>+</tt> <tt>-</tt> <tt>.</tt>
+ (plus, minus and full stop).
+ </p>
+
+ <p>
+ They must be at least two characters long and must start
+ with an alphanumeric character. The use lowercase package
+ names is strongly recommended unless the package you're
+ building (or referring to, in other fields) is already
+ using uppercase.</p>
+ </sect1>
+
+ <sect1 id="f-Version"><heading><tt>Version</tt>
+ </heading>
+
+ <p>
+ This lists the source or binary package's version number -
+ see <ref id="versions">.
+ </p>
+
+ </sect1>
+
+ <sect1
+ id="f-Standards-Version"><heading><tt>Standards-Version</tt>
+ </heading>
+
+ <p>
+ The most recent version of the standards (the packaging
+ and policy manuals and associated texts) with which the
+ package complies. This is updated manually when editing
+ the source package to conform to newer standards; it can
+ sometimes be used to tell when a package needs attention.
+ </p>
+
+ <p>
+ Its format is the same as that of a version number except
+ that no epoch or Debian revision is allowed - see <ref
+ id="versions">.</p>
+ </sect1>
+
+
+ <sect1 id="f-Distribution"><heading><tt>Distribution</tt>
+ </heading>
+
+ <p>
+ In a <tt>.changes</tt> file or parsed changelog output
+ this contains the (space-separated) name(s) of the
+ distribution(s) where this version of the package should
+ be or was installed. Distribution names follow the rules
+ for package names. (See <ref id="f-Package">).
+ </p>
+
+ <p>
+ <footnote>
+ Current distribution values are:
+ <taglist>
+ <tag><em>stable</em></tag>
+ <item>
+ <p>
+ This is the current `released' version of Debian
+ GNU/Linux. Once the
+ distribution is <em>stable</em> only major bug fixes
+ are allowed. When changes are made to this
+ distribution, the release number is increased
+ (for example: 1.2r1 becomes 1.2r2 then 1.2r3, etc).
+ </p>
+ </item>
+
+ <tag><em>unstable</em></tag>
+ <item>
+ <p>
+ This distribution value refers to the
+ <em>developmental</em> part of the Debian
+ distribution tree. New packages, new upstream
+ versions of packages and bug fixes go into the
+ <em>unstable</em> directory tree. Download from
+ this distribution at your own risk.
+ </p>
+ </item>
+
+ <tag><em>frozen</em></tag>
+ <item>
+ <p>
+ From time to time, the <em>unstable</em>
+ distribution enters a state of `code-freeze' in
+ anticipation of release as a <em>stable</em>
+ version. During this period of testing only
+ fixes for existing or newly-discovered bugs will
+ be allowed.
+ </p>
+ </item>
+
+ <tag><em>experimental</em></tag>
+ <item>
+ <p>
+ The packages with this distribution value are deemed
+ by their maintainers to be high risk. Oftentimes they
+ represent early beta or developmental packages from
+ various sources that the maintainers want people to
+ try, but are not ready to be a part of the other parts
+ of the Debian distribution tree. Download at your own
+ risk.
+ </p>
+ </item>
+ </taglist>
+ There are several sections in each
+ distribution. Currently, these sections are:
+
+ <taglist>
+ <tag><em>contrib</em></tag>
+ <item>
+ <p>
+ The packages in this section do not meet the
+ criteria for inclusion in the main Debian
+ distribution as defined by the Policy Manual,
+ but are otherwise free, as defined by the Debian
+ free software guidelines.</p>
+ </item>
+
+ <tag><em>non-free</em></tag>
+ <item>
+ <p>
+ Packages in <em>non-free</em> do not meet the
+ criteria of free software, as defined by the
+ Debian free software guidelines. Again, use your
+ best judgment in downloading from this
+ Distribution.</p>
+ </item>
+
+ </taglist> You should list <em>all</em> distributions that
+ the package should be installed into. Except in unusual
+ circumstances, installations to <em>stable</em> should also
+ go into <em>frozen</em> (if it exists) and
+ <em>unstable</em>. Likewise, installations into
+ <em>frozen</em> should also go into <em>unstable</em>.
+ </footnote>
+ </p>
+ </sect1>
+
+
+ </sect>
+ </chapt>
+
+ <chapt id="versions"><heading>Version numbering </heading>
+
+ <p>
+ Every package has a version number, in its <tt>Version</tt>
+ control file field.
+ </p>
+
+ <p>
+ The package management system imposes an ordering on version
+ numbers, so that it can tell whether packages are being up- or
+ downgraded and so that package system front end applications
+ can tell whether a package it finds available is newer than
+ the one installed on the system. The version number format
+ has the most significant parts (as far as comparison is
+ concerned) at the beginning.
+ </p>
+
+ <p>
+ The version number format is:
+ &lsqb<var>epoch</var><tt>:</tt>]<var>upstream-version</var>[<tt>-/<var>debian-revision</var>].</tt></var>
+ </p>
+
+ <p>
+ The three components here are:
+ <taglist>
+ <tag><var>epoch</var></tag>
+ <item>
+
+ <p>
+ This is a single (generally small) unsigned integer. It
+ may be omitted, in which case zero is assumed. If it is
+ omitted then the <var>upstream-version</var> may not
+ contain any colons.
+ </p>
+
+ <p>
+ It is provided to allow mistakes in the version numbers
+ of older versions of a package, and also a package's
+ previous version numbering schemes, to be left behind.
+ </p>
+
+ </item>
+
+ <tag><var>upstream-version</var></tag>
+ <item>
+
+ <p>
+ This is the main part of the version. It is usually
+ version number of the original (`upstream') package of
+ which the <tt>.deb</tt> file has been made, if this is
+ applicable. Usually this will be in the same format as
+ that specified by the upstream author(s); however, it
+ may need to be reformatted to fit into the package
+ management system's format and comparison scheme.
+ </p>
+
+ <p>
+ The comparison behavior of the package management system
+ with respect to the <var>upstream-version</var> is
+ described below. The <var>upstream-version</var>
+ portion of the version number is mandatory.
+ </p>
+
+ <p>
+ The <var>upstream-version</var> may contain only
+ alphanumerics and the characters <tt>.</tt> <tt>+</tt>
+ <tt>-</tt> <tt>:</tt> (full stop, plus, hyphen, colon)
+ and should start with a digit. If there is no
+ <var>debian-revision</var> then hyphens are not allowed;
+ if there is no <var>epoch</var> then colons are not
+ allowed.</p>
+ </item>
+
+ <tag><var>debian-revision</var></tag>
+ <item>
+
+ <p>
+ This part of the version represents the version of the
+ modifications that were made to the package to make it a
+ Debian binary package. It is in the same format as the
+ <var>upstream-version</var> and is compared in the same
+ way.
+ </p>
+
+ <p>
+ It is optional; if it isn't present then the
+ <var>upstream-version</var> may not contain a hyphen.
+ This format represents the case where a piece of
+ software was written specifically to be turned into a
+ Debian binary package, and so there is only one
+ `debianization' of it and therefore no revision
+ indication is required.
+ </p>
+
+ <p>
+ It is conventional to restart the
+ <var>debian-revision</var> at <tt>1</tt> each time the
+ <var>upstream-version</var> is increased.
+ </p>
+
+ <p>
+ The package management system will break the
+ <var>upstream-version</var> and
+ <var>debian-revision</var> apart at the last hyphen in
+ the string. The absence of a <var>debian-revision</var>
+ compares earlier than the presence of one (but note that
+ the <var>debian-revision</var> is the least significant
+ part of the version number).
+ </p>
+
+ <p>
+ The <var>debian-revision</var> may contain only
+ alphanumerics and the characters <tt>+</tt> and
+ <tt>.</tt> (plus and full stop).
+ </p>
+ </item>
+ </taglist>
+ The <var>upstream-version</var> and <var>debian-revision</var>
+ parts are compared by the package management system using the
+ same algorithm:
+ </p>
+
+ <p>
+ The strings are compared from left to right.
+ </p>
+
+ <p>
+ First the initial part of each string consisting entirely of
+ non-digit characters is determined. These two parts (one of
+ which may be empty) are compared lexically. If a difference
+ is found it is returned. The lexical comparison is a
+ comparison of ASCII values modified so that all the letters
+ sort earlier than all the non-letters.
+ </p>
+
+ <p>
+ Then the initial part of the remainder of each string which
+ consists entirely of digit characters is determined. The
+ numerical values of these two parts are compared, and any
+ difference found is returned as the result of the comparison.
+ For these purposes an empty string (which can only occur at
+ the end of one or both version strings being compared) counts
+ as zero.
+ </p>
+
+ <p>
+ These two steps are repeated (chopping initial non-digit
+ strings and initial digit strings off from the start) until a
+ difference is found or both strings are exhausted.
+ </p>
+
+ <p>
+ Note that the purpose of epochs is to allow us to leave behind
+ mistakes in version numbering, and to cope with situations
+ where the version numbering changes. It is <em>not</em> there
+ to cope with version numbers containing strings of letters
+ which the package management system cannot interpret (such as
+ <tt>ALPHA</tt> or <tt>pre-</tt>), or with silly orderings (the
+ author of this manual has heard of a package whose versions
+ went <tt>1.1</tt>, <tt>1.2</tt>, <tt>1.3</tt>, <tt>1</tt>,
+ <tt>2.1</tt>, <tt>2.2</tt>, <tt>2</tt> and so forth).
+ </p>
+
+ <p>
+ If an upstream package has problematic version numbers they
+ should be converted to a sane form for use in the
+ <tt>Version</tt> field.
+ </p>
+
+ <sect>
+ <heading>Version numbers based on dates</heading>
+ <p>
+ In general, Debian packages should use the same version
+ numbers as the upstream sources.</p>
+
+ <p>
+ However, in some cases where the upstream version number is
+ based on a date (e.g., a development `snapshot' release) the
+ package management system cannot handle these version
+ numbers without epochs. For example, dpkg will consider
+ `96May01' to be greater than `96Dec24'.</p>
+
+ <p>
+ To prevent having to use epochs for every new upstream
+ version, the version number should be changed to the
+ following format in such cases: `19960501', `19961224'. It
+ is up to the maintainer whether he/she wants to bother the
+ upstream maintainer to change the version numbers upstream,
+ too.</p>
+
+ <p>
+ Note, that other version formats based on dates which are
+ parsed correctly by the package management system should
+ <em>not</em> be changed.</p>
+
+ <p>
+ Native Debian packages (i.e., packages which have been
+ written especially for Debian) whose version numbers include
+ dates should always use the `YYYYMMDD' format.</p>
+ </sect>
+ </chapt>
+
+ <chapt id="miscellaneous"><heading>Packaging Considerations</heading>
+
+ <sect id="timestamps"><heading>Time Stamps</heading>
+ <p>
+ Maintainers are encouraged to preserve the modification
+ times of the upstream source files in a package, as far as
+ is reasonably possible. Even though this is optional, this
+ is still a good idea.
+ <footnote>
+ <p>
+ The rationale is that there is some information conveyed
+ by knowing the age of the file, for example, you could
+ recognize that some documentation is very old by looking
+ at the modification time, so it would be nice if the
+ modification time of the upstream source would be
+ preserved.
+ </p>
+ </footnote>
+ </p>
+ </sect>
+
+ <sect id="debianrules"><heading><tt>debian/rules</tt> - the
+ main building script </heading>
+
+ <p>
+ This file must be an executable makefile, and contains the
+ package-specific recipes for compiling the package and
+ building binary package(s) out of the source.
+ </p>
+
+ <p>
+ It must start with the line <tt>#!/usr/bin/make -f</tt>,
+ so that it can be invoked by saying its name rather than
+ invoking <prgn>make</prgn> explicitly.
+ </p>
+
+ <p>
+ Since an interactive <tt>debian/rules</tt> script makes it
+ impossible to auto-compile that package and also makes it
+ hard for other people to reproduce the same binary
+ package, all <strong>required targets</strong> MUST be
+ non-interactive. At a minimum, required targets are the
+ ones called by <prgn>dpkg-buildpackage</prgn>, namely,
+ <em>clean</em>, <em>binary</em>, <em>binary-arch</em>, and
+ <em>build</em>. It also follows that any target that these
+ targets depend on must also be non-interactive.
+ </p>
+
+ <p>
+ The targets which must be present are:
+ <taglist>
+ <tag><tt>build</tt></tag>
+ <item>
+ <p>
+ This should perform all non-interactive
+ configuration and compilation of the package. If a
+ package has an interactive pre-build configuration
+ routine, the Debianised source package should be
+ built after this has taken place, so that it can be
+ built without rerunning the configuration.
+ </p>
+
+ <p>
+ For some packages, notably ones where the same
+ source tree is compiled in different ways to produce
+ two binary packages, the <prgn>build</prgn> target
+ does not make much sense. For these packages it is
+ good enough to provide two (or more) targets
+ (<tt>build-a</tt> and <tt>build-b</tt> or whatever)
+ for each of the ways of building the package, and a
+ <prgn>build</prgn> target that does nothing. The
+ <prgn>binary</prgn> target will have to build the
+ package in each of the possible ways and make the
+ binary package out of each.
+ </p>
+
+ <p>
+ The <prgn>build</prgn> target must not do anything
+ that might require root privilege.
+ </p>
+
+ <p>
+ The <prgn>build</prgn> target may need to run
+ <prgn>clean</prgn> first - see below.
+ </p>
+
+ <p>
+ When a package has a configuration routine that
+ takes a long time, or when the makefiles are poorly
+ designed, or when <prgn>build</prgn> needs to run
+ <prgn>clean</prgn> first, it is a good idea to
+ <tt>touch build</tt> when the build process is
+ complete. This will ensure that if <tt>debian/rules
+ build</tt> is run again it will not rebuild the
+ whole program.
+ </p>
+ </item>
+
+ <tag><tt>binary</tt>, <tt>binary-arch</tt>,
+ <tt>binary-indep</tt>
+ </tag>
+ <item>
+ <p>
+ The <prgn>binary</prgn> target must be all that is
+ necessary for the user to build the binary
+ package. All these targets are required to be
+ non-interactive. It is split into two parts:
+ <prgn>binary-arch</prgn> builds the packages' output
+ files which are specific to a particular
+ architecture, and <prgn>binary-indep</prgn> builds
+ those which are not.
+ </p>
+
+ <p>
+ <prgn>binary</prgn> may be (and commonly is) a target
+ with no commands which simply depends on
+ <prgn>binary-arch</prgn> and
+ <prgn>binary-indep</prgn>.
+ </p>
+
+ <p>
+ Both <prgn>binary-*</prgn> targets should depend on
+ the <prgn>build</prgn> target, above, so that the
+ package is built if it has not been already. It
+ should then create the relevant binary package(s),
+ using <prgn>dpkg-gencontrol</prgn> to make their
+ control files and <prgn>dpkg-deb</prgn> to build
+ them and place them in the parent of the top level
+ directory.
+ </p>
+
+ <p>
+ If one of the <prgn>binary-*</prgn> targets has
+ nothing to do (this will be always be the case if
+ the source generates only a single binary package,
+ whether architecture-dependent or not) it
+ <em>must</em> still exist, and must always
+ succeed.
+ </p>
+
+ <p>
+ The <prgn>binary</prgn> targets must be invoked as
+ root.
+ </p>
+ </item>
+
+ <tag><tt>clean</tt></tag>
+ <item>
+
+ <p>
+ This must undo any effects that the
+ <prgn>build</prgn> and <prgn>binary</prgn> targets
+ may have had, except that it should leave alone any
+ output files created in the parent directory by a
+ run of <prgn>binary</prgn>. This target must be
+ non-interactive.
+ </p>
+
+ <p>
+ If a <prgn>build</prgn> file is touched at the end
+ of the <prgn>build</prgn> target, as suggested
+ above, it should be removed as the first thing that
+ <prgn>clean</prgn> does, so that running
+ <prgn>build</prgn> again after an interrupted
+ <prgn>clean</prgn> doesn't think that everything is
+ already done.
+ </p>
+
+ <p>
+ The <prgn>clean</prgn> target may need to be
+ invoked as root if <prgn>binary</prgn> has been
+ invoked since the last <prgn>clean</prgn>, or if
+ <prgn>build</prgn> has been invoked as root (since
+ <prgn>build</prgn> may create directories, for
+ example).
+ </p>
+ </item>
+
+ <tag><tt>get-orig-source</tt> (optional)</tag>
+ <item>
+
+ <p>
+ This target fetches the most recent version of the
+ original source package from a canonical archive site
+ (via FTP or WWW, for example), does any necessary
+ rearrangement to turn it into the original source
+ tar file format described below, and leaves it in the
+ current directory.
+ </p>
+
+ <p>
+ This target may be invoked in any directory, and
+ should take care to clean up any temporary files it
+ may have left.
+ </p>
+
+ <p>
+ This target is optional, but providing it if
+ possible is a good idea.
+ </p>
+ </item>
+ </taglist>
+
+ <p>
+ The <prgn>build</prgn>, <prgn>binary</prgn> and
+ <prgn>clean</prgn> targets must be invoked with a current
+ directory of the package's top-level directory.
+ </p>
+
+
+ <p>
+ Additional targets may exist in <tt>debian/rules</tt>,
+ either as published or undocumented interfaces or for the
+ package's internal use.
+ </p>
+
+ <p>
+ The architecture we build on and build for is determined by
+ make variables via dpkg-architecture. You can get the Debian
+ architecture and the GNU style architecture specification
+ string for the build machine as well as the host
+ machine. Here is a list of supported make variables:
+ <list compact="compact">
+ <item>
+ <p><tt>DEB_*_ARCH</tt> (the Debian architecture)</p>
+ </item>
+ <item>
+ <p><tt>DEB_*_GNU_TYPE</tt> (the GNU style architecture
+ specification string)</p>
+ </item>
+ <item>
+ <p><tt>DEB_*_GNU_CPU</tt> (the CPU part of DEB_*_GNU_TYPE)</p>
+ </item>
+ <item>
+ <p><tt>DEB_*_GNU_SYSTEM</tt> (the System part of
+ DEB_*_GNU_TYPE)</p>
+ </list>
+ </p>
+
+ <p>
+ where <tt>*</tt> is either <tt>BUILD</tt> for specification of
+ the build machine or <tt>HOST</tt> for specification of the machine
+ we build for.
+ </p>
+
+ <p>
+ Backward compatibility can be provided in the rules file
+ by setting the needed variables to suitable default
+ values, please refer to the documentation of
+ dpkg-architecture for details.
+ </p>
+
+ <p>
+ It is important to understand that the <tt>DEB_*_ARCH</tt>
+ string does only determine which Debian architecture we
+ build on resp. for. It should not be used to get the CPU
+ or System information, the GNU style variables should be
+ used for that.
+ </p>
+ </sect>
+
+ <sect id="dpkgchangelog"><heading><tt>debian/changelog</tt>
+ </heading>
+
+ <p>
+ This file records the changes to the Debian-specific parts of the
+ package
+ <footnote>
+ <p>
+ Though there is nothing stopping an author who is also
+ the Debian maintainer from using it for all their
+ changes, it will have to be renamed if the Debian and
+ upstream maintainers become different
+ people.
+ </p>
+ </footnote>.
+ </p>
+
+ <p>
+ It has a special format which allows the package building
+ tools to discover which version of the package is being
+ built and find out other release-specific information.
+ </p>
+
+ <p>
+ That format is a series of entries like this:
+ <example>
+ <var>package</var> (<var>version</var>) <var>distribution(s)</var>; urgency=<var>urgency</var>
+
+ * <var>change details</var>
+ <var>more change details</var>
+ * <var>even more change details</var>
+
+ -- <var>maintainer name and email address</var> <var>date</var>
+ </example>
+ </p>
+
+ <p>
+ <var>package</var> and <var>version</var> are the source
+ package name and version number.
+ </p>
+
+ <p>
+ <var>distribution(s)</var> lists the distributions where
+ this version should be installed when it is uploaded - it
+ is copied to the <tt>Distribution</tt> field in the
+ <tt>.changes</tt> file. See <ref id="f-Distribution">.
+ </p>
+
+ <p>
+ <var>urgency</var> is the value for the <tt>Urgency</tt>
+ field in the <tt>.changes</tt> file for the upload. It is
+ not possible to specify an urgency containing commas; commas
+ are used to separate
+ <tt><var>keyword</var>=<var>value</var></tt> settings in the
+ <prgn>dpkg</prgn> changelog format (though there is
+ currently only one useful <var>keyword</var>,
+ <tt>urgency</tt>).
+ </p>
+
+ <p>
+ The change details may in fact be any series of lines
+ starting with at least two spaces, but conventionally each
+ change starts with an asterisk and a separating space and
+ continuation lines are indented so as to bring them in
+ line with the start of the text above. Blank lines may be
+ used here to separate groups of changes, if desired.
+ </p>
+
+ <p>
+ The maintainer name and email address need <em>not</em>
+ necessarily be those of the usual package maintainer.
+ They should be the details of the person doing
+ <em>this</em> version. The information here will be
+ copied to the <tt>.changes</tt> file, and then later used
+ to send an acknowledgement when the upload has been
+ installed.
+ </p>
+
+ <p>
+ The <var>date</var> should be in RFC822 format
+ <footnote>
+ <p>
+ This is generated by the <prgn>822-date</prgn>
+ program.
+ </p>
+ </footnote>; it should include the time zone specified
+ numerically, with the time zone name or abbreviation
+ optionally present as a comment.
+ </p>
+
+ <p>
+ The first `title' line with the package name should start
+ at the left hand margin; the `trailer' line with the
+ maintainer and date details should be preceded by exactly
+ one space. The maintainer details and the date must be
+ separated by exactly two spaces.
+ </p>
+
+ <sect1><heading>Defining alternative changelog formats</heading>
+
+ <p>
+ It is possible to use a different format to the standard
+ one, by providing a parser for the format you wish to
+ use.
+ </p>
+ <p>
+ A changelog parser must not interact with the user at
+ all.
+ </p>
+ </sect1>
+ </sect>
+
+ <sect id="srcsubstvars"><heading><tt>debian/substvars</tt>
+ and variable substitutions </heading>
+
+ <p>
+ When <prgn>dpkg-gencontrol</prgn>,
+ <prgn>dpkg-genchanges</prgn> and <prgn>dpkg-source</prgn>
+ generate control files they do variable substitutions on
+ their output just before writing it. Variable
+ substitutions have the form
+ <tt>${<var>variable-name</var>}</tt>. The optional file
+ <tt>debian/substvars</tt> contains variable substitutions
+ to be used; variables can also be set directly from
+ <tt>debian/rules</tt> using the <tt>-V</tt> option to the
+ source packaging commands, and certain predefined
+ variables are available.
+ </p>
+
+ <p>
+ The is usually generated and modified dynamically by
+ <tt>debian/rules</tt> targets; in this case it must be
+ removed by the <prgn>clean</prgn> target.
+ </p>
+
+ <p>
+ See <manref name="dpkg-source" section="1"> for full
+ details about source variable substitutions, including the
+ format of <tt>debian/substvars</tt>.</p>
+ </sect>
+
+ <sect id="debianfiles"><heading><tt>debian/files</tt>
+ </heading>
+
+ <p>
+ This file is not a permanent part of the source tree; it
+ is used while building packages to record which files are
+ being generated. <prgn>dpkg-genchanges</prgn> uses it
+ when it generates a <tt>.changes</tt> file.
+ </p>
+
+ <p>
+ It should not exist in a shipped source package, and so it
+ (and any backup files or temporary files such as
+ <tt>files.new</tt>
+ <footnote>
+ <p>
+ <tt>files.new</tt> is used as a temporary file by
+ <prgn>dpkg-gencontrol</prgn> and
+ <prgn>dpkg-distaddfile</prgn> - they write a new
+ version of <tt>files</tt> here before renaming it,
+ to avoid leaving a corrupted copy if an error
+ occurs
+ </p>
+ </footnote>) should be removed by the
+ <prgn>clean</prgn> target. It may also be wise to
+ ensure a fresh start by emptying or removing it at the
+ start of the <prgn>binary</prgn> target.
+ </p>
+
+ <p>
+ <prgn>dpkg-gencontrol</prgn> adds an entry to this file
+ for the <tt>.deb</tt> file that will be created by
+ <prgn>dpkg-deb</prgn> from the control file that it
+ generates, so for most packages all that needs to be done
+ with this file is to delete it in <prgn>clean</prgn>.
+ </p>
+
+ <p>
+ If a package upload includes files besides the source
+ package and any binary packages whose control files were
+ made with <prgn>dpkg-gencontrol</prgn> then they should be
+ placed in the parent of the package's top-level directory
+ and <prgn>dpkg-distaddfile</prgn> should be called to add
+ the file to the list in <tt>debian/files</tt>.</p>
+ </sect>
+
+ <sect id="restrictions"><heading>Restrictions on objects in source packages
+ </heading>
+
+ <p>
+ The source package may not contain any hard links
+ <footnote>
+ <p>
+ This is not currently detected when building source
+ packages, but only when extracting
+ them.
+ </p>
+ </footnote>
+ <footnote>
+ <p>
+ Hard links may be permitted at some point in the
+ future, but would require a fair amount of
+ work.
+ </p>
+ </footnote>, device special files, sockets or setuid or
+ setgid files.
+ <footnote>
+ <p>
+ Setgid directories are allowed.
+ </p>
+ </footnote>
+ </p>
+ </sect>
+ <sect id="descriptions"><heading>Descriptions of packages - the
+ <tt>Description</tt> field </heading>
+
+ <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>
+
+ <sect1><heading>Notes about writing descriptions
+ </heading>
+
+ <p>
+ The single line synopsis should be kept brief - certainly
+ under 80 characters.
+ </p>
+
+ <p>
+ Do not include the package name in the synopsis line. The
+ display software knows how to display this already, and you
+ do not need to state it. Remember that in many situations
+ the user may only see the synopsis line - make it as
+ informative as you can.
+ </p>
+
+ <p>
+ Do not try to continue the single line synopsis into the
+ extended description. This will not work correctly when
+ the full description is displayed, and makes no sense
+ where only the summary (the single line synopsis) is
+ available.
+ </p>
+
+ <p>
+ The extended description should describe what the package
+ does and how it relates to the rest of the system (in terms
+ of, for example, which subsystem it is which part of).
+ </p>
+
+ <p>
+ The description field needs to make sense to anyone, even
+ people who have no idea about any of the things the
+ package deals with.
+ <footnote>
+ <p>
+ The blurb that comes with a program in its
+ announcements and/or <prgn>README</prgn> files is
+ rarely suitable for use in a description. It is
+ usually aimed at people who are already in the
+ community where the package is used.
+ </p>
+ </footnote>
+ </p>
+
+ <p>
+ Put important information first, both in the synopsis and
+ extended description. Sometimes only the first part of the
+ synopsis or of the description will be displayed. You can
+ assume that there will usually be a way to see the whole
+ extended description.
+ </p>
+
+ <p>
+ You may include information about dependencies and so forth
+ in the extended description, if you wish.
+ </p>
+
+ <p>
+ Do not use tab characters. Their effect is not predictable.
+ </p>
+
+ </sect1>
+ </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 should be the files <tt>preinst</tt>,
+ <tt>postinst</tt>, <tt>prerm</tt> and <tt>postrm</tt> in the
+ control area of the package. They must be proper executable
+ files; if they are scripts (which is recommended) they must
+ start with the usual <tt>#!</tt> convention. They should be
+ readable and executable to anyone, and not world-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>
+ It is necessary for the error recovery procedures that the
+ scripts be idempotent: i.e., invoking the same script several
+ times in the same situation should do no harm. If the first
+ call failed, or aborted half way through for some reason,
+ the second call should merely do the things that were left
+ undone the first time, if any, and exit with a success
+ status.
+ </p>
+
+ <p>
+ When a package is upgraded a combination of the scripts from
+ the old and new packages is called in amongst the other
+ steps of the upgrade procedure. If your scripts are going
+ to be at all complicated you need to be aware of this, and
+ may need to check the arguments to your scripts.
+ </p>
+
+ <p>
+ Broadly speaking the <prgn></prgn> is called before
+ (a particular version of) a package is installed, and the
+ <prgn>postinst</prgn> afterwards; the <prgn>prerm</prgn>
+ before (a version of) a package is removed and the
+ <prgn>postrm</prgn> afterwards.
+ </p>
+ <!--
+ next paragraph by Guy Maor to close bug #2481
+ -->
+
+ <p> Programs called from maintainer scripts should not
+ normally have a path prepended to them. Before installation
+ is started 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 on the <tt>PATH</tt>,
+ should thus be invoked without an absolute
+ pathname. Maintainer scripts should also not reset the
+ <tt>PATH</tt>, though they might choose to modify it by pre-
+ or appending package-specific directories. These
+ considerations really apply to all shell scripts.</p>
+ </sect>
+ <sect>
+ <heading>Maintainer scripts Idempotency</heading>
+
+ <p>
+ It is very important to make maintainer scripts
+ idempotent.
+ <footnote>
+ <p>
+ That means that if it runs successfully or fails
+ and then you call it again it doesn't bomb out,
+ but just ensures that everything is the way it
+ ought to be.
+ </p>
+ </footnote> This is so that if an error occurs, the
+ user interrupts <prgn>dpkg</prgn> or some other
+ unforeseen circumstance happens you don't leave the
+ user with a badly-broken package.
+ </p>
+ </sect>
+ <sect>
+ <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 <tt>/dev/tty</tt>, since
+ <prgn>dpkg</prgn> will at some point redirect scripts'
+ standard input and output so that it can log the
+ installation process. Likewise, because these scripts
+ may be executed with standard output redirected into a
+ pipe for logging purposes, Perl scripts should set
+ unbuffered output by setting <tt>$|=1</tt> so that the
+ output is printed immediately rather than being
+ buffered.
+ </p>
+
+ <p>
+ Each script should return a zero exit status for
+ success, or a nonzero one for failure.
+ </p>
+ </sect>
+
+ <sect id="mscriptsinstact"><heading>Summary of ways maintainer
+ scripts are called
+ </heading>
+
+ <p>
+ <list compact="compact">
+ <item>
+ <p><var>new-preinst</var> <tt>install</tt></p>
+ </item>
+ <item>
+ <p><var>new-preinst</var> <tt>install</tt>
+ <var>old-version</var></p>
+ </item>
+ <item>
+ <p><var>new-preinst</var> <tt>upgrade</tt>
+ <var>old-version</var></p>
+ </item>
+ <item>
+ <p><var>old-preinst</var> <tt>abort-upgrade</tt>
+ <var>new-version</var>
+ </p>
+ </item>
+ </list>
+
+ <p>
+ <list compact="compact">
+ <item>
+ <p><var>postinst</var> <tt>configure</tt>
+ <var>most-recently-configured-version</var></p>
+ </item>
+ <item>
+ <p><var>old-postinst</var> <tt>abort-upgrade</tt>
+ <var>new version</var></p>
+ </item>
+ <item>
+ <p><var>conflictor's-postinst</var> <tt>abort-remove</tt>
+ <tt>in-favour</tt> <var>package</var>
+ <var>new-version</var></p>
+ </item>
+ <item>
+ <p>
+ <var>deconfigured's-postinst</var>
+ <tt>abort-deconfigure</tt> <tt>in-favour</tt>
+ <var>failed-install-package</var> <var>version</var>
+ <tt>removing</tt> <var>conflicting-package</var>
+ <var>version</var>
+ </p>
+ </item>
+ </list>
+
+ <p>
+ <list compact="compact">
+ <item>
+ <p><var>prerm</var> <tt>remove</tt></p>
+ </item>
+ <item>
+ <p><var>old-prerm</var> <tt>upgrade</tt>
+ <var>new-version</var></p>
+ </item>
+ <item>
+ <p><var>new-prerm</var> <tt>failed-upgrade</tt>
+ <var>old-version</var></p>
+ </item>
+ <item>
+ <p><var>conflictor's-prerm</var> <tt>remove</tt>
+ <tt>in-favour</tt> <var>package</var>
+ <var>new-version</var></p>
+ </item>
+ <item>
+ <p>
+ <var>deconfigured's-prerm</var> <tt>deconfigure</tt>
+ <tt>in-favour</tt> <var>package-being-installed</var>
+ <var>version</var> <tt>removing</tt>
+ <var>conflicting-package</var>
+ <var>version</var>
+ </p>
+ </item>
+ </list>
+
+ <p>
+ <list compact="compact">
+ <item>
+ <p><var>postrm</var> <tt>remove</tt></p>
+ </item>
+ <item>
+ <p><var>postrm</var> <tt>purge</tt></p>
+ </item>
+ <item>
+ <p>
+ <var>old-postrm</var> <tt>upgrade</tt>
+ <var>new-version</var></p>
+ </item>
+ <item>
+ <p><var>new-postrm</var> <tt>failed-upgrade</tt>
+ <var>old-version</var></p>
+ </item>
+ <item>
+ <p><var>new-postrm</var> <tt>abort-install</tt></p>
+ </item>
+ <item>
+ <p><var>new-postrm</var> <tt>abort-install</tt>
+ <var>old-version</var></p>
+ </item>
+ <item>
+ <p><var>new-postrm</var> <tt>abort-upgrade</tt>
+ <var>old-version</var></p>
+ </item>
+ <item>
+ <p>
+ <var>disappearer's-postrm</var> <tt>disappear</tt>
+ <var>overwriter</var>
+ <var>overwriter-version</var></p></item>
+ </list>
+ </p>
+
+
+ <sect id="unpackphase"><heading>Details of unpack phase of
+ installation or upgrade
+ </heading>
+
+ <p>
+ The procedure on installation/upgrade/overwrite/disappear
+ (i.e., when running <tt>dpkg --unpack</tt>, or the unpack
+ stage of <tt>dpkg
+ --install</tt>) is as follows. In each case if an error occurs the
+ actions in are general run backwards - this means that the maintainer
+ scripts are run with different arguments in reverse order. These are
+ the `error unwind' calls listed below.
+
+ <enumlist>
+ <item>
+ <p>
+ <enumlist>
+ <item>
+ <p>If a version the package is already
+ installed, call
+ <example>
+ <var>old-prerm</var> upgrade <var>new-version</var>
+ </example></p>
+ </item>
+ <item>
+ <p>
+ If this gives an error (i.e., a non-zero exit
+ status), dpkg will attempt instead:
+ <example>
+ <var>new-prerm</var> failed-upgrade <var>old-version</var>
+ </example>
+ Error unwind, for both the above cases:
+ <example>
+ <var>old-postinst</var> abort-upgrade <var>new-version</var>
+ </example>
+ </p>
+ </item>
+ </enumlist>
+ </p>
+ </item>
+ <item>
+ <p>If a `conflicting' package is being removed at the same time:
+ <enumlist>
+ <item>
+ <p>
+ If any packages depended on that conflicting
+ package and <tt>--auto-deconfigure</tt> is
+ specified, call, for each such package:
+ <example>
+ <var>deconfigured's-prerm</var> deconfigure \
+ in-favour <var>package-being-installed</var> <var>version</var> \
+ removing <var>conflicting-package</var> <var>version</var>
+ </example>
+ Error unwind:
+ <example>
+ <var>deconfigured's-postinst</var> abort-deconfigure \
+ in-favour <var>package-being-installed-but-failed</var> <var>version</var> \
+ removing <var>conflicting-package</var> <var>version</var>
+ </example>
+ The deconfigured packages are marked as
+ requiring configuration, so that if
+ <tt>--install</tt> is used they will be
+ configured again if possible.</p>
+ </item>
+ <item>
+ <p>To prepare for removal of the conflicting package, call:
+ <example>
+ <var>conflictor's-prerm</var> remove in-favour <var>package</var> <var>new-version</var>
+ </example>
+ Error unwind:
+ <example>
+ <var>conflictor's-postinst</var> abort-remove \
+ in-favour <var>package</var> <var>new-version</var>
+ </example>
+ </p>
+ </item>
+ </enumlist>
+ </p>
+ </item>
+ <item>
+ <p>
+ <enumlist>
+ <item>
+ <p>If the package is being upgraded, call:
+ <example>
+ <var>new-preinst</var> upgrade <var>old-version</var>
+ </example></p>
+ </item>
+ <item>
+ <p>
+ Otherwise, if the package had some configuration
+ files from a previous version installed (i.e., it
+ is in the `configuration files only' state):
+ <example>
+ <var>new-preinst</var> install <var>old-version</var>
+ </example></p>
+
+ <item>
+ <p>Otherwise (i.e., the package was completely purged):
+ <example>
+ <var>new-preinst</var> install
+ </example>
+ Error unwind versions, respectively:
+ <example>
+ <var>new-postrm</var> abort-upgrade <var>old-version</var>
+ <var>new-postrm</var> abort-install <var>old-version</var>
+ <var>new-postrm</var> abort-install
+ </example>
+ </p>
+ </item>
+ </enumlist>
+ </p>
+ </item>
+ <item>
+
+ <p>
+ The new package's files are unpacked, overwriting any
+ that may be on the system already, for example any
+ from the old version of the same package or from
+ another package (backups of the old files are left
+ around, and if anything goes wrong 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 contains files which
+ are on the system in another package, unless
+ <tt>Replaces</tt> is used (see <ref id="replaces">).
+ Currently the <tt>--force-overwrite</tt> flag is
+ enabled, downgrading it to a warning, but this may not
+ always be the case.
+ </p>
+
+ <p>
+ It is a more serious error for a package to contain a
+ plain file or other kind of 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>
+ <p>
+ Part of the problem is due to what is arguably a
+ bug in <prgn>dpkg</prgn>.
+ </p>
+ </footnote>
+ </p>
+
+ <p>
+ A directory will never be replaced by a symbolic links
+ to a directory or vice versa; instead, the existing
+ state (symlink or not) will be left alone and
+ <prgn>dpkg</prgn> will follow the symlink if there is
+ one.</p>
+ </item>
+
+ <item>
+
+ <p><enumlist>
+ <item>
+ <p>If the package is being upgraded, call
+ <example>
+ <var>old-postrm</var> upgrade <var>new-version</var>
+ </example></p>
+ </item>
+ <item>
+ <p>If this fails, <prgn>dpkg</prgn> will attempt:
+ <example>
+ <var>new-postrm</var> failed-upgrade <var>old-version</var>
+ </example>
+ Error unwind, for both cases:
+ <example>
+ <var>old-preinst</var> abort-upgrade <var>new-version</var>
+ </example>
+ </p>
+ </item>
+ </enumlist>
+ <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>
+ <p>
+ Any files which were in the old version of the package
+ but not in the new are removed.</p>
+ </item>
+ <item>
+ <p>The new file list replaces the old.</p>
+ </item>
+ <item>
+ <p>The new maintainer scripts replace the old.</p>
+ </item>
+
+ <item>
+ <p>Any packages all of whose files have been overwritten during the
+ installation, and which aren't required for
+ dependencies, are considered to have been removed.
+ For each such package,
+ <enumlist>
+ <item>
+ <p><prgn>dpkg</prgn> calls:
+ <example>
+ <var>disappearer's-postrm</var> disappear \
+ <var>overwriter</var> <var>overwriter-version</var>
+ </example>
+ </p>
+ </item>
+ <item>
+ <p>The package's maintainer scripts are removed.
+ </p>
+ </item>
+ <item>
+ <p>
+ It is noted in the status database as being in a
+ sane state, namely not installed (any conffiles
+ it may have are ignored, rather than being
+ removed by <prgn>dpkg</prgn>). Note that
+ disappearing packages do not have their prerm
+ called, because <prgn>dpkg</prgn> doesn't know
+ in advance that the package is going to
+ vanish.
+ </p>
+ </item>
+ </enumlist>
+ </p>
+ </item>
+ <item>
+ <p>
+ Any files in the package we're unpacking that are also
+ listed in the file lists of other packages are removed
+ from those lists. (This will lobotomize the file list
+ of the `conflicting' package if there is one.)
+ </p>
+ </item>
+ <item>
+ <p>
+ The backup files made during installation, above, are
+ deleted.
+ </p>
+ </item>
+
+ <item>
+ <p>
+ The new package's status is now sane, and recorded as
+ `unpacked'. Here is another point of no return - if
+ the conflicting package's removal fails we do not
+ unwind the rest of the installation; the conflicting
+ package is left in a half-removed limbo.
+ </p>
+ </item>
+ <item>
+ <p>
+ If there was a conflicting package we go and do the
+ removal actions (described below), starting with the
+ removal of the conflicting package's files (any that
+ are also in the package being installed have already
+ been removed from the conflicting package's file list,
+ and so do not get removed now).
+ </p>
+ </item>
+ </enumlist>
+ </p>
+ </sect>
+
+ <sect><heading>Details of configuration</heading>
+
+ <p>
+ When we configure a package (this happens with <tt>dpkg
+ --install</tt>, or with <tt>--configure</tt>), we first
+ update the conffiles and then call:
+ <example>
+ <var>postinst</var> configure <var>most-recently-configured-version</var>
+ </example>
+ </p>
+
+ <p>
+ No attempt is made to unwind after errors during
+ configuration.
+ </p>
+
+ <p>
+ If there is no most recently configured version
+ <prgn>dpkg</prgn> will pass a null argument; older versions
+ of dpkg may pass <tt><unknown></tt> (including the
+ angle brackets) in this case. Even older ones do not pass a
+ second argument at all, under any circumstances.
+ </p>
+ </sect>
+
+ <sect><heading>Details of removal and/or configuration purging
+ </heading>
+
+ <p>
+ <enumlist>
+ <item>
+ <p>
+ <example>
+ <var>prerm</var> remove
+ </example>
+ </p>
+ </item>
+ <item>
+ <p>
+ The package's files are removed (except conffiles).
+ </p>
+ </item>
+ <item>
+ <p><example>
+ <var>postrm</var> remove
+ </example></p>
+ </item>
+ <item>
+ <p>All the maintainer scripts except the postrm are removed.
+ </p>
+
+ <p>
+ If we aren't purging the package we stop here. Note
+ that packages which have no postrm and no conffiles
+ are automatically purged when removed, as there is no
+ difference except for the <prgn>dpkg</prgn>
+ status.</p>
+ </item>
+ <item>
+ <p>
+ The conffiles and any backup files (<tt>~</tt>-files,
+ <tt>#*#</tt> files, <tt>%</tt>-files,
+ <tt>.dpkg-{old,new,tmp}</tt>, etc.) are removed.</p>
+ </item>
+ <item>
+ <p><example>
+ <var>postrm</var> purge
+ </example></p>
+ </item>
+ <item>
+ <p>The package's file list is removed.</p>
+ </item>
+ </enumlist>
+ No attempt is made to unwind after errors during
+ removal.</p>
+ </sect>
+ </chapt>
+
+
+ <chapt id="relationships"><heading>Declaring relationships between
+ packages </heading>
+
+ <p>
+ Packages can declare in their control file that they have
+ certain relationships to other packages - for example, that
+ they may not be installed at the same time as certain other
+ packages, and/or that they depend on the presence of others,
+ or that they should overwrite files in certain other packages
+ if present.
+ </p>
+
+ <p>
+ This is done using the <tt>Depends</tt>, <tt>Recommends</tt>,
+ <tt>Suggests</tt>, <tt>Conflicts</tt>, <tt>Provides</tt> and
+ <tt>Replaces</tt> control file fields.
+ </p>
+
+ <p>
+ Source packages may declare relationships to binary packages,
+ saying that they require certain binary packages being
+ installed or absent at the time of building the package.
+ </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>
+
+ <sect id="depsyntax"><heading>Syntax of relationship fields
+ </heading>
+
+ <p>
+ These fields all have a uniform syntax. They are a list of
+ package names separated by commas.
+ </p>
+
+ <p>
+ In <tt>Depends</tt>, <tt>Recommends</tt>, <tt>Suggests</tt>,
+ <tt>Pre-Depends</tt>, <tt>Build-Depends</tt> and
+ <tt>Build-Depends-Indep</tt>(the fields which declare
+ dependencies of the package in which they occur on other
+ packages) these package names may also be lists of
+ alternative package names, separated by vertical bar symbols
+ <tt>|</tt> (pipe symbols).
+ </p>
+
+ <p>
+ All the fields except <tt>Provides</tt> may restrict their
+ applicability to particular versions of each named package.
+ This is done in parentheses after each individual package
+ name; the parentheses should contain a relation from the
+ list below followed by a version number, in the format
+ described in <ref id="versions">.
+ </p>
+
+ <p>
+ The relations allowed are <tt><<</tt>, <tt><=</tt>,
+ <tt>=</tt>, <tt>>=</tt> and <tt>>></tt> for
+ strictly earlier, earlier or equal, exactly equal, later or
+ equal and strictly later, respectively. The forms
+ <tt><</tt> and <tt>></tt> were used to mean
+ earlier/later or equal, rather than strictly earlier/later,
+ so they should not appear in new packages (though
+ <prgn>dpkg</prgn> still supports them).
+ </p>
+
+ <p>
+ Whitespace may appear at any point in the version
+ specification, and must appear where it's necessary to
+ disambiguate; it is not otherwise significant. For
+ consistency and in case of future changes to
+ <prgn>dpkg</prgn> it is recommended that a single space be
+ used after a version relationship and before a version
+ number; it is usual also to put a single space after each
+ comma, on either side of each vertical bar, and before each
+ open parenthesis.
+ </p>
+
+ <p>
+ For example:
+ <example>
+ Package: metamail
+ Version: 2.7-3
+ Depends: libc5 (>= 5.2.18-4), mime-support, csh | tcsh
+ </example>
+ </p>
+
+ <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 done in brackets after each individual package name and
+ the optional version specification. The brackets enclose a
+ list of Debian architecture names separated by whitespace.
+ An exclamation mark may be prepended to each name. 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>
+ 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>
+ </sect>
+
+ <sect>
+ <heading>Binary Dependencies - <tt>Depends</tt>,
+ <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Pre-Depends</tt>
+ </heading>
+
+ <p>
+ These four fields are used to declare a dependency by one
+ package on another. They appear in the depending package's
+ control file.
+ </p>
+
+ <p>
+ All but <tt>Pre-Depends</tt> and <tt>Conflicts</tt>
+ (discussed below) take effect <em>only</em> when a package
+ is to be configured. They do not prevent a package being on
+ the system in an unconfigured state while its dependencies
+ are unsatisfied, and it is possible to replace a package
+ whose dependencies are satisfied and which is properly
+ installed with a different version whose dependencies are
+ not and cannot be satisfied; when this is done the depending
+ package will be left unconfigured (since attempts to
+ configure it will give errors) and will not function
+ properly.
+ </p>
+
+ <p>
+ For this reason packages in an installation run are usually
+ all unpacked first and all configured later; this gives
+ later versions of packages with dependencies on later
+ versions of other packages the opportunity to have their
+ dependencies satisfied.
+ </p>
+
+ <p>
+ Thus <tt>Depends</tt> allows package maintainers to impose
+ an order in which packages should be configured.
+ <taglist>
+ <tag><tt>Depends</tt></tag>
+ <item>
+
+ <p>This declares an absolute dependency.
+ </p>
+
+ <p>
+ The <tt>Depends</tt> field should be used if the
+ depended-on package is required for the depending
+ package to provide a significant amount of
+ functionality.</p>
+ </item>
+
+ <tag><tt>Recommends</tt></tag>
+ <item>
+ <p>This declares a strong, but not absolute, dependency.
+ </p>
+
+ <p>
+ The <tt>Recommends</tt> field should list packages
+ that would be found together with this one in all but
+ unusual installations.</p>
+ </item>
+
+ <tag><tt>Suggests</tt></tag>
+ <item>
+
+ <p>
+ This is used to declare that one package may be more
+ useful with one or more others. Using this field
+ tells the packaging system and the user that the
+ listed packages are related to this one and can
+ perhaps enhance its usefulness, but that installing
+ this one without them is perfectly reasonable.
+ </p>
+
+ </item>
+
+ <tag><tt>Pre-Depends</tt></tag>
+ <item>
+
+ <p>
+ This field is like <tt>Depends</tt>, except that it
+ also forces <prgn>dpkg</prgn> to complete installation
+ of the packages named before even starting the
+ installation of the package which declares the
+ Pre-dependency.
+ </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>
+ When the package declaring it is being configured, a
+ <tt>Pre-Dependency</tt> will be considered satisfied
+ only if the depending package has been correctly
+ configured, just as if an ordinary <tt>Depends</tt>
+ had been used.
+ </p>
+
+ <p>
+ However, when a package declaring a Pre-dependency is
+ being unpacked the predependency can be satisfied even
+ if the depended-on package(s) are only unpacked or
+ half-configured, provided that they have been
+ configured correctly at some point in the past (and
+ not removed or partially removed since). In this case
+ both the previously-configured and currently unpacked
+ or half-configured versions must satisfy any version
+ clause in the <tt>Pre-Depends</tt> field.
+ </p>
+ </item>
+ </taglist>
+ </p>
+ <p>
+ When selecting which level of dependency to use you should
+ consider how important the depended-on package is to the
+ functionality of the one declaring the dependency. Some
+ packages are composed of components of varying degrees of
+ importance. Such a package should list using
+ <tt>Depends</tt> the package(s) which are required by the
+ more important components. The other components'
+ requirements may be mentioned as Suggestions or
+ Recommendations, as appropriate to the components' relative
+ importance.
+ </p>
+
+
+ <sect id="conflicts"><heading>Alternative binary packages -
+ <tt>Conflicts</tt> and <tt>Replaces</tt>
+ </heading>
+
+ <p>
+ When one binary package declares a conflict with another
+ <prgn>dpkg</prgn> will refuse to allow them to be installed
+ on the system at the same time.
+ </p>
+
+ <p>
+ If one package is to be installed, the other must be removed
+ first - if the package being installed is marked as
+ replacing (<ref id="replaces">) the one on the system, or
+ the one on the system is marked as deselected, or both
+ packages are marked <tt>Essential</tt>, then
+ <prgn>dpkg</prgn> will automatically remove the package
+ which is causing the conflict, otherwise it will halt the
+ installation of the new package with an error. This
+ mechanism specifically doesn't work 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 something.
+ </p>
+
+ <p>
+ A <tt>Conflicts</tt> entry should almost never have an
+ `earlier than' version clause. This would prevent
+ <prgn>dpkg</prgn> from upgrading or installing the package
+ which declared such a conflict until the upgrade or removal
+ of the conflicted-with package had been completed.
+ </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>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
+ <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Conflicts</tt>,
+ <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt> may
+ mention virtual packages.
+ </p>
+
+ <p>
+ A virtual package is one which appears in the
+ <tt>Provides</tt> control file field of another package.
+ The effect is as if the package(s) which provide a
+ particular virtual package name had been listed by name
+ everywhere the virtual package name appears.
+ </p>
+
+ <p>
+ If there are both a real and a virtual package of the same
+ name then the dependency may be satisfied (or the conflict
+ caused) by either the real package or any of the virtual
+ packages which provide it. This is so that, for example,
+ supposing we have
+ <example>
+ Package: vm
+ Depends: emacs
+ </example>
+ and someone else releases an xemacs package they can say
+ <example>
+ Package: xemacs
+ Provides: emacs
+ </example> and all will work in the interim (until a purely
+ virtual package name is decided on and the <tt>emacs</tt>
+ and <tt>vm</tt> packages are changed to use it).
+ </p>
+
+ <p>
+ If a dependency or a conflict has a version number attached
+ then only real packages will be considered to see whether
+ the relationship is satisfied (or the prohibition violated,
+ for a conflict) - it is assumed that a real package which
+ provides virtual package is not of the `right' version. So,
+ a <tt>Provides</tt> field may not contain version numbers,
+ and the version number of the concrete package which
+ provides a particular virtual package will not be looked at
+ when considering a dependency on or conflict with the
+ virtual package name.
+ </p>
+
+ <p>
+ It is likely that the ability will be added in a future
+ release of <prgn>dpkg</prgn> to specify a version number for
+ each virtual package it provides. This feature is not yet
+ present, however, and is expected to be used only
+ infrequently.
+ </p>
+
+ <p>
+ If you want to specify which of a set of real packages should be the
+ default to satisfy a particular dependency on a virtual package, you
+ should list the real package as an alternative before the virtual.
+ </p>
+ </sect>
+
+
+ <sect id="replaces"><heading><tt>Replaces</tt> - overwriting
+ files and replacing packages
+ </heading>
+
+ <p>
+ The <tt>Replaces</tt> control file field has two purposes,
+ which come into play in different situations.
+ </p>
+
+ <p>
+ Virtual packages (<ref id="virtual">) are not considered
+ when looking at a <tt>Replaces</tt> field - the packages
+ declared as being replaced must be mentioned by their real
+ names.
+ </p>
+
+ <sect1><heading>Overwriting files in other packages
+ </heading>
+
+ <p>
+ Firstly, as mentioned before, it is usually an error for a
+ package to contains files which are on the system in
+ another package, though currently the
+ <tt>--force-overwrite</tt> flag is enabled by default,
+ downgrading the error to a warning,
+ </p>
+
+ <p>
+ If the overwriting package declares that it replaces the
+ one containing the file being overwritten then
+ <prgn>dpkg</prgn> will proceed, and replace the file from
+ the old package with that from the new. The file will no
+ longer be listed as `owned' by the old package.
+ </p>
+
+ <p>
+ If a package is completely replaced in this way, so that
+ <prgn>dpkg</prgn> does not know of any files it still
+ contains, it is considered to have disappeared. It will
+ be marked as not wanted on the system (selected for
+ removal) and not installed. Any conffiles details noted
+ in the package will be ignored, as they will have been
+ taken over by the replacing package(s). The package's
+ <prgn>postrm</prgn> script will be run to allow the
+ package to do any final cleanup required. See <ref
+ id="mscriptsinstact">.
+ </p>
+
+ <p>
+ In the future <prgn>dpkg</prgn> will discard files which
+ overwrite those from another package which declares that
+ it replaces the one being installed (so that you can
+ install an older version of a package without problems).
+ </p>
+
+ <p>
+ This usage of <tt>Replaces</tt> only takes effect when
+ both packages are at least partially on the system at
+ once, so that it can only happen if they do not conflict
+ or if the conflict has been overridden.</p>
+ </sect1>
+
+ <sect1><heading>Replacing whole packages, forcing their
+ removal
+ </heading>
+
+ <p>
+ Secondly, <tt>Replaces</tt> allows 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 effects do not interfere with each other.
+ </p>
+ </sect1>
+ </sect>
+
+ <sect><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>
+ A source package may declare a dependency or a conflict on a
+ binary package. This is done with the control file fields
+ <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
+ <tt>Build-Conflicts</tt>, and <tt>Build-Conflicts-Indep</tt>. Their
+ semantics is that the dependencies and conflicts they define
+ must be satisfied (as defined earlier for binary packages),
+ when one of the targets in <tt>debian/rules</tt> that the
+ particular field applies to is invoked.
+
+ <taglist>
+ <tag><tt>Build-Depends</tt>, <tt>Build-Conflicts</tt></tag>
+ <item>
+ <p>
+ The <tt>Build-Depends</tt> and
+ <tt>Build-Conflicts</tt> fields apply to the targets
+ <tt>build</tt>, <tt>binary</tt>, <tt>binary-arch</tt>
+ and <tt>binary-indep</tt>.
+ </p>
+ </item>
+ <tag><tt>Build-Depends-Indep</tt>, <tt>Build-Conflicts-Indep</tt></tag>
+ <item>
+ <p>
+ The <tt>Build-Depends-Indep</tt> and
+ <tt>Build-Conflicts-Indep</tt> fields apply to the
+ targets <tt>binary</tt> and <tt>binary-indep</tt>.
+ </p>
+ </item>
+ </taglist>
+
+ </p>
+
+ </sect>
+ </chapt>
+
+
+ <chapt id="conffiles"><heading>Configuration file handling
+ </heading>
+
+ <p>
+ <prgn>dpkg</prgn> can do a certain amount of automatic
+ handling of package configuration files.
+ </p>
+
+ <p>
+ Whether this mechanism is appropriate depends on a number of
+ factors, but basically there are two approaches to any
+ particular configuration file.
+ </p>
+
+ <p>
+ The easy method is to ship a best-effort configuration in the
+ package, and use <prgn>dpkg</prgn>'s conffile mechanism to
+ handle updates. If the user is unlikely to want to edit the
+ file, but you need them to be able to without losing their
+ changes, and a new package with a changed version of the file
+ is only released infrequently, this is a good approach.
+ </p>
+
+ <p>
+ The hard method is to build the configuration file from
+ scratch in the <prgn>postinst</prgn> script, and to take the
+ responsibility for fixing any mistakes made in earlier
+ versions of the package automatically. This will be
+ appropriate if the file is likely to need to be different on
+ each system.
+ </p>
+
+
+ <chapt id="sharedlibs"><heading>Shared libraries
+ </heading>
+
+ <p>
+ Packages containing shared libraries must be constructed with
+ a little care to make sure that the shared library is always
+ available. This is especially important for packages whose
+ shared libraries are vitally important, such as the libc.
+ </p>
+
+ <p>
+ Firstly, your package should install the shared libraries
+ under their normal names. For example, the
+ <prgn>libgdbm1</prgn> package should install
+ <tt>libgdbm.so.1.7.3</tt> as
+ <tt>/usr/lib/libgdbm.so.1.7.3</tt>. The files should not be
+ renamed or re-linked by any prerm or postrm scripts;
+ <prgn>dpkg</prgn> will take care of renaming things safely
+ without affecting running programs, and attempts to interfere
+ with this are likely to lead to problems.
+ </p>
+
+ <p>
+ Secondly, your package should include the symlink that
+ <prgn>ldconfig</prgn> would create for the shared libraries.
+ For example, the <prgn>libgdbm1</prgn> package should include
+ a symlink from <tt>/usr/lib/libgdbm.so.1</tt> to
+ <tt>libgdbm.so.1.7.3</tt>. This is needed so that
+ <prgn>ld.so</prgn> can find the library in between the time
+ <prgn>dpkg</prgn> installs it and <prgn>ldconfig</prgn> is run
+ in the <prgn>postinst</prgn> script. Furthermore, older
+ versions of the package management system required the library
+ must be placed before the symlink pointing to it in the
+ <tt>.deb</tt> file. This is so that by the time
+ <prgn>dpkg</prgn> comes to install the symlink (overwriting
+ the previous symlink pointing at an older version of the
+ library) the new shared library is already in place.
+ Unfortunately, this was not not always possible, since it
+ highly depends on the behavior of the file system. Some
+ file systems (such as reiserfs) will reorder the files so it
+ doesn't matter in what order you create them. Starting with
+ release <tt>1.7.0</tt> <prgn>dpkg</prgn> will reorder the
+ files itself when building a package.
+ </p>
+
+ <!--
+ next Paragraph added to close Bug #5299, Guy Maor
+ -->
+
+ <p>
+ Thirdly, the development package should contain a symlink for
+ the shared library without a version number. For example, the
+ <tt>libgdbm1-dev</tt> package should include a symlink from
+ <tt>/usr/lib/libgdm.so</tt> to <tt>libgdm.so.1.7.3</tt>. This
+ symlink is needed by <prgn>ld</prgn> when compiling packages
+ as it will only look for <tt>libgdm.so</tt> and
+ <tt>libgdm.a</tt> when compiling dynamically or statically,
+ respectively.
+ </p>
+
+ <!--
+ next paragraph changed by Christian Schwarz (see policy weekly #6)
+ -->
+
+ <p>
+ Any package installing shared libraries in a directory that's listed
+ in <tt>/etc/ld.so.conf</tt> or in one of the default library
+ directories of <prgn>ld.so</prgn> (currently, these are <tt>/usr/lib</tt>
+ and <tt>/lib</tt>) must call <prgn>ldconfig</prgn> in its <prgn>postinst</prgn>
+ script if and only if the first argument is `configure'. However, it
+ is important not to call <prgn>ldconfig</prgn> in the postrm or preinst
+ scripts in the case where the package is being upgraded (see <ref
+ id="unpackphase">), as <prgn>ldconfig</prgn> will see the temporary names
+ that <prgn>dpkg</prgn> uses for the files while it is
+ installing them and will make the shared library links point
+ to them, just before <prgn>dpkg</prgn> continues the
+ installation and removes the links!
+ </p>
+
+ <!--
+ moved from section 2.2 , DMorris
+ -->
+
+ <sect id="shlibs"><heading>The <tt>shlibs</tt> File Format
+ </heading>
+
+ <p>
+ This file is for use by <prgn>dpkg-shlibdeps</prgn> and is
+ required when your package provides shared libraries.
+ </p>
+
+ <p>
+ Each line is of the form:
+ <example>
+ <var>library-name</var> <var>version-or-soname</var> <var>dependencies ...</var>
+ </example>
+ </p>
+
+ <p>
+ <var>library-name</var> is the name of the shared library,
+ for example <tt>libc5</tt>.
+ </p>
+
+ <p>
+ <var>version-or-soname</var> is the soname of the library -
+ i.e., the thing that must exactly match for the library to be
+ recognized by <prgn>ld.so</prgn>. Usually this is major
+ version number of the library.
+ </p>
+
+ <p>
+ <var>dependencies</var> has the same syntax as a dependency
+ field in a binary package control file. It should give
+ details of which package(s) are required to satisfy a binary
+ built against the version of the library contained in the
+ package. See <ref id="depsyntax">.
+ </p>
+
+ <p>
+ For example, if the package <tt>foo</tt> contains
+ <tt>libfoo.so.1.2.3</tt>, where the soname of the library is
+ <tt>libfoo.so.1</tt>, and the first version of the package
+ which contained a minor number of at least <tt>2.3</tt> was
+ <var>1.2.3-1</var>, then the package's <var>shlibs</var>
+ could say:
+ <example>
+ libfoo 1 foo (>= 1.2.3-1)
+ </example>
+ </p>
+
+ <p>
+ The version-specific dependency is to avoid warnings from
+ <prgn>ld.so</prgn> about using older shared libraries with
+ newer binaries.</p>
+ </sect>
+
+ <sect><heading>Further Technical information on
+ <tt>shlibs</tt></heading>
+
+
+ <!--
+ following section mostly provided by Heiko Schlittermann
+ edited by DMorris
+ -->
+
+ <sect1><heading><em>What</em> are the <tt>shlibs</tt> files?
+ </heading>
+
+ <p>
+ The <tt>debian/shlibs</tt> file provides a way of checking
+ for shared library dependencies on packaged binaries.
+ They are intended to be used by package maintainers to
+ make their lives easier.
+ </p>
+
+ <p>
+ Other <tt>shlibs</tt> files that exist on a Debian system are
+ <list>
+ <item> <p><tt>/etc/dpkg/shlibs.default</tt></p></item>
+ <item> <p><tt>/etc/dpkg/shlibs.override</tt></p></item>
+ <item> <p><tt>/var/lib/dpkg/info/*.shlibs</tt></p></item>
+ <item> <p><tt>debian/shlibs.local</tt></p></item>
+ </list>
+ These files are used by <prgn>dpkg-shlibdeps</prgn> when
+ creating a binary package.</p>
+ </sect1>
+
+ <sect1><heading><em>How</em> does <prgn>dpkg-shlibdeps</prgn>
+ work?
+ </heading>
+ <p>
+ <prgn>dpkg-shlibdeps</prgn>
+ determines the shared libraries directly
+ <footnote>
+ <p>
+ Currently, it calls <prgn>ldd</prgn>, but in a
+ forthcoming version it shall call <prgn>objdump</prgn>
+ to to this. This however changes will need a couple of
+ changes in the way that packages are build.
+ </p>
<p>
- In the past, people specified 4 digits in the
- Standards-Version field, like `2.3.0.0'. Since any
- `patch-level changes' don't introduce new policy, it
- was thought it would be better to relax policy and
- only require that the first 3 digits are specified. (4
- digits may still be used if someone wants to do so.)
+ Suppose a binary <tt>foo</tt> directly use a library
+ <tt>libbar</tt> if it is linked with that
+ library. Other libraries that are needed by
+ <tt>libbar</tt> are linked indirectly to <tt>foo</tt>,
+ and the dynamic linker will load the automatically
+ when it loads <tt>libbar</tt>. Using <prgn>ldd</prgn>
+ lists all the libraries, used directly and indirectly;
+ but <prgn>objdump</prgn> only lists the directly
+ linked libraries. A package only needs to depend on
+ the libraries it is directly linked to, since the
+ dependencies for those libraries should automatically
+ pull in the other libraries.</p>
+
+ <p>
+ This change does mean a change in the way packages are
+ build though: currently dpkg-shlibdeps is only run on
+ binaries. But since we will now depend on the
+ libraries to depend on the libraries they need the
+ packages containing those libraries will need to run
+ dpkg-shlibdeps on the libraries.
</p>
- </footnote>
+ <p>
+ A good example where this would help us is the current
+ mess with multiple version of the mesa library. With
+ the ldd-based system every package that uses mesa need
+ to add a dependency on svgalib|svgalib-dummy in order
+ to handle the glide mesa variant. With an
+ objdump-based system this isn't necessary anymore and
+ would have saved everyone a lot of work.
+ </p>
+ <p>
+ Another example: we could update libimlib with a new
+ version that supports a new graphics format called
+ dgf. If we use the old ldd method every package that
+ uses libimlib would need to be recompiled so it would
+ also depend on libdgf or it wouldn't run due to
+ missing symbols. However with the new system packages
+ using libimlib can depend on libimlib itself having
+ the dependency on libgdh and wouldn't need to be
+ updated.
+ </p>
+ </footnote>
+ used by the compiled binaries (and libraries, in a version
+ of <prgn>dpkg-shlibdeps</prgn> coming soon) passed through
+ on its command line.
</p>
-
- <p>
- You should regularly, and especially if your package has
- become out of date, check for the newest Policy Manual
- available and update your package, if necessary. When your
- package complies with the new standards you should update the
- <tt>Standards-Version</tt> source package field and
- release it.</p></sect1>
-
-
- <sect1>
- <heading>Package relationships</heading>
-
- <p>
- Source packages should specify which binary packages they
- require to be installed or not to be installed in order to
- build correctly. For example, if building a package
- requires a certain compiler, then the compiler should be
- specified as a build-time dependency.
- </p>
-
- <p>
- It is not be necessary to explicitly specify build-time
- relationships on a minimal set of packages that are always
- needed to compile, link and put in a Debian package a
- standard "Hello World!" program written in C or C++. The
- required packages are called <em>build-essential</em>, and
- an informational list can be found in
- <tt>/usr/share/doc/build-essential/list</tt> (which is
- contained in the <tt>build-essential</tt> package).
- </p>
-
- <p>
- When specifying the set of build-time dependencies, one
- should list only those packages explicitly required by the
- build. It is not necessary to list packages which are
- required merely because some other package in the list of
- build-time dependencies depends on them. The reason is
- that dependencies change, and you should list only those
- <em>you</em> need. What others need is their business.
- </p>
-
- <p>
- If build-time dependencies are specified, it must be
- possible to build the package and produce working binaries
- on a system with the build-essential packages installed
- and satisfying the build-time relationships (including any
- implied relationships). This
- means in particular that version clauses should be used
- rigorously in build-time relationships so that one cannot
- produce bad or inconsistently configured packages when the
- relationships are properly satisfied.
- </p>
-
- <sect1>
- <heading>Changes to the upstream sources</heading>
-
- <p>
- If changes to the source code are made that are generally
- applicable, they should be sent to the upstream authors
- in whatever form they prefer so as to be included in the
- upstream version of the package.</p>
-
- <p>
- If you need to configure the package differently for
- Debian or for Linux, and the upstream source doesn't
- provide a way to configure it the way you need to, you
- should add such configuration facilities (for example, a new
- <prgn>autoconf</prgn> test or <tt>#define</tt>) and send
- the patch to the upstream authors, with the default set to
- the way they originally had it. You can then easily
- override the default in your <tt>debian/rules</tt> or
- wherever is appropriate.</p>
-
- <p>
- You should make sure that the <prgn>configure</prgn> utility
- detects the correct architecture specification string
- (refer to <ref id="arch-spec"> for details).</p>
-
- <p>
- If you need to edit a <prgn>Makefile</prgn> where
- GNU-style <prgn>configure</prgn> scripts are used, you
- should edit the <tt>.in</tt> files rather than editing the
- <prgn>Makefile</prgn> directly. This allows the user to
- reconfigure the package if necessary. You should
- <em>not</em> configure the package and edit the generated
- <prgn>Makefile</prgn>! This makes it impossible for
- someone else to later reconfigure the package.</p></sect1>
-
-
- <sect1>
- <heading>Documenting your changes</heading>
-
- <p>
- You should document your changes and updates to the source
- package properly in the <tt>debian/changelog</tt> file. (Note
- that mistakes in changelogs are usually best rectified by
- making a new changelog entry rather than "rewriting history"
- by editing old changelog entries)</p>
-
- <p>
- A copy of the file which will be installed in
- <tt>/usr/share/doc/<var>package</var>/copyright</tt> should be
- in <tt>debian/copyright</tt>.</p>
-
- <p>
- In non-experimental packages you must only use a format for
- <tt>debian/changelog</tt> which is supported by the most
- recent released version of <prgn>dpkg</prgn>. If your
- format is not supported and there is general support for
- it you should contact the <prgn>dpkg</prgn> maintainer to
- have the parser script for your format included in the
- <prgn>dpkg</prgn> package. (You will need to agree that
- the parser and its manpage may be distributed under the
- GNU GPL, just as the rest of <prgn>dpkg</prgn>
- is.)</p></sect1>
-
-
- <sect1>
- <heading>Error trapping in makefiles</heading>
-
- <p>
- When <prgn>make</prgn> invokes a command in a makefile
- (including your package's upstream makefiles and the
- <tt>debian/rules</tt>) it does so using <tt>sh</tt>. This
- means that <tt>sh</tt>'s usual bad error handling
- properties apply: if you include a miniature script as one
- of the commands in your makefile you'll find that if you
- don't do anything about it then errors are not detected
- and <prgn>make</prgn> will blithely continue after
- problems.</p>
-
- <p>
- Every time you put more than one shell command (this
- includes using a loop) in a makefile command you
- must make sure that errors are trapped. For
- simple compound commands, such as changing directory and
- then running a program, using <tt>&&</tt> rather
- than semicolon as a command separator is sufficient. For
- more complex commands including most loops and
- conditionals you should include a separate <tt>set -e</tt>
- command at the start of every makefile command that's
- actually one of these miniature shell scripts.</p></sect1>
-
-
- <sect1>
- <heading>Obsolete constructs and libraries</heading>
-
- <p>
- The include file <prgn><varargs.h></prgn> is
- provided to support end-users compiling very old software;
- the library <tt>libtermcap</tt> is provided to support the
- execution of software which has been linked against it
- (either old programs or those such as Netscape which are
- only available in binary form).</p>
-
+
+ <p>
+ For each shared library, <prgn>dpkg-shlibdeps</prgn> needs to know
+ <list compact="compact">
+ <item><p>the package containing the library, and</p></item>
+ <item><p>the library version number,</p></item>
+
+ </list> <p>
+ it scans the following files in this order.
+ <enumlist compact="compact">
+ <item><p><tt>debian/shlibs.local</tt></p></item>
+ <item><p><tt>/etc/dpkg/shlibs.override</tt></p></item>
+ <item><p><tt>/var/lib/dpkg/info/*.shlibs</tt></p></item>
+ <item><p><tt>/etc/dpkg/shlibs.default</tt></p></item>
+ </enumlist></p>
+ </sect1>
+
+ <sect1><heading><em>Who</em> maintains the various
+ <tt>shlibs</tt> files?
+ </heading>
+
+ <p>
+ <list compact="compact">
+ <item>
+ <p><tt>/etc/dpkg/shlibs.default</tt> - the maintainer
+ of dpkg</p>
+ </item>
+ <item>
+ <p>
+ <tt>/var/lib/dpkg/info/<var>package</var>.shlibs</tt>
+ - the maintainer of each package</p>
+ </item>
+ <item>
+ <p>
+ <tt>/etc/dpkg/shlibs.override</tt> - the local
+ system administrator</p>
+ </item>
+ <item>
+ <p><tt>debian/shlibs.local</tt> - the maintainer of
+ the package
+ </p>
+ </item>
+ </list>
+ The <tt>shlibs.default</tt> file is managed by
+ <prgn>dpkg</prgn>. The entries in <tt>shlibs.default</tt>
+ that are provided by <prgn>dpkg</prgn> are just there to
+ fix things until the shared library packages all have
+ <tt>shlibs</tt> files.
+ </p>
+ </sect1>
+
+ <sect1><heading><em>How</em> to use <prgn>dpkg-shlibdeps</prgn> and
+ the <tt>shlibs</tt> files?
+ </heading>
+
+ <sect2><heading>If your package doesn't provide a shared
+ library
+ </heading>
+
+ <p>
+ Put a call to <prgn>dpkg-shlibdeps</prgn> into your
+ <tt>debian/rules</tt> file. If your package contains
+ only binaries (e.g. no scripts) use:
+ <example>
+ dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/*
+ </example>
+ If <prgn>dpkg-shlibdeps</prgn> doesn't complain, you're
+ done. If it does complain you might need to create your
+ own <tt>debian/shlibs.local</tt> file.</p>
+ </sect2>
+
+ <sect2><heading>If your package provides a shared library
+ </heading>
+
+ <p>
+ Create a <tt>debian/shlibs</tt> file and let
+ <tt>debian/rules</tt> install it in the control area:
+ <example>
+ install -m644 debian/shlibs debian/tmp/DEBIAN
+ </example>
+ If your package contains additional binaries see above.
+ </p>
+ </sect2>
+ </sect1>
+
+ <sect1><heading><em>How</em> to write
+ <tt>debian/shlibs.local</tt>
+ </heading>
+
+ <p>
+ This file is intended only as a <em>temporary</em> fix if
+ your binaries depend on a library which doesn't provide
+ its own <tt>/var/lib/dpkg/info/*.shlibs</tt> file yet.
+ </p>
+
+ <p>
+ Let's assume you are packaging a binary <tt>foo</tt>. Your
+ output in building the package might look like this.
+ <example>
+ $ ldd foo
+ libbar.so.1 => /usr/X11R6/lib/libbar.so.1.0
+ libc.so.5 => /lib/libc.so.5.2.18
+ libX11.so.6 => /usr/X11R6/lib/libX11.so.6.0
+ </example>
+ And when you ran <prgn>dpkg-shlibdeps</prgn>
+ <example>
+ $ dpkg-shlibdeps -o foo
+ dpkg-shlibdeps: warning: unable to find dependency information
+ for shared library libbar
+ (soname 1, path /usr/X11R6/lib/libbar.so.1.0, dependency field Depends)
+ shlibs:Depends=elf-x11r6lib, libc5 (>= 5.2.18)
+ </example>
+ The <prgn>foo</prgn> binary depends on the
+ <prgn>libbar</prgn> shared library, but no package seems
+ to provide a <tt>*.shlibs</tt> file in
+ <tt></tt>var/lib/dpkg/info/. Let's determine the package
+ responsible:
+ </p>
+
<p>
- Debian packages should be ported to include
- <prgn><stdarg.h></prgn> and <tt>ncurses</tt> when
- they are built.</p>
+ <example>
+ $ dpkg -S /usr/X11R6/lib/libbar.so.1.0
+ bar1: /usr/X11R6/lib/libbar.so.1.0
+ $ dpkg -s bar1 | grep Version
+ Version: 1.0-1
+ </example>
+ This tells us that the <prgn>bar1</prgn> package, version
+ 1.0-1 is the one we are using. Now we can create our own
+ <tt>debian/shlibs.local</tt> to temporarily fix the above
+ problem. Include the following line into your
+ <tt>debian/shlibs.local</tt> file.
+ <example>
+ libbar 1 bar1 (>= 1.0-1)
+ </example>
+ Now your package build should work. As soon as the
+ maintainer of <prgn>libbar1</prgn> provides a
+ <tt>shlibs</tt> file, you can remove your
+ <tt>debian/shlibs.local</tt> file.
+ </p>
</sect1>
- </sect></chapt>
-
+ </sect>
+ </chapt>
+
<chapt><heading>The Operating System</heading>
-
+
<sect>
<heading>File system hierarchy</heading>
-
+
<sect1>
<heading>Linux File system Structure</heading>
-
+
<p>
The location of all installed files and directories must
comply with the Linux File system Hierarchy Standard
(FHS). The latest version of this document can be found
alongside this manual or on
- <url id="http://www.pathname.com/fhs/">.<footnote>
- <p>The Debian distribution currently distributes a draft
- version of FHS 2.1 because several significant details
- have changed between the currently released 2.0
- version and the to-be-released 2.1 version.</p>
- </footnote>
+ <url id="http://www.pathname.com/fhs/">.
Specific questions about following the standard may be
asked on <prgn>debian-devel</prgn>, or referred to Daniel
Quinlan, the FHS coordinator, at
<email>quinlan@pathname.com</email>.</p></sect1>
-
-
+
+
<sect1>
<heading>Site-specific programs</heading>
-
+
<p>
As mandated by the FHS, packages must not place any
files in <tt>/usr/local</tt>, 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
<tt>/usr/local</tt> 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>
<tt>/usr/local</tt>, not <em>in</em>
<tt>/usr/local</tt>. Packages must not create sub-directories
in the directory <tt>/usr/local</tt> itself, except those listed in
- FHS, section 4.6. However, you may create directories
+ 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.6, even if you created them.</p>
-
+ directories listed in 4.5, even if you created them.</p>
+
<p>
Since <tt>/usr/local</tt> can be mounted read-only from a
remote server, these directories must be created and
included in the <tt>.deb</tt> packages and system
administrators who do not wish these directories in
/usr/local do not need to have them.)</p>
-
+
<p>
For example, the <prgn>emacs</prgn> package will contain
<example>
true
</example>
in the <tt>prerm</tt> script.</p>
-
+
<p>
If you do create a directory in <tt>/usr/local</tt> for
local additions to a package, you should ensure that
exclusive use of the local administrator, a package must
not rely on the presence or absence of files or
directories in '/usr/local' for normal operation.</p>
-
+
<p>
The <tt>/usr/local</tt> directory itself and all the
subdirectories created by the package should (by default) have
owned by <tt>root.staff</tt>.</p>
</sect1>
</sect>
-
+
<sect>
<heading>Users and groups</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
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
<tt>/etc/passwd</tt>, <tt>/etc/shadow</tt>,
<tt>/etc/group</tt> or <tt>/etc/gshadow</tt>.</p>
-
+
<p>
The UID and GID ranges are as follows:
<taglist>
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>
will check for the existence of the user or group, and
if necessary choose an unused id based on the ranged
specified in <tt>adduser.conf</tt>.</p></item>
-
-
+
+
<tag>1000-29999:</tag>
<item>
<p>
<tt>adduser.conf</tt> may be used to modify this
behavior.</p>
</item>
-
+
<tag>30000-59999:</tag>
<item>
<p>Reserved.</p></item>
-
-
+
+
<tag>60000-64999:</tag>
<item>
<p>
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
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>.'</p></item>
-
-
+
+
<tag>65535:</tag>
<item>
<p>
</sect>
<sect id="sysvinit">
<heading>System run levels</heading>
-
+
<sect1 id="/etc/init.d">
<heading>Introduction</heading>
-
+
<p>
The <tt>/etc/init.d</tt> directory contains the scripts
executed by <prgn>init</prgn> at boot time and when init
state (or `runlevel') is changed (see <manref name="init"
- section="8">).</p>
+ section="8">).</p>
<p>
There are at least two different, yet functionally
directory <tt>/etc/rc<var>n</var>.d</tt> for the scripts
it should execute, where <var>n</var> is the runlevel that
is being changed to, or `S' for the boot-up scripts.</p>
-
+
<p>
The names of the links all have the form
<tt>S<var>mm</var><var>script</var></tt> or
<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 <tt>/etc/init.d</tt>.</p>
-
+
<p>
When <prgn>init</prgn> changes runlevel first the targets
of the links whose names starting with a <tt>K</tt> are
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>
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 decide which
order to start and stop things in--low-numbered links have
</example>
</p>
</sect1>
-
+
<sect1>
<heading>Writing the scripts</heading>
-
+
<p>
Packages that include daemons for system services should
place scripts in <tt>/etc/init.d</tt> to start or stop
<taglist>
<tag><tt>start</tt></tag>
<item><p>start the service,</p></item>
-
+
<tag><tt>stop</tt></tag>
<item><p>stop the service,</p></item>
-
+
<tag><tt>restart</tt></tag>
<item><p>stop and restart the service,</p></item>
-
+
<tag><tt>reload</tt></tag>
<item><p>cause the configuration of the service to be
reloaded without actually stopping and restarting
the service,</p></item>
-
+
<tag><tt>force-reload</tt></tag> <item><p>cause the
- configuration to be reloaded if the service supports
+ configuration to be reloaded if the service supports
this, otherwise restart the service.</p></item>
</taglist>
<tt>force-reload</tt> options should be supported by all
scripts in <tt>/etc/init.d</tt>, the <tt>reload</tt>
option is optional.</p>
-
+
<p>
The <tt>init.d</tt> scripts should ensure that they will
behave sensibly if invoked with <tt>start</tt> when the
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 <tt>init.d</tt> script
should behave as if the configuration has been reloaded
successfully.</p>
-
+
<p>
These scripts should not fail obscurely when the
configuration files remain but the package has been
should include a <tt>test</tt> statement at the top of the
script, like this:
<example>
- test -f <var>program-executed-later-in-script</var> || exit 0
+ test -f <var>program-executed-later-in-script</var> || exit 0
</example></p>
</sect1>
-
+
<sect1>
<heading>Managing the links</heading>
-
+
<p>
The program <prgn>update-rc.d</prgn> is provided to make
it easier for package maintainers to arrange for the
functional equivalent if another method is being used.
This may be used by maintainers in their packages'
<tt>postinst</tt> and <tt>postrm</tt> scripts.</p>
-
+
<p>
You must use this script to make changes to
<tt>/etc/rc<var>n</var>.d</tt> and <em>never</em> either
symbolic links in maintainer scripts. (The latter will
fail if an alternative method of maintaining runlevel
information is being used.)</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)
<tt>/etc/rc<var>n</var>.d</tt> if symbolic links are being
used, or by modifying <tt>/etc/runlevel.conf</tt> if the
<tt>file-rc</tt> method is being used.</p>
-
+
<p>
To get the default behavior for your package, put in your
<tt>postinst</tt> script
update-rc.d <var>package</var> remove >/dev/null
fi
</example></p>
-
+
<p>
This will use a default sequence number of 20. If it does
not matter when or in which order the script is run, use
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></sect1>
-
-
+ section="8">.</p></sect1>
+
+
<sect1>
<heading>Boot-time initialization</heading>
-
+
<p>
There used to be another directory, <tt>/etc/rc.boot</tt>,
which contained scripts which were run once per machine
<sect1 id="init.d notes">
<heading>Notes</heading>
-
+
<p>
<em>Do not</em> include the
<tt>/etc/rc<var>n</var>.d/*</tt> symbolic links in the
<tt>.deb</tt> file system archive! <em>This will cause
- problems!</em> You must create them with
+ problems!</em> You must create them with
<prgn>update-rc.d</prgn>, as above.</p>
-
+
<p>
<em>Do not</em> include the
<tt>/etc/rc<var>n</var>.d/*</tt> symbolic links in
<prgn>dpkg</prgn>'s conffiles list! <em>This will cause
- problems!</em> You should, however, treat the
+ problems!</em> You should, however, treat the
<tt>/etc/init.d</tt> scripts as configuration files,
either by marking them as conffiles or managing them
correctly in the maintainer scripts (see
service--while making sure her changes aren't lost during
the next package upgrade.)</p>
</sect1>
-
+
<sect1>
<heading>Example</heading>
-
+
<p>
The <prgn>bind</prgn> DNS (nameserver) package wants to
make sure that the nameserver is running in multiuser
configuration); this way the user can say
<tt>/etc/init.d/bind reload</tt> to reload the name
server.</p>
-
+
<p>
<example>
#!/bin/sh
exit 0
</example></p>
-
+
<p>
Another example on which to base your <tt>/etc/init.d</tt>
scripts is in <tt>/etc/init.d/skeleton</tt>.</p>
-
+
<p>
If this package is happy with the default setup from
<prgn>update-rc.d</prgn>, namely an ordering number of 20
fi
</example></p>
</sect1></sect>
-
+
<sect>
<heading>Cron jobs</heading>
-
+
<p>
Packages must not modify the configuration file
<tt>/etc/crontab</tt>, and they must not modify the files in
<tt>/var/spool/cron/crontabs</tt>.</p>
-
+
<p>
If a package wants to install a job that has to be executed
via cron, it should place a file with the name if the
<sect>
<heading>Console messages</heading>
-
+
<p>
This section describes different formats for messages
written to standard output by the <tt>/etc/init.d</tt>
scripts. The intent is to improve the consistency of
Debian's startup and shutdown look and feel.</p>
-
+
<p>
Please look very careful at the details. We want to get the
messages to look exactly the same way concerning spaces,
punctuation, and case of letters.</p>
-
+
<p>
Here is a list of overall rules that you should use when you
create output messages. They can be useful if you have a
non-standard message that isn't covered in the sections
below.</p>
-
+
<p>
<list>
<item>
<p>
Every message should cover one line, start with a
capital letter and end with a period `.'.</p></item>
-
-
+
+
<item>
<p>
If you want to express that the computer is working on
three dots `...'. Note that we don't insert spaces in
front of or behind the dots. If the task has been
completed we write `done.' and a line feed.</p></item>
-
-
+
+
<item>
<p>
Design your messages as if the computer is telling you
Starting network daemons: nfsd mountd.
</example></p></item>
</list></p>
-
+
<p>
The following formats should be used</p>
-
+
<p>
<list>
<item>
<p>when daemons get started.</p>
-
+
<p>
Use this format if your script starts one or more
daemons. The output should look like this (a single
<daemon-1> up to <daemon-n> denote each
daemon's name (typically the file name of the
program).</p>
-
+
<p>
For example, the output of /etc/init.d/lpd would look like:
<example>
Starting printer spooler: lpd.
</example></p>
-
+
<p>
This can be achieved by saying
<example>
comment out a line if he don't wants to start a
specific daemon, while the displayed message still
looks good.</p></item>
-
-
+
+
<item>
<p>when something needs to be configured.</p>
-
+
<p>
If you have to set up different parameters of the
system upon boot up, you should use this format:
<example>
Setting <parameter> to `<value>'.
</example></p>
-
+
<p>
You can use the following echo statement to get the quotes right:
<example>
echo "Setting DNS domainname to \`"value"'."
</example></p>
-
+
<p>
Note that the left quotation mark (`) is different
from the right (').</p></item>
-
+
<item>
<p>when a daemon is stopped.</p>
-
+
<p>
When you stop a daemon you should issue a message
similar to the startup message, except that `Starting'
is replaced with `Stopping'.</p>
-
+
<p>
So stopping the printer daemon will like like this:
<example>
Stopping printer spooler: lpd.
</example></p></item>
-
+
<item>
<p>when something is executed.</p>
-
+
<p>
There are several examples where you have to run a
program at system startup or shutdown to perform a
echo "done."
</example>
in your script.</p></item>
-
+
<item>
<p>when the configuration is reloaded.</p>
-
+
<p>
When a daemon is forced to reload its configuration
files you should use the following format:
<example>
Reloading <daemon's-name> configuration...done.
</example></p></item>
-
+
<item>
<p>when none of the above rules apply.</p>
-
+
<p>
If you have to print a message that doesn't fit into
the styles described above, you can use something
appropriate, but please have a look at the overall
rules listed above.</p></item>
</list></p></sect>
-
-
+
+
<sect>
<heading>Menus</heading>
documents, and <em>menu programs</em> (either X window
managers or text-based menu programs as
<prgn>pdmenu</prgn>).</p>
-
+
<p>
All packages that provide applications that need not be
passed any special command line arguments for normal
applications, so that users of the <tt>menu</tt> package
will automatically get menu entries in their window
managers, as well in shells like <tt>pdmenu</tt>.</p>
-
+
<p>
Please refer to the <em>Debian Menu System</em> document
that comes with the <tt>menu</tt> package for information
about how to register your applications and web
documents.</p>
</sect>
-
-
+
+
<sect>
<heading>Multimedia handlers</heading>
<sect>
<heading>Keyboard configuration</heading>
-
+
<p>
To achieve a consistent keyboard configuration (i.e., all
applications interpret a keyboard event the same way) all
programs in the Debian distribution must be configured to
comply with the following guidelines.</p>
-
+
<p>
Here is a list that contains certain keys and their interpretation:
<taglist>
<tag><tt><--</tt></tag>
<item><p>delete the character to the left of the cursor</p></item>
-
+
<tag><tt>Delete</tt></tag>
<item><p>delete the character to the right of the cursor</p></item>
-
+
<tag><tt>Control+H</tt></tag>
<item><p>emacs: the help prefix</p></item>
</taglist>
The interpretation of any keyboard events should be independent
of the terminal that's used, be it a virtual console, an X
terminal emulator, an rlogin/telnet session, etc.</p>
-
+
<p>
The following list explains how the different programs
should be set up to achieve this:</p>
-
+
<p>
<list compact="compact">
<item><p>`<tt><--</tt>' generates KB_Backspace in
X.</p></item>
-
+
<item><p>`<tt>Delete</tt>' generates KB_Delete in X.</p></item>
-
+
<item>
<p>
X translations are set up to make KB_Backspace
displays, not using the application defaults, so that
the translation resources used correspond to the
xmodmap settings.</p></item>
-
+
<item>
<p>
The Linux console is configured to make
`<tt><--</tt>' generate DEL, and `Delete' generate
<tt>ESC [ 3 ~</tt> (this is the case at the
moment).</p></item>
-
+
<item><p>
X applications are configured so that Backspace
deletes left, and Delete deletes right. Motif
applications already work like this.</p></item>
-
+
<item><p>stty erase <tt>^?</tt> .</p></item>
-
+
<item><p>
The `xterm' terminfo entry should have <tt>ESC [ 3
- ~</tt> for kdch1, just like TERM=linux and
+ ~</tt> for kdch1, just like TERM=linux and
TERM=vt220.</p></item>
-
+
<item><p>
Emacs is programmed to map KB_Backspace or the `stty
erase' character to delete-backward-char, and
KB_Delete or kdch1 to delete-forward-char, and
<tt>^H</tt> to help as always.</p></item>
-
+
<item><p>
Other applications use the `stty erase' character and
kdch1 for the two delete keys, with ASCII DEL being
`delete previous character' and kdch1 being `delete
character under cursor'.</p></item>
</list></p>
-
+
<p>
This will solve the problem except for:</p>
-
+
<p>
<list compact="compact">
<item><p>
takes precedence in Emacs, and has been set
correctly). M-x help or F1 (if available) can be used
instead.</p></item>
-
+
<item><p>
Some operating systems use <tt>^H</tt> for stty erase.
However, modern telnet versions and all rlogin
versions honour stty erase. Where the stty settings
are not propagated correctly things can be made to
work by using stty manually.</p></item>
-
+
<item><p>
Some systems (including previous Debian versions) use
xmodmap to arrange for both <tt><--</tt> and Delete
other way around. On displays configured like this
Delete will not work, but <tt><--</tt>
will.</p></item>
-
+
<item><p>
Some operating systems have different kdch1 settings
in their terminfo for xterm and others. On these
</list>
</p>
</sect>
-
-
+
+
<sect>
<heading>Environment variables</heading>
-
+
<p>
A program must not depend on environment variables to get
reasonable defaults. (That's because these environment
variables would have to be set in a system-wide
configuration file like /etc/profile, which is not supported
by all shells.)</p>
-
+
<p>
If a program usually depends on environment variables for its
configuration, the program should be changed to fall back to
available), the program must be replaced by a small
`wrapper' shell script which sets the environment variables
if they are not already defined, and calls the original program.</p>
-
+
<p>
Here is an example of a wrapper script for this purpose:
export BAR
exec /usr/lib/foo/foo "$@"
</example></p>
-
+
<p>
Furthermore, as <tt>/etc/profile</tt> is a configuration
file of the <prgn>base-files</prgn> package, other packages must not
The <tt>-N</tt> flag should not be used. On a.out systems
it may have been useful for some very small binaries, but
for ELF it has no good effect.</p>
-
+
<p>
Debugging symbols are useful for error diagnosis,
investigation of core dumps (which may be submitted by users
</p>
</footnote>
- <example>
- CFLAGS = -O2 -Wall
- INSTALL = install
-
- ifneq (,$(findstring debug,$(DEB_BUILD_OPTIONS)))
- CFLAGS += -g
- endif
- ifeq (,$(findstring nostrip,$(DEB_BUILD_OPTIONS)))
- INSTALL += -s
- endif
- </example></p>
-
- It is up to the package maintainer to decide what
- compilation options are best for the package. Certain
- binaries (such as computationally-intensive programs) will
- function better with certain flags (<tt>-O3</tt>, for
- example); feel free to use them. Please use good judgment
- here. Don't use flags for the sake of it; only use them
- if there is good reason to do so. Feel free to override
- the upstream author's ideas about which compilation
- options are best--they are often inappropriate for our
- environment.</p></sect>
-
-
- <sect>
- <heading>Libraries</heading>
-
- All libraries must have a shared version in the lib
- package and a static version in the lib-dev package. The
- shared version must be compiled with <tt>-fPIC</tt>, and
- the static version must not be. In other words, each
- <tt>*.c</tt> file will need to be compiled twice.</p>
-
- You must specify the gcc option <tt>-D_REENTRANT</tt>
- when building a library (either static or shared) to make
- the library compatible with LinuxThreads.</p>
-
- Note that all installed shared libraries should be
- stripped with
- <example>
- strip --strip-unneeded <your-lib>
- </example>
- (The option `--strip-unneeded' makes <tt>strip</tt> remove
- only the symbols which aren't needed for relocation
- processing.) Shared libraries can function perfectly well
- when stripped, since the symbols for dynamic linking are
- in a separate part of the ELF object file.</p>
-
- Note that under some circumstances it may be useful to
- install a shared library unstripped, for example when
- building a separate package to support debugging.
+ <example>
+ CFLAGS = -O2 -Wall
+ INSTALL = install
+
+ ifneq (,$(findstring debug,$(DEB_BUILD_OPTIONS)))
+ CFLAGS += -g
+ endif
+ ifeq (,$(findstring nostrip,$(DEB_BUILD_OPTIONS)))
+ INSTALL += -s
+ endif
+ </example></p>
+
+ <p>
+ It is up to the package maintainer to decide what
+ compilation options are best for the package. Certain
+ binaries (such as computationally-intensive programs) will
+ function better with certain flags (<tt>-O3</tt>, for
+ example); feel free to use them. Please use good judgment
+ here. Don't use flags for the sake of it; only use them
+ if there is good reason to do so. Feel free to override
+ the upstream author's ideas about which compilation
+ options are best--they are often inappropriate for our
+ environment.</p></sect>
+
+
+ <sect>
+ <heading>Libraries</heading>
+
+ <p>
+ All libraries must have a shared version in the lib
+ package and a static version in the lib-dev package. The
+ shared version must be compiled with <tt>-fPIC</tt>, and
+ the static version must not be. In other words, each
+ <tt>*.c</tt> file will need to be compiled twice.</p>
+
+ <p>
+ You must specify the gcc option <tt>-D_REENTRANT</tt>
+ when building a library (either static or shared) to make
+ the library compatible with LinuxThreads.</p>
+
+ <p>
+ Note that all installed shared libraries should be
+ stripped with
+ <example>
+ strip --strip-unneeded <your-lib>
+ </example>
+ (The option `--strip-unneeded' makes <tt>strip</tt> remove
+ only the symbols which aren't needed for relocation
+ processing.) Shared libraries can function perfectly well
+ when stripped, since the symbols for dynamic linking are
+ in a separate part of the ELF object file.</p>
+
+ <p>
+ Note that under some circumstances it may be useful to
+ install a shared library unstripped, for example when
+ building a separate package to support debugging.
</p>
<p>
idea.
</p>
</sect>
-
-
- <sect>
- <heading>Shared libraries</heading>
-
- Packages involving shared libraries should be split up
- into several binary packages.</p>
-
- For a straightforward library which has a development
- environment and a runtime kit including just shared
- libraries you need to create two packages:
- <tt><var>libraryname</var><var>soname</var></tt>
- (<var>soname</var> is the shared object name of the shared
- library--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; usually the
- <var>soname</var> is the major number of the library) and
- <tt><var>libraryname</var><var>soname</var>-dev</tt>.</p>
-
- If you prefer only to support one development version at a
- time you may name the development package
- <tt><var>libraryname</var>-dev</tt>; otherwise you may
-
wish to use <prgn>dpkg</prgn>'s conflicts mechanism to
- ensure that the user only installs one development version
- at a time (after all, different development versions are
- likely to have the same header files in them, causing a
- filename clash if both are installed). Typically the
- development version should also have an exact version
- dependency on the runtime library, to make sure that
- compilation and linking happens correctly.</p>
-
- Packages which use the shared library should have a
- dependency on the name of the shared library package,
- <tt><var>libraryname</var><var>soname</var></tt>. When
- the <var>soname</var> changes you can have both versions
- of the library installed while moving from the old library
- to the new.</p>
-
+
+
+ <sect>
+ <heading>Shared libraries</heading>
+
+ <p>
+ Packages involving shared libraries should be split up
+ into several binary packages.</p>
+
+ <p>
+ For a straightforward library which has a development
+ environment and a runtime kit including just shared
+ libraries you need to create two packages:
+ <tt><var>libraryname</var><var>soname</var></tt>
+ (<var>soname</var> is the shared object name of the shared
+ library--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; usually the
+ <var>soname</var> is the major number of the library) and
+ <tt><var>libraryname</var><var>soname</var>-dev</tt>.</p>
+
+ <p>
+ If you prefer only to support one development version at a
+ time you may name the development package
+ <tt><var>libraryname</var>-dev</tt>; otherwise you may
+ wish to use <prgn>dpkg</prgn>'s conflicts mechanism to
+ ensure that the user only installs one development version
+ at a time (after all, different development versions are
+ likely to have the same header files in them, causing a
+ filename clash if both are installed). Typically the
+ development version should also have an exact version
+ dependency on the runtime library, to make sure that
+ compilation and linking happens correctly.</p>
+
+ <p>
+ Packages which use the shared library should have a
+ dependency on the name of the shared library package,
+ <tt><var>libraryname</var><var>soname</var></tt>. When
+ the <var>soname</var> changes you can have both versions
+ of the library installed while moving from the old library
+ to the new.</p>
+
<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. Instead, either create
- a third package for the runtime binaries (this package
- might typically be named
- <tt><var>libraryname</var>-runtime</tt>--note the absence
+ be able to install several versions of the shared library
+ without getting filename clashes. Instead, either create
+ a third package for the runtime binaries (this package
+ might typically be named
+ <tt><var>libraryname</var>-runtime</tt>--note the absence
of the <var>soname</var> in the package name) or if the
development package is small include them in there.</p>
clashes if you try to install different versions of the
combined shared libraries package).</p>
+ <p>
You should follow the directions in the <em>Debian Packaging
Manual</em> for putting the shared library in its package,
and you must include a <tt>shlibs</tt> control area
file with details of the dependencies for packages which
use the library.</p>
+ <p>
Shared libraries should not be installed
executable, since <prgn>ld.so</prgn> does not require this
and trying to execute a shared library results in a core
should have a <tt>#!</tt> line naming the shell to be used
to interpret them.</p>
+ <p>
In the case of Perl scripts this should be
<tt>#!/usr/bin/perl</tt>.</p>
errors are detected. Every script should use
<tt>set -e</tt> or check the exit status of <em>every</em>
command.</p>
-
+
<p>
The standard shell interpreter `<tt>/bin/sh</tt>' can be a
symbolic link to any POSIX compatible shell, if <tt>echo
<prgn>c-shell</prgn> virtual package.</p>
<p>
- Any scripts which create files in world-writeable
- directories (e.g., in <tt>/tmp</tt>) must use a
- mechanism which will fail if a file with the same name
- already exists.</p>
+ Any scripts which create files in world-writeable
+ directories (e.g., in <tt>/tmp</tt>) must use a
+ mechanism which will fail if a file with the same name
+ already exists.</p>
+
+ <p>
+ The Debian base distribution provides the
+ <prgn>tempfile</prgn> and <prgn>mktemp</prgn> utilities
+ for use by scripts for this purpose.</p></sect>
+
+
+ <sect>
+ <heading>Symbolic links</heading>
+
+ <p>
+ In general, symbolic links within a top-level directory
+ should be relative, and symbolic links pointing from one
+ top-level directory into another should be absolute. (A
+ top-level directory is a sub-directory of the root
+ directory `/'.)</p>
+
+ <p>
+ In addition, symbolic links should be specified as short
+ as possible, i.e., link targets like `foo/../bar' are
+ deprecated.</p>
+
+ <p>
+ Note that when creating a relative link using
+ <prgn>ln</prgn> it is not necessary for the target of the
+ link to exist relative to the working directory you're
+ running <prgn>ln</prgn> from; nor is it necessary to
+ change directory to the directory where the link is to be
+ made. Simply include the string that should appear as the
+ target of the link (this will be a pathname relative to
+ the directory in which the link resides) as the first
+ argument to <prgn>ln</prgn>.</p>
- <p>
- The Debian base distribution provides the
- <prgn>tempfile</prgn> and <prgn>mktemp</prgn> utilities
- for use by scripts for this purpose.</p></sect>
+ <p>
+ For example, in your <prgn>Makefile</prgn> or
+ <tt>debian/rules</tt>, do things like:
+ <example>
+ ln -fs gcc $(prefix)/bin/cc
+ ln -fs gcc debian/tmp/usr/bin/cc
+ ln -fs ../sbin/sendmail $(prefix)/bin/runq
+ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
+ </example></p>
+
+ <p>
+ A symbolic link pointing to a compressed file should
+ always have the same file extension as the referenced
+ file. (For example, if a file `<tt>foo.gz</tt>' is
+ referenced by a symbolic link, the filename of the link
+ has to end with `<tt>.gz</tt>' too, as in
+ `bar.gz.')</p></sect>
- <sect>
- <heading>Symbolic links</heading>
-
- <p>
- In general, symbolic links within a top-level directory
- should be relative, and symbolic links pointing from one
- top-level directory into another should be absolute. (A
- top-level directory is a sub-directory of the root
- directory `/'.)</p>
-
- <p>
- In addition, symbolic links should be specified as short
- as possible, i.e., link targets like `foo/../bar' are
- deprecated.</p>
-
- <p>
- Note that when creating a relative link using
- <prgn>ln</prgn> it is not necessary for the target of the
- link to exist relative to the working directory you're
- running <prgn>ln</prgn> from; nor is it necessary to
- change directory to the directory where the link is to be
- made. Simply include the string that should appear as the
- target of the link (this will be a pathname relative to
- the directory in which the link resides) as the first
- argument to <prgn>ln</prgn>.</p>
-
- <p>
- For example, in your <prgn>Makefile</prgn> or
- <tt>debian/rules</tt>, do things like:
- <example>
- ln -fs gcc $(prefix)/bin/cc
- ln -fs gcc debian/tmp/usr/bin/cc
- ln -fs ../sbin/sendmail $(prefix)/bin/runq
- ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
- </example></p>
-
- <p>
- A symbolic link pointing to a compressed file should
- always have the same file extension as the referenced
- file. (For example, if a file `<tt>foo.gz</tt>' is
- referenced by a symbolic link, the filename of the link
- has to end with `<tt>.gz</tt>' too, as in
- `bar.gz.')</p></sect>
-
-
- <sect>
- <heading>Device files</heading>
-
- <p>
- Packages must not include device files in the package file
- tree.</p>
-
- <p>
- If a package needs any special device files that are not
- included in the base system, it must call
- <prgn>makedev</prgn> in the <tt>postinst</tt> script,
- after asking the user for permission to do so.</p>
-
- <p>
- Packages must not remove any device files in the
- <tt>postrm</tt> or any other script. This is left to the
- system administrator.</p>
-
- <p>
- Debian uses the serial devices
- <tt>/dev/ttyS*</tt>. Programs using the old
- <tt>/dev/cu*</tt> devices should be changed to use
- <tt>/dev/ttyS*</tt>.</p>
+ <sect>
+ <heading>Device files</heading>
+
+ <p>
+ Packages must not include device files in the package file
+ tree.</p>
+
+ <p>
+ If a package needs any special device files that are not
+ included in the base system, it must call
+ <prgn>makedev</prgn> in the <tt>postinst</tt> script,
+ after asking the user for permission to do so.</p>
+
+ <p>
+ Packages must not remove any device files in the
+ <tt>postrm</tt> or any other script. This is left to the
+ system administrator.</p>
+
+ <p>
+ Debian uses the serial devices
+ <tt>/dev/ttyS*</tt>. Programs using the old
+ <tt>/dev/cu*</tt> devices should be changed to use
+ <tt>/dev/ttyS*</tt>.</p>
</sect>
-
+
<sect id="config files">
- <heading>Configuration files</heading>
+ <heading>Configuration files</heading>
<sect1>
<heading>Definitions</heading>
<p>
file (for more information see <manref name="logrotate"
section="8">):
<example>
- /var/log/foo/* {
- rotate 12
- weekly
- compress
- postrotate
- /etc/init.d/foo force-reload
- endscript
- }
+ /var/log/foo/* {
+ rotate 12
+ weekly
+ compress
+ postrotate
+ /etc/init.d/foo force-reload
+ endscript
+ }
</example>
Which rotates all files under `/var/log/foo', saves 12
compressed generations, and sends a HUP signal at the end of
Log files should be removed when the package is
purged (but not when it is only removed), by checking the
argument to the <tt>postrm</tt> script (see the <em>Debian
- Packaging Manual</em> for details).</p>
+ Packaging Manual</em> for details).</p>
+ </sect>
+
+
+ <sect>
+ <heading>Permissions and owners</heading>
+
+ <p>
+ The rules in this section are guidelines for general use.
+ If necessary you may deviate from the details below.
+ However, if you do so you must make sure that what is done
+ is secure and you should try to be as consistent as possible
+ with the rest of the system. You should probably also
+ discuss it on <prgn>debian-devel</prgn> first.</p>
+
+ <p>
+ Files should be owned by <tt>root.root</tt>, and made
+ writable only by the owner and universally readable (and
+ executable, if appropriate).</p>
+
+ <p>
+ Directories should be mode 755 or (for group-writability)
+ mode 2775. The ownership of the directory should be
+ consistent with its mode--if a directory is mode 2775, it
+ should be owned by the group that needs write access to
+ it.</p>
+
+ <p>
+ Setuid and setgid executables should be mode 4755 or 2755
+ respectively, and owned by the appropriate user or group.
+ They should not be made unreadable (modes like 4711 or
+ 2711 or even 4111); doing so achieves no extra security,
+ because anyone can find the binary in the freely available
+ Debian package--it is merely inconvenient. For the same
+ reason you should not restrict read or execute permissions
+ on non-set-id executables.</p>
+
+ <p>
+ Some setuid programs need to be restricted to particular
+ sets of users, using file permissions. In this case they
+ should be owned by the uid to which they are set-id, and
+ by the group which should be allowed to execute them.
+ They should have mode 4754; there is no point in making
+ them unreadable to those users who must not be allowed to
+ execute them.</p>
+
+ <p>
+ You must not arrange that the system administrator can only
+ reconfigure the package to correspond to their local
+ security policy by changing the permissions on a binary.
+ Ordinary files installed by <prgn>dpkg</prgn> (as opposed
+ to conffiles and other similar objects) have their
+ permissions reset to the distributed permissions when the
+ package is reinstalled. Instead you should consider (for
+ example) creating a group for people allowed to use the
+ program(s) and making any setuid executables executable
+ only by that group.</p>
+
+ <p>
+ If you need to create a new user or group for your package
+ there are two possibilities. Firstly, you may need to
+ make some files in the binary package be owned by this
+ user or group, or you may need to compile the user or
+ group id (rather than just the name) into the binary
+ (though this latter should be avoided if possible, as in
+ this case you need a statically allocated id).</p>
+
+ <p>
+ If you need a statically allocated id, you must ask for a
+ user or group id from the base system
+ maintainer, and must not release the package until you
+ have been allocated one. Once you have been allocated one
+ you must make the package depend on a version of the base
+ system with the id present in <tt>/etc/passwd</tt> or
+ <tt>/etc/group</tt>, or alternatively arrange for your
+ package to create the user or group itself with the
+ correct id (using <tt>adduser</tt>) in its pre- or
+ post-installation script (the latter is to be preferred if
+ it is possible).</p>
+
+ <p>
+ On the other hand, the program might be able to determine the
+ uid or gid from the group name at runtime, so that a
+ dynamic id can be used. In this case you should choose an
+ appropriate user or group name, discussing this on
+ <prgn>debian-devel</prgn> and checking with the base
+ system maintainer that it is unique and that they do not
+ wish you to use a statically allocated id instead. When
+ this has been checked you must arrange for your package to
+ create the user or group if necessary using
+ <prgn>adduser</prgn> in the pre- or post-installation
+ script (again, the latter is to be preferred if it is
+ possible).</p>
+
+ <p>
+ Note that changing the numeric value of an id associated with a name
+ is very difficult, and involves searching the file system for all
+ appropriate files. You need to think carefully whether a static or
+ dynamic id is required, since changing your mind later will cause
+ problems.</p>
</sect>
-
-
- <sect>
- <heading>Permissions and owners</heading>
-
- <p>
- The rules in this section are guidelines for general use.
- If necessary you may deviate from the details below.
- However, if you do so you must make sure that what is done
- is secure and you should try to be as consistent as possible
- with the rest of the system. You should probably also
- discuss it on <prgn>debian-devel</prgn> first.</p>
-
- <p>
- Files should be owned by <tt>root.root</tt>, and made
- writable only by the owner and universally readable (and
- executable, if appropriate).</p>
-
- <p>
- Directories should be mode 755 or (for group-writability)
- mode 2775. The ownership of the directory should be
- consistent with its mode--if a directory is mode 2775, it
- should be owned by the group that needs write access to
- it.</p>
-
- <p>
- Setuid and setgid executables should be mode 4755 or 2755
- respectively, and owned by the appropriate user or group.
- They should not be made unreadable (modes like 4711 or
- 2711 or even 4111); doing so achieves no extra security,
- because anyone can find the binary in the freely available
- Debian package--it is merely inconvenient. For the same
- reason you should not restrict read or execute permissions
- on non-set-id executables.</p>
-
- <p>
- Some setuid programs need to be restricted to particular
- sets of users, using file permissions. In this case they
- should be owned by the uid to which they are set-id, and
- by the group which should be allowed to execute them.
- They should have mode 4754; there is no point in making
- them unreadable to those users who must not be allowed to
- execute them.</p>
-
- <p>
- You must not arrange that the system administrator can only
- reconfigure the package to correspond to their local
- security policy by changing the permissions on a binary.
- Ordinary files installed by <prgn>dpkg</prgn> (as opposed
- to conffiles and other similar objects) have their
- permissions reset to the distributed permissions when the
- package is reinstalled. Instead you should consider (for
- example) creating a group for people allowed to use the
- program(s) and making any setuid executables executable
- only by that group.</p>
-
- <p>
- If you need to create a new user or group for your package
- there are two possibilities. Firstly, you may need to
- make some files in the binary package be owned by this
- user or group, or you may need to compile the user or
- group id (rather than just the name) into the binary
- (though this latter should be avoided if possible, as in
- this case you need a statically allocated id).</p>
-
- <p>
- If you need a statically allocated id, you must ask for a
- user or group id from the base system
- maintainer, and must not release the package until you
- have been allocated one. Once you have been allocated one
- you must make the package depend on a version of the base
- system with the id present in <tt>/etc/passwd</tt> or
- <tt>/etc/group</tt>, or alternatively arrange for your
- package to create the user or group itself with the
- correct id (using <tt>adduser</tt>) in its pre- or
- post-installation script (the latter is to be preferred if
- it is possible).</p>
-
- <p>
- On the other hand, the program might be able to determine the
- uid or gid from the group name at runtime, so that a
- dynamic id can be used. In this case you should choose an
- appropriate user or group name, discussing this on
- <prgn>debian-devel</prgn> and checking with the base
- system maintainer that it is unique and that they do not
- wish you to use a statically allocated id instead. When
- this has been checked you must arrange for your package to
- create the user or group if necessary using
- <prgn>adduser</prgn> in the pre- or post-installation
- script (again, the latter is to be preferred if it is
- possible).</p>
-
- <p>
- Note that changing the numeric value of an id associated with a name
- is very difficult, and involves searching the file system for all
- appropriate files. You need to think carefully whether a static or
- dynamic id is required, since changing your mind later will cause
- problems.</p>
- </sect>
</chapt>
<chapt>
<heading>Customized programs</heading>
-
+
<sect id="arch-spec">
<heading>Architecture specification strings</heading>
-
+
<p>
If a program needs to specify an <em>architecture specification
- string</em> in some place, the following format should be used:
+ string</em> in some place, the following format should be used:
<example>
<arch>-<os>
</example>
distributions. Also note, that we don't use
`<arch>-unknown-linux', since the `unknown' does not
look very good.</p></sect>
-
-
+
+
<sect>
<heading>Daemons</heading>
-
+
<p>
The configuration files <tt>/etc/services</tt>,
<tt>/etc/protocols</tt>, and <tt>/etc/rpc</tt> are managed
by the <prgn>netbase</prgn> package and may not be modified
by other packages.</p>
-
+
<p>
If a package requires a new entry in one of these files, the
maintainer should get in contact with the
<prgn>netbase</prgn> maintainer, who will add the entries
and release a new version of the <prgn>netbase</prgn>
package.</p>
-
+
<p>
The configuration file <tt>/etc/inetd.conf</tt> must not be
modified by the package's scripts except via the
<prgn>update-inetd</prgn> script or the
<prgn>DebianNet.pm</prgn> Perl module.</p>
-
+
<p>
If a package wants to install an example entry into
<tt>/etc/inetd.conf</tt>, the entry must be preceded with
treated as `commented out by user' by the
<prgn>update-inetd</prgn> script and are not changed or
activated during a package updates.</p></sect>
-
-
+
+
<sect>
<heading>Using pseudo-ttys and modifying wtmp, utmp and lastlog</heading>
-
+
<p>
Some programs need to create pseudo-ttys. This should be done
using Unix98 ptys if the C library supports it. The resulting
<sect>
<heading>Editors and pagers</heading>
-
+
<p>
Some programs have the ability to launch an editor or pager
program to edit or display a text document. Since there are
distribution, the system administrator and each user should
have the possibility to choose his/her preferred editor and
pager.</p>
-
+
<p>
In addition, every program should choose a good default
editor/pager if none is selected by the user or system
administrator.</p>
-
+
<p>
Thus, every program that launches an editor or pager must
use the EDITOR or PAGER environment variables to determine
the editor/pager the user wants to get started. If these
variables are not set, the programs <tt>/usr/bin/editor</tt>
and <tt>/usr/bin/pager</tt> should be used, respectively.</p>
-
+
<p>
These two files are managed through `alternatives.' That is,
every package providing an editor or pager must call the
<prgn>update-alternatives</prgn> script to register these
programs.</p>
-
+
<p>
If it is very hard to adapt a program to make us of the
EDITOR and PAGER variables, that program may be configured
launch the appropriate program or fall back to
<tt>/usr/bin/editor</tt> and <tt>/usr/bin/pager</tt>,
automatically.</p>
-
+
<p>
A program may also use the VISUAL environment variable to
determine the user's choice of editor. If it exists, it
a pager program, it is not required for a package to depend on
`editor' and `pager', nor is it required for a package to
provide such virtual packages.</p></sect>
-
-
+
+
<sect id="web-appl">
<heading>Web servers and applications</heading>
-
+
<p>
This section describes the locations and URLs that should
be used by all web servers and web application in the Debian
system.</p>
-
+
<p>
<enumlist>
<item>
<example>
http://localhost/cgi-bin/<cgi-bin-name>
</example></p></item>
-
-
+
+
<item><p>Access to html documents</p>
-
+
<p>
Html documents for a package are stored in
<tt>/usr/share/doc/<var>package</var></tt> but should
be accessed via symlinks as
<tt>/usr/doc/<var>package</var></tt><footnote> for
- backward compatibility, see <ref id="usrdoc"></footnote>
+ backward compatibility, see <ref id="usrdoc"></footnote>
and can be referred to as
<example>
http://localhost/doc/<package>/<filename>
</example></p></item>
-
-
+
+
<item><p>Web Document Root</p>
-
+
<p>
Web Applications should try to avoid storing files in
the Web Document Root. Instead they should use the
</item>
</enumlist></p></sect>
-
-
+
+
<sect>
<heading>Mail transport agents</heading>
-
+
<p>
Debian packages which process electronic mail, whether
mail-user-agents (MUAs) or mail-transport-agents (MTAs),
configuration decisions below. Failure to do this may
result in lost mail, broken <tt>From:</tt> lines, and other
serious brain damage!</p>
-
+
<p>
The mail spool is <tt>/var/spool/mail</tt> and the interface
to send a mail message is <tt>/usr/sbin/sendmail</tt> (as
per the FHS). The mail spool is part of the base system
and not part of the MTA package.</p>
-
+
<p>
All Debian MUAs, MTAs, MDAs and other mailbox accessing
programs (like IMAP daemons) must lock the mailbox in an
<tt>liblockfile</tt> version >>1.01</p>
</footnote> packages is the recommended way to realize this.
</p>
-
+
<p>
Mailboxes are generally 660 <tt><var>user</var>.mail</tt>
unless the user has chosen otherwise. A MUA may remove a
mailbox (unless it has nonstandard permissions) in which
case the MTA or another MUA must recreate it if needed.
Mailboxes must be writable by group mail.</p>
-
+
<p>
The mail spool is 2775 <tt>root.mail</tt>, and MUAs should
be setgid mail to do the locking mentioned above (and
must obviously avoid accessing other users' mailboxes
using this privilege).</p>
-
+
<p>
<tt>/etc/aliases</tt> is the source file for the system mail
aliases (e.g., postmaster, usenet, etc.)--it is the one
even if it does nothing, but older MTA packages do not do
this so programs should not fail if <prgn>newaliases</prgn>
cannot be found.</p>
-
+
<p>
The convention of writing <tt>forward to
- <var>address</var></tt> in the mailbox itself is not
+ <var>address</var></tt> in the mailbox itself is not
supported. Use a <tt>.forward</tt> file instead.</p>
-
+
<p>
The <prgn>rmail</prgn> program used by UUCP
- for incoming mail should be <tt>/usr/sbin/rmail</tt>, as per the
- FHS. Likewise, <prgn>rsmtp</prgn>, for receiving
+ for incoming mail should be <tt>/usr/sbin/rmail</tt>.
+ Likewise, <prgn>rsmtp</prgn>, for receiving
batch-SMTP-over-UUCP, should be <tt>/usr/sbin/rsmtp</tt> if it
is supported.</p>
-
+
<p>
If you need to know what name to use (for example) on
outgoing news and mail messages which are generated locally,
contain the portion after the username and <tt>@</tt> (at)
sign for email addresses of users on the machine (followed
by a newline).</p>
-
+
<p>
A package should check for the existence of this file. If
it exists it should use it without comment. (An MTA's
</example>
where <var>syshostname</var> is the output of <tt>hostname
--fqdn</tt>.</p></sect>
-
-
+
+
<sect>
<heading>News system configuration</heading>
-
+
<p>
All the configuration files related to the NNTP (news)
servers and clients should be located under
<tt>/etc/news</tt>.</p>
-
+
<p>
There are some configuration issues that apply to a number
of news clients and server packages on the machine. These
<item><p>A string which should appear as the
organization header for all messages posted
by NNTP clients on the machine</p></item>
-
+
<tag>/etc/news/server</tag>
<item><p>Contains the FQDN of the upstream NNTP
server, or localhost if the local machine is
Other global files may be added as required for cross-package news
configuration.</p></sect>
-
-
+
+
<sect>
<heading>Programs for the X Window System</heading>
-
+
<p>
<em>Programs that may be configured with support for the X Window
System</em> must be configured to do so and must declare any
</p>
</footnote>
</p>
-
-
+
+
<p>
- <em>Packages which provide an X server</em> that, directly or
- indirectly, communicates with real input and display hardware
- should declare in their control data that they provide the
+ <em>Packages which provide an X server</em> that, directly or
+ indirectly, communicates with real input and display hardware
+ should declare in their control data that they provide the
virtual package <tt>xserver</tt>.
<footnote>
<p>
change this drastically.
</p>
</footnote>
- </p>
+ </p>
<p>
<em>Packages that provide a terminal emulator</em> for the X
(without killing the X server) in its default
configuration, add 10 points; otherwise add
none.</item>
- </list>
- </p>
+ </list>
+ </p>
<p>
- <em>Packages that provide fonts for the X Window System</em>
- must do a number of things to ensure that they are both
- available without modification of the X or font server
- configuration, and that they do not corrupt files used by
- other font packages to register information about themselves.
- <enumlist>
- <item>
+ <em>Packages that provide fonts for the X Window System</em>
+ must do a number of things to ensure that they are both
+ available without modification of the X or font server
+ configuration, and that they do not corrupt files used by
+ other font packages to register information about themselves.
+ <enumlist>
+ <item>
Fonts of any type supported by the X Window System
should be be in a separate binary package from any
executables, libraries, or documentation (except that
library should declare a dependency on the package(s)
containing the font(s) it requires.
</item>
- <item>
+ <item>
BDF fonts should be converted to PCF fonts with the
<tt>bdftopcf</tt> utility (available in the
<tt>xbase-clients</tt> package, <tt>gzip</tt>ped, and
Font packages that provide one or more
<tt>fonts.alias</tt> files as described above must
declare a versioned dependency on <tt>xbase-clients
- (>= 3.3.3.1-5)</tt> and, in the package
+ (>= 3.3.3.1-5)</tt> and, in the package
post-installation and post-removal scripts, invoke
<tt>update-fonts-alias</tt> on each directory into
which they installed fonts.
administrator, as to how to manage
/etc/X11/Xresources.</p>
</footnote>
- </p>
+ </p>
-
+
<p>
<em>Packages using the X Window System should abide by the FHS
standard whenever possible</em>; they should install binaries,
<tt>/usr/X11R6/include/X11/</tt>, and
<tt>/usr/X11R6/lib/X11/</tt>, if the resources being
referred to have not been moved to FHS-compliant locations.
- </p>
+ </p>
<p>
<em>Programs that require the non-DFSG-compliant OSF/Motif
his or her possession.
</p>
</sect>
-
-
+
+
<sect>
<heading>Emacs lisp programs</heading>
-
+
<p>
Please refer to the `Debian Emacs Policy' (documented in
<tt>debian-emacs-policy.gz</tt> of the
<prgn>emacsen-common</prgn> package) for details of how to
package emacs lisp programs.</p></sect>
-
-
+
+
<sect>
<heading>Games</heading>
-
+
<p>
The permissions on /var/games are 755
<tt>root.root</tt>.</p>
-
+
<p>
Each game decides on its own security policy.</p>
-
+
<p>
Games which require protected, privileged access to
high-score files, savegames, etc., may be made
important game data, and if they can get at the other
players' accounts at all it will take considerably more
effort.)</p>
-
+
<p>
Some packages, for example some fortune cookie programs, are
configured by the upstream authors to install with their
making the files unreadable also means that you don't have
to make so many programs set-id, which reduces the risk of a
security hole.</p>
-
+
<p>
As described in the FHS, binaries of games should be
installed in the directory <tt>/usr/games</tt>. This also
<tt>/usr/share/man/man6</tt>.</p>
</sect>
</chapt>
-
+
<chapt><heading>Documentation</heading>
-
+
<sect>
<heading>Manual pages</heading>
-
+
<p>
You should install manual pages in <prgn>nroff</prgn> source
form, in appropriate places under <tt>/usr/share/man</tt>. You
should only use sections 1 to 9 (see the FHS for more
details). You must not install a preformatted `cat
page'.</p>
-
+
<p>
- Each program, utiltiy, and function should have an
+ Each program, utility, and function should have an
associated manpage included in the same package. It is
suggested that all configuration files also have a manual
page included as well.
</p>
-
+
<p>
If no manual page is available for a particular program,
utility, function or configuration file and this is reported as a bug on
reported as a bug, so you may only do this if it really has
(you can report it yourself, if you like). Do not close the
bug report until a proper manpage is available.</p>
-
+
<p>
You may forward a complaint about a missing manpage to the
upstream authors, and mark the bug as forwarded in the
we do--if they tell you that they don't consider it a bug
you should leave the bug in our bug tracking system open
anyway.</p>
-
+
<p>
Manual pages should be installed compressed using <tt>gzip
- -9</tt>.</p>
-
+ -9</tt>.</p>
+
<p>
If one manpage needs to be accessible via several names it
is better to use a symbolic link than the <tt>.so</tt>
in a <tt>.so</tt> in a manpage should be relative to the
base of the manpage tree (usually
<tt>/usr/share/man</tt>).</p></sect>
-
-
+
+
<sect>
<heading>Info documents</heading>
-
+
<p>
Info documents should be installed in <tt>/usr/share/info</tt>.
They should be compressed with <tt>gzip -9</tt>.</p>
-
+
<p>
Your package should call <prgn>install-info</prgn> to update the Info
<tt>dir</tt>
install-info --quiet --section Development Development \
/usr/share/info/foobar.info
</example></p>
-
+
<p>
It is a good idea to specify a section for the location of
your program; this is done with the <tt>--section</tt>
flag takes two arguments; the first is a regular expression
to match (case-insensitively) against an existing section,
the second is used when creating a new one.</p>
-
+
<p>
You should remove the entries in the pre-removal script:
<example>
install-info --quiet --remove /usr/share/info/foobar.info
</example></p>
-
+
<p>
If <prgn>install-info</prgn> cannot find a description entry
in the Info file you must supply one. See <manref
- name="install-info" section="8"> for details.</p>
+ name="install-info" section="8"> for details.</p>
</sect>
<sect>
the instructions for building and installing the package, of
course!</p>
</sect>
-
+
<sect id="usrdoc">
- <heading>Accessing the documentation</heading>
-
- <p>
- Former Debian releases placed all additional documentation
- in <tt>/usr/doc/<var>package</var></tt>. To realize a
- smooth migration to
- <tt>/usr/share/doc/<var>package</var></tt>, each package
- must maintain a symlink <tt>/usr/doc/<var>package</var></tt>
- that points to the new location of its documentation in
- <tt>/usr/share/doc/<var>package</var></tt><footnote>These
- symlinks will be removed in the future, but they have to be
- there for compatibility reasons until all packages have
- moved and the policy is changed accordingly.</footnote>.
- The symlink must be created when the package is installed;
- it cannot be contained in the package itself due to problems
- with <prgn>dpkg</prgn>. One reasonable way to accomplish
- this is to put the following in the package's
- <prgn>postinst</prgn>:
+ <heading>Accessing the documentation</heading>
+
+ <p>
+ Former Debian releases placed all additional documentation
+ in <tt>/usr/doc/<var>package</var></tt>. To realize a
+ smooth migration to
+ <tt>/usr/share/doc/<var>package</var></tt>, each package
+ must maintain a symlink <tt>/usr/doc/<var>package</var></tt>
+ that points to the new location of its documentation in
+ <tt>/usr/share/doc/<var>package</var></tt><footnote>These
+ symlinks will be removed in the future, but they have to be
+ there for compatibility reasons until all packages have
+ moved and the policy is changed accordingly.</footnote>.
+ The symlink must be created when the package is installed;
+ it cannot be contained in the package itself due to problems
+ with <prgn>dpkg</prgn>. One reasonable way to accomplish
+ this is to put the following in the package's
+ <prgn>postinst</prgn>:
<example>
- if [ "$1" = "configure" ]; then
- if [ -d /usr/doc -a ! -e /usr/doc/#PACKAGE# \
+ if [ "$1" = "configure" ]; then
+ if [ -d /usr/doc -a ! -e /usr/doc/#PACKAGE# \
-a -d /usr/share/doc/#PACKAGE# ]; then
- ln -sf ../share/doc/#PACKAGE# /usr/doc/#PACKAGE#
- fi
- fi
+ ln -sf ../share/doc/#PACKAGE# /usr/doc/#PACKAGE#
+ fi
+ fi
</example>
And the following in the package's <prgn>prerm</prgn>:
<example>
- if [ \( "$1" = "upgrade" -o "$1" = "remove" \) \
- -a -L /usr/doc/#PACKAGE# ]; then
- rm -f /usr/doc/#PACKAGE#
- fi
+ if [ \( "$1" = "upgrade" -o "$1" = "remove" \) \
+ -a -L /usr/doc/#PACKAGE# ]; then
+ rm -f /usr/doc/#PACKAGE#
+ fi
</example>
</p>
</sect>
-
+
<sect>
<heading>Preferred documentation formats</heading>
projects / debian / debian-policy.git / commitdiff