+++ /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>
projects / debian / debian-policy.git / blobdiff