+
+ <appendix id="pkg-scope">
+ <heading>Introduction and scope of these appendices</heading>
+
+ <p>
+ These appendices are taken essentially verbatim from the
+ now-deprecated Packaging Manual, version 3.2.1.0. They are
+ the chapters which are likely to be of use to package
+ maintainers and which have not already been included in the
+ policy document itself. Most of these sections are very likely
+ not relevant to policy; they should be treated as
+ documentation for the packaging system. Please note that these
+ appendices are included for convenience, and for historical
+ reasons: they used to be part of policy package, and they have
+ not yet been incorporated into dpkg documentation. However,
+ they still have value, and hence they are presented here.
+ </p>
+ <p>
+ They have not yet been checked to ensure that they are
+ compatible with the contents of policy, and if there are any
+ contradictions, the version in the main policy document takes
+ precedence. The remaining chapters of the old Packaging
+ Manual have also not been read in detail to ensure that there
+ are not parts which have been left out. Both of these will be
+ done in due course.
+ </p>
+
+ <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>
+ </appendix>
+
+ <appendix id="pkg-binarypkg"><heading>Binary packages (from old
+ Packaging Manual)
+ </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="pkg-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="pkg-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="pkg-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/share/doc/<var>\*</var>copyright | less
+ </example>
+ </p>
+ </sect>
+
+ <sect id="pkg-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="pkg-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="pkg-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="pkg-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="pkg-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="pkg-sourcepkg"> for
+ more details.
+ </p>
+
+ <p>
+ The fields in binary package control files are:
+ <list compact="compact">
+ <item>
+ <p><qref id="pkg-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="pkg-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="pkg-f-Essential"><tt>Essential</tt></qref></p>
+ </item>
+ <item>
+ <p><qref id="pkg-f-Maintainer"><tt>Maintainer</tt></qref></p>
+ </item>
+ <item>
+ <p><qref id="pkg-f-classification"><tt>Section</tt>,
+ <tt>Priority</tt></qref></p>
+ </item>
+ <item>
+ <p><qref id="pkg-f-Source"><tt>Source</tt></qref></p>
+ </item>
+ <item>
+ <p><qref id="descriptions"><tt>Description</tt></qref></p>
+ </item>
+ <item>
+ <p>
+ <qref id="pkg-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="pkg-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>
+ </appendix>
+
+ <appendix id="pkg-sourcepkg">
+ <heading>Source packages (from old Packaging Manual) </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="pkg-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="pkg-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 <tt>clean</tt>, <tt>build</tt> and
+ <tt>binary</tt>, <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="pkg-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="pkg-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 <tt>binary</tt> 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="pkg-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="pkg-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="pkg-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="pkg-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>
+ A package may also provide both of the targets
+ <tt>build-arch</tt> and <tt>build-indep</tt>. The
+ <tt>build-arch</tt> target, if provided, should
+ perform all non-interactive configuration and
+ compilation required for producing all
+ architecture-dependant binary packages (those packages
+ for which the body of the <tt>Architecture</tt> field
+ in <tt>debian/control</tt> is not <tt>all</tt>).
+ Similarly, the <tt>build-indep</tt> target, if
+ provided, should perform all non-interactive
+ configuration and compilation required for producing
+ all architecture-independent binary packages (those
+ packages for which the body of the
+ <tt>Architecture</tt> field in <tt>debian/control</tt>
+ is <tt>all</tt>). The <tt>build</tt> target should
+ depend on those of the targets <tt>build-arch</tt> and
+ <tt>build-indep</tt> that are provided in the rules
+ file.
+ </p>
+
+ <p>
+ If one or both of the targets <tt>build-arch</tt> and
+ <tt>build-indep</tt> are not provided, then invoking
+ <tt>debian/rules</tt> with one of the not-provided
+ targets as arguments should produce a exit status code
+ of 2. Usually this is provided automatically by make
+ if the target is missing.
+ </p>
+
+ <p>
+ For some packages, notably ones where the same
+ source tree is compiled in different ways to produce
+ two binary packages, the <tt>build</tt> 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
+ <tt>build</tt> target that does nothing. The
+ <tt>binary</tt> target will have to build the
+ package in each of the possible ways and make the
+ binary package out of each.
+ </p>
+
+ <p>
+ The targets <tt>build</tt>, <tt>build-arch</tt>
+ and <tt>build-indep</tt> target must not do
+ anything that might require root privilege.
+ </p>
+
+ <p>
+ The <tt>build</tt> target may need to run
+ <tt>clean</tt> 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 <tt>build</tt> needs to run
+ <tt>clean</tt> 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 <tt>binary</tt> 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:
+ <tt>binary-arch</tt> builds the packages' output
+ files which are specific to a particular
+ architecture, and <tt>binary-indep</tt> builds
+ those which are not.
+ </p>
+
+ <p>
+ <tt>binary</tt> 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 <tt>build</tt> 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="pkg-binarypkg"> describes how to construct
+ binary packages.
+ </p>
+
+ <p>
+ The <tt>binary</tt> targets must be invoked as
+ root.
+ </p>
+ </item>
+
+ <tag><tt>clean</tt></tag>
+ <item>
+
+ <p>
+ This should undo any effects that the
+ <tt>build</tt> and <tt>binary</tt> targets
+ may have had, except that it should leave alone any
+ output files created in the parent directory by a
+ run of <tt>binary</tt>. This target is required
+ to be non-interactive.
+ </p>
+
+ <p>
+ If a <tt>build</tt> file is touched at the end
+ of the <tt>build</tt> target, as suggested
+ above, it must be removed as the first thing that
+ <tt>clean</tt> does, so that running
+ <tt>build</tt> again after an interrupted
+ <tt>clean</tt> doesn't think that everything is
+ already done.
+ </p>
+
+ <p>
+ The <tt>clean</tt> target must be invoked as
+ root if <tt>binary</tt> has been invoked since
+ the last <tt>clean</tt>, or if
+ <tt>build</tt> has been invoked as root (since
+ <tt>build</tt> 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 <tt>build</tt>, <tt>binary</tt> and
+ <tt>clean</tt> 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="pkg-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="pkg-controlfields">.
+ </p>
+
+ <p>
+ The general (binary-package-independent) fields are:
+ <list compact="compact">
+ <item>
+ <p><qref id="pkg-f-Source"><tt>Source</tt></qref> (mandatory)</p>
+ </item>
+ <item>
+ <p><qref id="pkg-f-Maintainer"><tt>Maintainer</tt></qref></p>
+ </item>
+ <item>
+ <p>
+ <qref id="pkg-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="pkg-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="pkg-f-Package"><tt>Package</tt></qref> (mandatory)</p>
+ </item>
+ <item>
+ <p>
+ <qref id="pkg-f-Architecture"><tt>Architecture</tt></qref>
+ (mandatory)</p>
+ </item>
+ <item>
+ <p><qref id="descriptions"><tt>Description</tt></qref></p>
+ </item>
+ <item>
+ <p>
+ <qref id="pkg-f-classification"><tt>Section</tt> and
+ <tt>Priority</tt></qref> (classification)</p>
+ </item>
+ <item>
+ <p><qref id="pkg-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="pkg-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="pkg-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="pkg-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="pkg-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="pkg-f-Source"><tt>Source</tt></qref></p>
+ </item>
+ <item>
+ <p><qref id="versions"><tt>Version</tt></qref> (mandatory)</p>
+ </item>
+ <item>
+ <p>
+ <qref id="pkg-f-Distribution"><tt>Distribution</tt></qref>
+ (mandatory)
+ </p>
+ </item>
+ <item>
+ <p><qref id="pkg-f-Urgency"><tt>Urgency</tt></qref> (mandatory)</p>
+ </item>
+ <item>
+ <p>
+ <qref id="pkg-f-Maintainer"><tt>Maintainer</tt></qref>
+ (mandatory)
+ </p>
+ </item>
+ <item>
+ <p><qref id="pkg-f-Date"><tt>Date</tt></qref></p>
+ </item>
+ <item>
+ <p>
+ <qref id="pkg-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="pkg-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="pkg-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 <tt>clean</tt> 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
+ <tt>clean</tt> target. It may also be wise to
+ ensure a fresh start by emptying or removing it at the
+ start of the <tt>binary</tt> 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 <tt>clean</tt>.
+ </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 <tt>binary</tt>
+ 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="pkg-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
+ <tt>binary</tt> must of course be removed by the
+ <tt>clean</tt> target.</p></sect1>
+ </sect>
+
+
+ <sect id="pkg-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="pkg-controlfields">.
+ <list compact="compact">
+ <item>
+ <p><qref id="pkg-f-Source"><tt>Source</tt></qref></p>
+ </item>
+ <item>
+ <p><qref id="versions"><tt>Version</tt></qref></p>
+ </item>
+ <item>
+ <p><qref id="pkg-f-Maintainer"><tt>Maintainer</tt></qref></p>
+ </item>
+ <item>
+ <p><qref id="pkg-f-Binary"><tt>Binary</tt></qref></p>
+ </item>
+ <item>
+ <p><qref id="pkg-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="pkg-f-Standards-Version"><tt>Standards-Version</tt></qref></p>
+ </item>
+ <item>
+ <p><qref id="pkg-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>
+ </appendix>
+
+ <appendix id="pkg-controlfields"><heading>Control files and their
+ fields (from old Packaging Manual)
+ </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="pkg-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="pkg-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="pkg-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="pkg-debianrules"> for information how to get the
+ architecture for the build process.
+ </p>
+ </sect1>
+
+ <sect1 id="pkg-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="pkg-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="pkg-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="pkg-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="pkg-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="pkg-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="pkg-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="pkg-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="pkg-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="pkg-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="pkg-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="pkg-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="pkg-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="pkg-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="pkg-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="pkg-dpkgchangelog">).
+ </p>
+
+ <p>
+ Urgency keywords are not case-sensitive.</p>
+ </sect1>
+
+ <sect1 id="pkg-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="pkg-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="pkg-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="pkg-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="pkg-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="pkg-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="pkg-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="pkg-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>
+ </appendix>
+
+ <appendix id="pkg-conffiles"><heading>Configuration file handling
+ (from old Packaging Manual)
+ </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>
+ </appendix>
+
+ <appendix id="pkg-alternatives"><heading>Alternative versions of
+ an interface - <prgn>update-alternatives</prgn> (from old
+ Packaging Manual)
+ </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>
+ </appendix>
+
+ <appendix id="pkg-diversions"><heading>Diversions - overriding a
+ package's version of a file (from old Packaging Manual)
+ </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="pkg-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>
+ </appendix>
+
projects / debian / debian-policy.git / blobdiff