From: Manoj Srivastava <srivasta@debian.org> Date: Thu, 16 Jun 2005 05:04:58 +0000 (+0000) Subject: New version X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=88a29ddc386bab01a2d6d88ee043616873ce4a08;p=debian%2Fdebian-policy.git New version Author: srivasta Date: 1998/11/27 07:45:27 New version git-archimport-id: srivasta@debian.org--etch/debian-policy--devel--3.0--patch-20 --- diff --git a/packaging.sgml b/packaging.sgml index 4a3f0a5..a040af4 100644 --- a/packaging.sgml +++ b/packaging.sgml @@ -1,4 +1,8 @@ -<!doctype debiandoc system> +<!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. @@ -8,3567 +12,5052 @@ Maintainer since 1998, Christian Schwarz <schwarz@debian.org> --> -<book> - -<title>Debian Packaging Manual -<author>Ian Jackson <email/ijackson@gnu.ai.mit.edu/ -<author>Revised: David A. Morris <email/bweaver@debian.org/ -<author>Maintainer: Christian Schwarz <email/schwarz@debian.org/ -<version>version 2.4.1.0, 14 April 1998 - -<abstract> -This manual describes the technical aspects of creating Debian binary -and source packages. It also documents the interface between -<prgn/dselect/ and its access method scripts. It does not deal with -the Debian Project policy requirements, and it assumes familiarity -with <prgn/dpkg/'s functions from the system administrator's -perspective. - -<copyright>Copyright ©1996 Ian Jackson. -<p> - -This manual is free software; you may redistribute it and/or modify it -under the terms of the GNU General Public License as published by the -Free Software Foundation; either version 2, or (at your option) any -later version. -<p> - -This is distributed in the hope that it will be useful, but -<em>without any warranty</em>; without even the implied warranty of -merchantability or fitness for a particular purpose. See the GNU -General Public License for more details. -<p> - -A copy of the GNU General Public License is available as -<tt>/usr/doc/copyright/GPL</tt> in the Debian GNU/Linux -distribution or on the World Wide Web at -<tt>http://www.gnu.org/copyleft/gpl.html</tt>. You can also obtain it -by writing to the Free Software Foundation, Inc., 59 Temple Place - -Suite 330, Boston, MA 02111-1307, USA. -<p> - -<toc sect> - -<!-- Describes the technical interface between a package and dpkg. - -How to safely put shared libraries in a package. Details of dpkg's -handling of individual files. Sections on when to use which feature -(eg Replaces vs. Replaces/Conflicts vs. update-alternatives -vs. diversions) Cross-references to the policy document (see below) -where appropriate. Description of the interface between dselect and -its access methods. Hints on where to start with a new package (ie, -the hello package). What to do about file aliasing. - -file aliasing - -Manpages are required for: update-rc.d, diversions, -update-alternatives, install-info in a package. - ---> - -<chapt id="scope">Introduction and scope of this manual -<p> - -<prgn/dpkg/ is a suite of programs for creating binary package files -and installing and removing them on Unix systems.<footnote><prgn/dpkg/ -is targetted primarily at Debian GNU/Linux, but may work on or be -ported to other systems.</footnote> -<p> - -The binary packages are designed for the management of installed -executable programs (usually compiled binaries) and their associated -data, though source code examples and documentation are provided as -part of some packages. -<p> - -This manual describes the technical aspects of creating Debian binary -packages (<tt/.deb/ files). It documents the behaviour of the -package management programs <prgn/dpkg/, <prgn/dselect/ et al. and and the -way they interact with packages. -<p> - -It also documents the interaction between <prgn/dselect/'s core and the -access method scripts it uses to actually install the selected -packages, and describes how to create a new access method. -<p> - -This manual does not go into detail about the options and usage of the -package building and installation tools. It should therefore be read -in conjuction with those programs' manpages. -<p> - -The utility programs which are provided with <prgn/dpkg/ for managing -various system configuration and similar issues, such as -<prgn/update-rc.d/ and <prgn/install-info/, are not described in -detail here - please see their manpages. -<p> - -It does <em/not/ describe the policy requirements imposed on Debian -packages, such as the permissions on files and directories, -documentation requirements, upload procedure, and so on. You should -see the Debian packaging policy manual for these details. (Many of -them will probably turn out to be helpful even if you don't plan to -upload your package and make it available as part of the -distribution.) -<p> - -It is assumed that the reader is reasonably familiar with the -<prgn/dpkg/ System Administrators' manual. Unfortunately this manual -does not yet exist. -<p> - -The Debian version of the FSF's GNU hello program is provided as an -example for people wishing to create Debian packages. The Debian -<prgn/debmake/ package is recommended as a very helpful tool in -creating and maintaining Debian packages. However, while the tools and -examples are helpful, they do not replace the need to read and follow -the Policy and Programmer's Manual. - -<chapt id="binarypkg">Binary packages -<p> - -The binary package has two main sections. The first part consists of -various control information files and scripts used by <prgn/dpkg/ when -installing and removing. See <ref id="controlarea">. -<p> - -The second part is an archive containing the files and directories to -be installed. -<p> - -In the future binary packages may also contain other components, such -as checksums and digital signatures. The format for the archive is -described in full in the <tt>deb(5)</> manpage. - - -<sect id="bincreating">Creating package files - <prgn/dpkg-deb/ -<p> - -All manipulation of binary package files is done by <prgn/dpkg-deb/; -it's the only program that has knowledge of the format. -(<prgn/dpkg-deb/ may be invoked by calling <prgn/dpkg/, as <prgn/dpkg/ will -spot that the options requested are appropriate to <prgn/dpkg-deb/ and -invoke that instead with the same arguments.) -<p> - -In order to create a binary package you must make a directory tree -which contains all the files and directories you want to have in the -filesystem data part of the package. In Debian-format source packages -this directory is usually <tt>debian/tmp</tt>, relative to the top of -the package's source tree. -<p> - -They should have the locations (relative to the root of the directory -tree you're constructing) ownerships and permissions which you want -them to have on the system when they are installed. -<p> - -With current versions of <prgn/dpkg/ the uid/username and gid/groupname -mappings for the users and groups being used should be the same on the -system where the package is built and the one where it is installed. -<p> - -You need to add one special directory to the root of the miniature -filesystem tree you're creating: <prgn/DEBIAN/. It should contain the -control information files, notably the binary package control file -(see <ref id="controlfile">). -<p> - -The <prgn/DEBIAN/ directory will not appear in the filesystem archive of -the package, and so won't be installed by <prgn/dpkg/ when the package -is installed. -<p> - -When you've prepared the package, you should invoke: -<example> -dpkg --build <var/directory/ -</example> -<p> - -This will build the package in <tt/<var/directory/.deb/. -(<prgn/dpkg/ knows that <tt/--build/ is a <prgn/dpkg-deb/ option, so it -invokes <prgn/dpkg-deb/ with the same arguments to build the package.) -<p> - -See the manpage <manref name="dpkg-deb" section=8> for details of how -to examine the contents of this newly-created file. You may find the -output of following commands enlightening: -<example> -dpkg-deb --info <var/filename/.deb -dpkg-deb --contents <var/filename/.deb -dpkg --contents <var/filename/.deb -</example> -To view the copyright file for a package you could use this command: -<example> -dpkg --fsys-tarfile <var/filename/.deb | tar xof usr/doc/<var/\*/copyright | less -</example> - -<sect id="controlarea">Package control information files -<p> - -The control information portion of a binary package is a collection of -files with names known to <prgn/dpkg/. It will treat the contents of -these files specially - some of them contain information used by -<prgn/dpkg/ when installing or removing the package; others are scripts -which the package maintainer wants <prgn/dpkg/ to run. -<p> - -It is possible to put other files in the package control area, but -this is not generally a good idea (though they will largely be -ignored). -<p> - -Here is a brief list of the control info files supported by <prgn/dpkg/ -and a summary of what they're used for. -<p> - -<taglist> -<tag><tt/control/ -<item> - -This is the key description file used by <prgn/dpkg/. It specifies the -package's name and version, gives its description for the user, states -its relationships with other packages, and so forth. -See <ref id="controlfile">. -<p> - -It is usually generated automatically from information in the source -package by the <prgn/dpkg-gencontrol/ program, and with assistance -from <prgn/dpkg-shlibdeps/. See <ref id="sourcetools">. - -<tag><tt/postinst/, <tt/preinst/, <tt/postrm/, <tt/prerm/ -<item> - -These are exectuable files (usually scripts) which <prgn/dpkg/ runs -during installation, upgrade and removal of packages. They allow the -package to deal with matters which are particular to that package or -require more complicated processing than that provided by <prgn/dpkg/. -Details of when and how they are called are in -<ref id="maintainerscripts">. -<p> - -It is very important to make these scripts idempotent.<footnote>That -means that if it runs successfully or fails and then you call it again -it doesn't bomb out, but just ensures that everything is the way it -ought to be.</footnote> This is so that if an error occurs, the user -interrupts <prgn/dpkg/ or some other unforeseen circumstance happens you -don't leave the user with a badly-broken package. -<p> - -The maintainer scripts are guaranteed to run with a controlling -terminal and can interact with the user. If they need to prompt for -passwords, do full-screen interaction or something similar you should -do these things to and from <tt>/dev/tty</>, since <prgn/dpkg/ will at -some point redirect scripts' standard input and output so that it can -log the installation process. Likewise, because these scripts may be -executed with standard output redirected into a pipe for logging -purposes, Perl scripts should set unbuffered output by setting -<tt/$|=1/ so that the output is printed immediately rather than being -buffered. -<p> - -Each script should return a zero exit status for success, or a nonzero -one for failure. - -<tag><tt/conffiles/ -<item> - -This file contains a list of configuration files which are to be -handled automatically by <prgn/dpkg/ (see <ref id="conffiles">). Note -that not necessarily every configuration file should be listed here. - -<tag><tt/shlibs/ -<item> - -This file contains a list of the shared libraries supplied by the -package, with dependency details for each. This is used by -<prgn/dpkg-shlibdeps/ when it determines what dependencies are -required in a package control file. The <tt/shlibs/ file format is -described on <ref id="shlibs">. -<p> - -</taglist> - -<sect id="controlfile">The main control information file: <tt/control/ -<p> - -The most important control information file used by <prgn/dpkg/ when it -installs a package is <tt/control/. It contains all the package's -`vital statistics'. -<p> - -The binary package control files of packages built from Debian sources -are made by a special tool, <prgn/dpkg-gencontrol/, which reads -<tt>debian/control</> and <tt>debian/changelog</> to find the -information it needs. See <ref id="sourcepkg"> for more details. -<p> - -The fields in binary package control files are: -<list compact> - -<item><qref id="f-Package"><tt/Package/</> (mandatory) -<item><qref id="versions"><tt/Version/</> (mandatory) - -<item><qref id="f-Architecture"><tt/Architecture/</> -(mandatory)<footnote>This field should appear in all packages, though -<prgn/dpkg/ doesn't require it yet so that old packages can still be -installed.</footnote> - -<item><qref id="relationships"><tt/Depends/, <tt/Provides/ et al.</> -<item><qref id="f-Essential"><tt/Essential/</> -<item><qref id="f-Maintainer"><tt/Maintainer/</> -<item><qref id="f-classification"><tt/Section/, <tt/Priority/</> -<item><qref id="f-Source"><tt/Source/</> -<item><qref id="descriptions"><tt/Description/</> -<item><qref id="f-Installed-Size"><tt/Installed-Size/</> - -</list> -<p> - -A description of the syntax of control files and the purpose of these -fields is available in <ref id="controlfields">. - - -<chapt id="sourcepkg">Source packages -<p> - -The Debian binary packages in the distribution are generated from -Debian sources, which are in a special format to assist the easy and -automatic building of binaries. -<p> - -There was a previous version of the Debian source format, which is now -being phased out. Instructions for converting an old-style package -are given in the Debian policy manual. - -<sect id="sourcetools">Tools for processing source packages -<p> - -Various tools are provided for manipulating source packages; they pack -and unpack sources and help build of binary packages and help manage -the distribution of new versions. -<p> - -They are introduced and typical uses described here; see <manref -name=dpkg-source section=1> for full documentation about their -arguments and operation. -<p> - -For examples of how to construct a Debian source package, and how to -use those utilities that are used by Debian source packages, please -see the <prgn/hello/ example package. - -<sect1><prgn/dpkg-source/ - packs and unpacks Debian source packages -<p> - -This program is frequently used by hand, and is also called from -package-independent automated building scripts such as -<prgn/dpkg-buildpackage/. -<p> - -To unpack a package it is typically invoked with -<example> -dpkg-source -x <var>.../path/to/filename</>.dsc -</example> -with the <tt/<var/filename/.tar.gz/ and -<tt/<var/filename/.diff.gz/ (if applicable) in the same directory. It -unpacks into <tt/<var/package/-<var/version//, and if applicable -<tt/<var/package/-<var/version/.orig/, in the current directory. -<p> - -To create a packed source archive it is typically invoked: -<example> -dpkg-source -b <var/package/-<var/version/ -</example> -This will create the <tt/.dsc/, <tt/.tar.gz/ and <tt/.diff.gz/ (if -appropriate) in the current directory. <prgn/dpkg-source/ does not -clean the source tree first - this must be done separately if it is -required. -<p> - -See also <ref id="sourcearchives">. - - -<sect1><prgn/dpkg-buildpackage/ - overall package-building control -script -<p> - -<prgn/dpkg-buildpackage/ is a script which invokes <prgn/dpkg-source/, -the <tt>debian/rules</> targets <prgn/clean/, <prgn/build/ and -<prgn/binary/, <prgn/dpkg-genchanges/ and <prgn/pgp/ to build a signed -source and binary package upload. -<p> - -It is usually invoked by hand from the top level of the built or -unbuilt source directory. It may be invoked with no arguments; useful -arguments include: -<taglist compact> -<tag><tt/-uc/, <tt/-us/ -<item>Do not PGP-sign the <tt/.changes/ file or the source package -<tt/.dsc/ file, respectively. - -<tag><tt/-p<var/pgp-command// -<item>Invoke <var/pgp-command/ instead of finding <tt/pgp/ on the -<prgn/PATH/. <var/pgp-command/ must behave just like <prgn/pgp/. - -<tag><tt/-r<var/root-command// -<item>When root privilege is required, invoke the command -<var/root-command/. <var/root-command/ should invoke its first -argument as a command, from the <prgn/PATH/ if necessary, and pass its -second and subsequent arguments to the command it calls. If no -<var/root-command/ is supplied then <var/dpkg-buildpackage/ will take -no special action to gain root privilege, so that for most packages it -will have to be invoked as root to start with. - -<tag><tt/-b/, <tt/-B/ -<item>Two types of binary-only build and upload - see <manref -name=dpkg-source section=1>. -</taglist> - - -<sect1><prgn/dpkg-gencontrol/ - generates binary package control files -<p> - -This program is usually called from <tt>debian/rules</> (see <ref -id="sourcetree">) in the top level of the source tree. -<p> - -This is usually done just before the files and directories in the -temporary directory tree where the package is being built have their -permissions and ownerships set and the package is constructed using -<prgn/dpkg-deb/<footnote>This is so that the control file which is -produced has the right permissions</footnote>. -<p> - -<prgn/dpkg-gencontrol/ must be called after all the files which are to -go into the package have been placed in the temporary build directory, -so that its calculation of the installed size of a package is correct. -<p> - -It is also necessary for <prgn/dpkg-gencontrol/ to be run after -<prgn/dpkg-shlibdeps/ so that the variable substitutions created by -<prgn/dpkg-shlibdeps/ in <tt>debian/substvars</> are available. -<p> - -For a package which generates only one binary package, and which -builds it in <tt>debian/tmp</> relative to the top of the source -package, it is usually sufficient to call: -<example> -dpkg-gencontrol -</example> -<p> - -Sources which build several binaries will typically need something -like: -<example> -dpkg-gencontrol -Pdebian/tmp-<var/pkg/ -p<var/package/ -</example> -The <tt/-P/ tells <prgn/dpkg-gencontrol/ that the package is being -built in a non-default directory, and the <tt/-p/ tells it which -package's control file should be generated. -<p> - -<prgn/dpkg-gencontrol/ also adds information to the list of files in -<tt>debian/files</>, for the benefit of (for example) a future -invocation of <prgn/dpkg-genchanges/. - - -<sect1><prgn/dpkg-shlibdeps/ - calculates shared library dependencies -<p> - -This program is usually called from <tt>debian/rules</> just before -<prgn/dpkg-gencontrol/ (see <ref id="sourcetree">), in the top level -of the source tree. -<p> - -Its arguments are executables<footnote>They may be specified either -in the locations in the source tree where they are created or in the -locations in the temporary build tree where they are installed prior -to binary package creation.</footnote> for which shared library -dependencies should be included in the binary package's control file. -<p> - -If some of the executable(s) shared libraries should only warrant a -<tt/Recommends/ or <tt/Suggests/, or if some warrant a -<tt/Pre-Depends/, this can be achieved by using the -<tt/-d<var/dependency-field// option before those executable(s). -(Each <tt/-d/ option takes effect until the next <tt/-d/.) -<p> - -<prgn/dpkg-shlibdeps/ does not directly cause the output control file -to be modified. Instead by default it adds to the -<tt>debian/substvars</> file variable settings like -<tt/shlibs:Depends/. These variable settings must be referenced in -dependency fields in the appropriate per-binary-package sections of -the source control file. -<p> - -For example, the <prgn/procps/ package generates two kinds of -binaries, simple C binaries like <prgn/ps/ which require a -predependency and full-screen ncurses binaries like <prgn/top/ which -require only a recommendation. It can say in its <tt>debian/rules</>: -<example> -dpkg-shlibdeps -dPre-Depends ps -dRecommends top -</example> -and then in its main control file <tt>debian/control</>: -<example> -<var/.../ -Package: procps -Pre-Depends: ${shlibs:Pre-Depends} -Recommends: ${shlibs:Recommends} -<var/.../ -</example> -<p> - -Sources which produce several binary packages with different shared -library dependency requirements can use the <tt/-p<var/varnameprefix// -option to override the default <tt/shlib:/ prefix (one invocation of -<prgn/dpkg-shlibdeps/ per setting of this option). They can thus -produce several sets of dependency variables, each of the form -<tt/<var/varnameprefix/:<var/dependencyfield//, which can be referred -to in the appropriate parts of the binary package control files. - - -<sect1><prgn/dpkg-distaddfile/ - adds a file to <tt>debian/files</> -<p> - -Some packages' uploads need to include files other than the source and -binary package files. -<p> - -<prgn/dpkg-distaddfile/ adds a file to the <tt>debian/files</> file so -that it will be included in the <tt/.changes/ file when -<prgn/dpkg-genchanges/ is run. -<p> - -It is usually invoked from the <prgn/binary/ target of -<tt>debian/rules</>: -<example> -dpkg-distaddfile <var/filename/ <var/section/ <var/priority/ -</example> -The <var/filename/ is relative to the directory where -<prgn/dpkg-genchanges/ will expect to find it - this is usually the -directory above the top level of the source tree. The -<tt>debian/rules</> target should put the file there just before or -just after calling <prgn/dpkg-distaddfile/. -<p> - -The <var/section/ and <var/priority/ are passed unchanged into the -resulting <tt/.changes/ file. See <ref id="f-classification">. - - -<sect1><prgn/dpkg-genchanges/ - generates a <tt/.changes/ upload -control file -<p> - -This program is usually called by package-independent automatic -building scripts such as <prgn/dpkg-buildpackage/, but it may also be -called by hand. -<p> - -It is usually called in the top level of a built source tree, and when -invoked with no arguments will print out a straightforward -<tt/.changes/ file based on the information in the source package's -changelog and control file and the binary and source packages which -should have been built. - - -<sect1><prgn/dpkg-parsechangelog/ - produces parsed representation of -a changelog -<p> - -This program is used internally by <prgn/dpkg-source/ et al. It may -also occasionally be useful in <tt>debian/rules</> and elsewhere. It -parses a changelog, <tt>debian/changelog</> by default, and prints a -control-file format representation of the information in it to -standard output. - -<sect id="sourcetree">The Debianised source tree -<p> - -The source archive scheme described later is intended to allow a -Debianised source tree with some associated control information to be -reproduced and transported easily. The Debianised source tree is a -version of the original program with certain files added for the -benefit of the Debianisation process, and with any other changes -required made to the rest of the source code and installation scripts. -<p> - -The extra files created for Debian are in the subdirectory <tt/debian/ -of the top level of the Debianised source tree. They are described -below. - -<sect1><tt>debian/rules</tt> - the main building script -<p> - -This file is an executable makefile, and contains the package-specific -recipies for compiling the package and building binary package(s) out -of the source. -<p> - -It must start with the line <tt>#!/usr/bin/make -f</tt>, so that it -can be invoked by saying its name rather than invoking <prgn/make/ -explicitly. -<p> - -The targets which are required to be present are: - -<taglist> -<tag/<tt/build// -<item> - -This should perform all non-interactive configuration and compilation -of the package. If a package has an interactive pre-build -configuration routine, the Debianised source package should be built -after this has taken place, so that it can be built without rerunning -the configuration. -<p> - -For some packages, notably ones where the same source tree is compiled -in different ways to produce two binary packages, the <prgn/build/ -target does not make much sense. For these packages it is good enough -to provide two (or more) targets (<tt/build-a/ and <tt/build-b/ or -whatever) for each of the ways of building the package, and a -<prgn/build/ target that does nothing. The <prgn/binary/ target will have -to build the package in each of the possible ways and make the binary -package out of each. -<p> - -The <prgn/build/ target must not do anything that might require root -privilege. -<p> - -The <prgn/build/ target may need to run <prgn/clean/ first - see below. -<p> - -When a package has a configuration routine that takes a long time, or -when the makefiles are poorly designed, or when <prgn/build/ needs to -run <prgn/clean/ first, it is a good idea to <tt/touch build/ when the -build process is complete. This will ensure that if <tt>debian/rules -build</tt> is run again it will not rebuild the whole program. - -<tag/<tt/binary/, <tt/binary-arch/, <tt/binary-indep/ -<item> - -The <prgn/binary/ target should be all that is necessary for the user -to build the binary package. It is split into two parts: -<prgn/binary-arch/ builds the packages' output files which are -specific to a particular architecture, and <prgn/binary-indep/ -builds those which are not. -<p> - -<prgn/binary/ should usually be a target with no commands which simply -depends on <prgn/binary-arch/ and <prgn/binary-indep/. -<p> - -Both <prgn/binary-*/ targets should depend on the <prgn/build/ target, -above, so that the package is built if it has not been already. It -should then create the relevant binary package(s), using -<prgn/dpkg-gencontrol/ to make their control files and <prgn/dpkg-deb/ -to build them and place them in the parent of the top level directory. -<p> - -If one of the <prgn/binary-*/ targets has nothing to do (this will be -always be the case if the source generates only a single binary -package, whether architecture-dependent or not) it <em/must/ still -exist, but should always succeed. -<p> - -<ref id="binarypkg"> describes how to construct binary packages. -<p> - -The <prgn/binary/ targets must be invoked as root. - -<tag/<tt/clean// -<item> - -This should undo any effects that the <prgn/build/ and <prgn/binary/ -targets may have had, except that it should leave alone any output -files created in the parent directory by a run of <prgn/binary/. -<p> - -If a <prgn/build/ file is touched at the end of the <prgn/build/ target, -as suggested above, it must be removed as the first thing that -<prgn/clean/ does, so that running <prgn/build/ again after an interrupted -<prgn/clean/ doesn't think that everything is already done. -<p> - -The <prgn/clean/ target must be invoked as root if <prgn/binary/ has -been invoked since the last <prgn/clean/, or if <prgn/build/ has been -invoked as root (since <prgn/build/ may create directories, for -example). - -<tag/<tt/get-orig-source/ (optional)/ -<item> - -This target fetches the most recent version of the original source -package from a canonical archive site (via FTP or WWW, for example), -does any necessary rearrangement to turn it into the original source -tarfile format described below, and leaves it in the current directory. -<p> - -This target may be invoked in any directory, and should take care to -clean up any temporary files it may have left. -<p> - -This target is optional, but providing it if possible is a good idea. - -</taglist> - -The <prgn/build/, <prgn/binary/ and <prgn/clean/ targets must be -invoked with a current directory of the package's top-level -directory. - -<p> - -Additional targets may exist in <tt>debian/rules</tt>, either as -published or undocumented interfaces or for the package's internal -use. - - -<sect1><tt>debian/control</tt> -<p> - -This file contains version-independent details about the source -package and about the binary packages it creates. -<p> - -It is a series of sets of control fields, each syntactically similar -to a binary package control file. The sets are separated by one or -more blank lines. The first set is information about the source -package in general; each subsequent set describes one binary package -that the source tree builds. -<p> - -The syntax and semantics of the fields are described below in -<ref id="controlfields">. -<p> - -The general (binary-package-independent) fields are: -<list compact> -<item><qref id="f-Source"><tt/Source/</> (mandatory) -<item><qref id="f-Maintainer"><tt/Maintainer/</> -<item><qref id="f-classification"><tt/Section/ and <tt/Priority/</> -(classification, mandatory) -<item><qref id="f-Standards-Version"><tt/Standards-Version/</> -</list> -<p> - -The per-binary-package fields are: -<list compact> -<item><qref id="f-Package"><tt/Package/</> (mandatory) -<item><qref id="f-Architecture"><tt/Architecture/</> (mandatory) -<item><qref id="descriptions"><tt/Description/</> -<item><qref id="f-classification"><tt/Section/ and <tt/Priority/</> (classification) -<item><qref id="f-Essential"><tt/Essential/</> -<item><qref id="relationships"><tt/Depends/ et al.</> (package interrelationships) -</list> -<p> - -These fields are used by <prgn/dpkg-gencontrol/ to generate control -files for binary packages (see below), by <prgn/dpkg-genchanges/ to -generate the <tt/.changes/ file to accompany the upload, and by -<prgn/dpkg-source/ when it creates the <tt/.dsc/ source control file as -part of a source archive. -<p> - -The fields here may contain variable references - their values will be -substituted by <prgn/dpkg-gencontrol/, <prgn/dpkg-genchanges/ or -<prgn/dpkg-source/ when they generate output control files. See <ref -id="srcsubstvars"> for details. -<p> - -<sect2>User-defined fields -<p> - -Additional user-defined fields may be added to the source package -control file. Such fields will be ignored, and not copied to (for -example) binary or source package control files or upload control -files. -<p> - -If you wish to add additional unsupported fields to these output files -you should use the mechanism described here. -<p> - -Fields in the main source control information file with names starting -<tt/X/, followed by one or more of the letters <tt/BCS/ and a hyphen -<tt/-/, will be copied to the output files. Only the part of the -field name after the hyphen will be used in the output file. Where -the letter <tt/B/ is used the field will appear in binary package -control files, where the letter <tt/S/ is used in source package -control files and where <tt/C/ is used in upload control -(<tt/.changes/) files. -<p> - -For example, if the main source information control file contains the -field -<example> -XBS-Comment: I stand between the candle and the star. -</example> -then the binary and source package control files will contain the -field -<example> -Comment: I stand between the candle and the star. -</example> - -<sect1 id="dpkgchangelog"><tt>debian/changelog</> -<p> - -This file records the changes to the Debian-specific parts of the -package<footnote>Though there is nothing stopping an author who is -also the Debian maintainer from using it for all their changes, it -will have to be renamed if the Debian and upstream maintainers become -different people.</footnote>. -<p> - -It has a special format which allows the package building tools to -discover which version of the package is being built and find out -other release-specific information. -<p> - -That format is a series of entries like this: -<p> -<example> -<var/package/ (<var/version/) <var/distribution(s)/; urgency=<var/urgency/ - - * <var/change details/ - <var/more change details/ - * <var/even more change details/ - - -- <var/maintainer name and email address/ <var/date/ -</example> -<p> - -<var/package/ and <var/version/ are the source package name and -version number. -<p> -<var/distribution(s)/ lists the distributions where -this version should be installed when it is uploaded - it is copied to -the <tt/Distribution/ field in the <tt/.changes/ file. See <ref -id="f-Distribution">. -<p> - -<var/urgency/ is the value for the <tt/Urgency/ field in the -<tt/.changes/ file for the upload. See <ref id="f-Urgency">. It is -not possible to specify an urgency containing commas; commas are used -to separate <tt/<var/keyword/=<var/value// settings in the <prgn/dpkg/ -changelog format (though there is currently only one useful -<var/keyword/, <tt/urgency/). -<p> - -The change details may in fact be any series of lines starting with at -least two spaces, but conventionally each change starts with an -asterisk and a separating space and continuation lines are indented so -as to bring them in line with the start of the text above. Blank -lines may be used here to separate groups of changes, if desired. -<p> - -The maintainer name and email address should <em/not/ necessarily be -those of the usual package maintainer. They should be the details of -the person doing <em/this/ version. The information here will be -copied to the <tt/.changes/ file, and then later used to send an -acknowledgement when the upload has been installed. -<p> - -The <var/date/ should be in RFC822 format<footnote>This is generated -by the <prgn/822-date/ program.</footnote>; it should include the -timezone specified numerically, with the timezone name or abbreviation -optionally present as a comment. -<p> - -The first `title' line with the package name should start at the left -hand margin; the `trailer' line with the maintainer and date details -should be preceded by exactly one space. The maintainer details and -the date must be separated by exactly two spaces. -<p> - -An Emacs mode for editing this format is available: it is called -<tt/debian-changelog-mode/. You can have this mode selected -automatically when you edit a Debian changelog by adding a local -variables clause to the end of the changelog. - -<sect2>Defining alternative changelog formats -<p> - -It is possible to use a different format to the standard one, by -providing a parser for the format you wish to use. -<p> - -In order to have <tt/dpkg-parsechangelog/ run your parser, you must -include a line within the last 40 lines of your file matching the Perl -regular expression: -<tt>\schangelog-format:\s+([0-9a-z]+)\W</tt> -The part in parentheses should be the name of the format. For -example, you might say: -<example> -@@@ changelog-format: joebloggs @@@ -</example> -Changelog format names are non-empty strings of alphanumerics. -<p> - -If such a line exists then <tt/dpkg-parsechangelog/ will look for the -parser as <tt>/usr/lib/dpkg/parsechangelog/<var/format-name/</> or -<tt>/usr/local/lib/dpkg/parsechangelog/<var/format-name/</>; it is an -error for it not to find it, or for it not to be an executable -program. The default changelog format is <tt/dpkg/, and a parser for -it is provided with the <tt/dpkg/ package. -<p> - -The parser will be invoked with the changelog open on standard input -at the start of the file. It should read the file (it may seek if it -wishes) to determine the information required and return the parsed -information to standard output in the form of a series of control -fields in the standard format. By default it should return -information about only the most recent version in the changelog; it -should accept a <tt/-v<var/version// option to return changes -information from all versions present <em/strictly after/ -<var/version/, and it should then be an error for <var/version/ not to -be present in the changelog. -<p> - -The fields are: -<list compact> -<item><qref id="f-Source"><tt/Source/</> -<item><qref id="versions"><tt/Version/</> (mandatory) -<item><qref id="f-Distribution"><tt/Distribution/</> (mandatory) -<item><qref id="f-Urgency"><tt/Urgency/</> (mandatory) -<item><qref id="f-Maintainer"><tt/Maintainer/</> (mandatory) -<item><qref id="f-Date"><tt/Date/</> -<item><qref id="f-Changes"><tt/Changes/</> (mandatory) -</list> -<p> - -If several versions are being returned (due to the use of <tt/-v/), -the urgency value should be of the highest urgency code listed at the -start of any of the versions requested followed by the concatenated -(space-separated) comments from all the versions requested; the -maintainer, version, distribution and date should always be from the -most recent version. -<p> - -For the format of the <tt/Changes/ field see <ref id="f-Changes">. -<p> - -If the changelog format which is being parsed always or almost always -leaves a blank line between individual change notes these blank lines -should be stripped out, so as to make the resulting output compact. -<p> - -If the changelog format does not contain date or package name -information this information should be omitted from the output. The -parser should not attempt to synthesise it or find it from other -sources. -<p> - -If the changelog does not have the expected format the parser should -exit with a nonzero exit status, rather than trying to muddle through -and possibly generating incorrect output. -<p> - -A changelog parser may not interact with the user at all. - -<sect1 id="srcsubstvars"><tt>debian/substvars</> and variable substitutions -<p> - -When <prgn/dpkg-gencontrol/, <prgn/dpkg-genchanges/ and -<prgn/dpkg-source/ generate control files they do variable -substitutions on their output just before writing it. Variable -substitutions have the form <tt/${<var/variable-name/}/. The optional -file <tt>debian/substvars</> contains variable substitutions to be -used; variables can also be set directly from <tt>debian/rules</> -using the <tt/-V/ option to the source packaging commands, and certain -predefined variables are available. -<p> - -The is usually generated and modified dynamically by -<tt>debian/rules</> targets; in this case it must be removed by the -<prgn/clean/ target. -<p> - - - -See <manref name=dpkg-source section=1> for full details about source -variable substitutions, including the format of -<tt>debian/substvars</>. - -<sect1><tt>debian/files</> -<p> - -This file is not a permanent part of the source tree; it is used while -building packages to record which files are being generated. -<prgn/dpkg-genchanges/ uses it when it generates a <tt/.changes/ file. -<p> - -It should not exist in a shipped source package, and so it (and any -backup files or temporary files such as -<tt/files.new/<footnote><tt/files.new/ is used as a temporary file by -<prgn/dpkg-gencontrol/ and <prgn/dpkg-distaddfile/ - they write a new -version of <tt/files/ here before renaming it, to avoid leaving a -corrupted copy if an error occurs</footnote>) should be removed by the -<prgn/clean/ target. It may also be wise to ensure a fresh start by -emptying or removing it at the start of the <prgn/binary/ target. -<p> - -<prgn/dpkg-gencontrol/ adds an entry to this file for the <tt/.deb/ -file that will be created by <prgn/dpkg-deb/ from the control file -that it generates, so for most packages all that needs to be done with -this file is to delete it in <prgn/clean/. -<p> - -If a package upload includes files besides the source package and any -binary packages whose control files were made with -<prgn/dpkg-gencontrol/ then they should be placed in the parent of the -package's top-level directory and <prgn/dpkg-distaddfile/ should be -called to add the file to the list in <tt>debian/files</>. - -<sect1><tt>debian/tmp</> -<p> - -This is the canonical temporary location for the construction of -binary packages by the <prgn/binary/ target. The directory <tt/tmp/ -serves as the root of the filesystem tree as it is being constructed -(for example, by using the package's upstream makefiles install -targets and redirecting the output there), and it also contains the -<tt/DEBIAN/ subdirectory. See <ref id="bincreating">. -<p> - -If several binary packages are generated from the same source tree it -is usual to use several <tt>debian/tmp<var/something/</> directories, -for example <tt/tmp-a/ or <tt/tmp-doc/. -<p> - -Whatever <tt>tmp</> directories are created and used by <prgn/binary/ -must of course be removed by the <prgn/clean/ target. - - -<sect id="sourcearchives">Source packages as archives -<p> - -As it exists on the FTP site, a Debian source package consists of -three related files. You must have the right versions of all three to -be able to use them. -<p> - -<taglist> -<tag/Debian source control file - <tt/.dsc// -<item> - -This file contains a series of fields, identified and separated just -like the fields in the control file of a binary package. The fields -are listed below; their syntax is described above, in -<ref id="controlfields">. -<list compact> -<item><qref id="f-Source"><tt/Source/</> -<item><qref id="versions"><tt/Version/</> -<item><qref id="f-Maintainer"><tt/Maintainer/</> -<item><qref id="f-Binary"><tt/Binary/</> -<item><qref id="f-Architecture"><tt/Architecture/</> -<item><qref id="f-Standards-Version"><tt/Standards-Version/</> -<item><qref id="f-Files"><tt/Files/</> -</list> -<p> - -The source package control file is generated by <prgn/dpkg-source/ -when it builds the source archive, from other files in the source -package, described above. When unpacking it is checked against the -files and directories in the other parts of the source package, as -described below. - -<tag/Original source archive - <tt/<var/package/_<var/upstream-version/.orig.tar.gz// -<item> - -This is a compressed (with <tt/gzip -9/) <prgn/tar/ file containing -the source code from the upstream authors of the program. The tarfile -unpacks into a directory -<tt/<var/package/-<var/upstream-version/.orig/, and does not contain -files anywhere other than in there or in its subdirectories. - -<tag/Debianisation diff - <tt/<var/package/_<var/upstream_version-revision/.diff.gz// -<item> - -This is a unified context diff (<tt/diff -u/) giving the changes which -are required to turn the original source into the Debian source. -These changes may only include editing and creating plain files. The -permissions of files, the targets of symbolic links and the -characteristics of special files or pipes may not be changed and no -files may be removed or renamed. -<p> - -All the directories in the diff must exist, except the <tt/debian/ -subdirectory of the top of the source tree, which will be created by -<prgn/dpkg-source/ if necessary when unpacking. -<p> - -The <prgn/dpkg-source/ program will automatically make the -<tt>debian/rules</tt> file executable (see below). - -</taglist> -<p> - -If there is no original source code - for example, if the package is -specially prepared for Debian or the Debian maintainer is the same as -the upstream maintainer - the format is slightly different: then there -is no diff, and the tarfile is named -<tt/<var/package/_<var/version/.tar.gz</> and contains a directory -<tt/<var/package/-<var/version/</>. - -<sect>Unpacking a Debian source package without <prgn/dpkg-source/ -<p> - -<tt/dpkg-source -x/ is the recommended way to unpack a Debian source -package. However, if it is not available it is possible to unpack a -Debian source archive as follows: - -<enumlist compact> -<item>Untar the tarfile, which will create a <tt/.orig/ directory. -<item>Rename the <tt/.orig/ directory to -<tt/<var/package/-<var/version//. -<item>Create the subdirectory <tt/debian/ at the top of the source -tree. -<item>Apply the diff using <tt/patch -p0/. -<item>Untar the tarfile again if you want a copy of the original -source code alongside the Debianised version. -</enumlist> -<p> - -It is not possible to generate a valid Debian source archive without -using <prgn/dpkg-source/. In particular, attempting to use -<prgn/diff/ directly to generate the <tt/.diff.gz/ file will not work. - -<sect1>Restrictions on objects in source packages -<p> - -The source package may not contain any hard links<footnote>This is not -currently detected when building source packages, but only when -extracting them.</footnote><footnote>Hard links may be permitted at -some point in the future, but would require a fair amount of -work.</footnote>, device special files, sockets or setuid or setgid -files.<footnote>Setgid directories are allowed.</footnote> -<p> - -The source packaging tools manage the changes between the original and -Debianised source using <prgn/diff/ and <prgn/patch/. Turning the -original source tree as included in the <tt/.orig.tar.gz/ into the -debianised source must not involve any changes which cannot be handled -by these tools. Problematic changes which cause <prgn/dpkg-source/ to -halt with an error when building the source package are: -<list compact> -<item>Adding or removing symbolic links, sockets or pipes. -<item>Changing the targets of symbolic links. -<item>Creating directories, other than <tt/debian/. -<item>Changes to the contents of binary files. -</list> -Changes which cause <prgn/dpkg-source/ to print a warning but continue -anyway are: -<list compact> -<item>Removing files, directories or symlinks. <footnote>Renaming a -file is not treated specially - it is seen as the removal of the old -file (which generates a warning, but is otherwise ignored), and the -creation of the new one.</footnote> -<item>Changed text files which are missing the usual final newline -(either in the original or the modified source tree). -</list> -Changes which are not represented, but which are not detected by -<prgn/dpkg-source/, are: -<list compact> -<item>Changing the permissions of files (other than -<tt>debian/rules</>) and directories. -</list> -<p> - -The <tt/debian/ directory and <tt>debian/rules</> are handled -specially by <prgn/dpkg-source/ - before applying the changes it will -create the <tt/debian/ directory, and afterwards it will make -<tt>debian/rules</> world-exectuable. - -<chapt id="controlfields">Control files and their fields -<p> - -Many of the tools in the <prgn/dpkg/ suite manipulate data in a common -format, known as control files. Binary and source packages have -control data as do the <tt/.changes/ files which control the -installation of uploaded files, and <prgn/dpkg/'s internal databases -are in a similar format. - -<sect>Syntax of control files -<p> - -A file consists of one or more paragraphs of fields. The paragraphs -are separated by blank lines. Some control files only allow one -paragraph; others allow several, in which case each paragraph often -refers to a different package. -<p> - -Each paragraph is a series of fields and values; each field consists -of a name, followed by a colon and the value. It ends at the end of -the line. Horizontal whitespace (spaces and tabs) may occur before or -after the value and is ignored there; it is conventional to put a -single space after the colon. -<p> - -Some fields' values may span several lines; in this case each -continuation line <em/must/ start with a space or tab. Any trailing -spaces or tabs at the end of individual lines of a field value are -ignored. -<p> - -Except where otherwise stated only a single line of data is allowed -and whitespace is not significant in a field body. Whitespace may -never appear inside names (of packages, architectures, files or -anything else), version numbers or in between the characters of -multi-character version relationships. -<p> - -Field names are not case-sensitive, but it is usual to capitalise the -fields using mixed case as shown below. -<p> - -Blank lines, or lines consisting only of spaces and tabs, are not -allowed within field values or between fields - that would mean a new -paragraph. -<p> - -It is important to note that there are several fields which are -optional as far as <prgn/dpkg/ and the related tools are concerned, -but which must appear in every Debian package, or whose omission may -cause problems. When writing the control files for Debian packages -you <em/must/ read the Debian policy manual in conjuction with the -details below and the list of fields for the particular file. - -<sect>List of fields - -<sect1 id="f-Package"><tt/Package/ -<p> - -The name of the binary package. Package names consist of the -alphanumerics and <tt/+/ <tt/-/ <tt/./ (plus, minus and full -stop).<footnote>The characters <tt/@/ <tt/:/ <tt/=/ <tt/%/ <tt/_/ (at, -colon, equals, percent and underscore) used to be legal and are still -accepted when found in a package file, but may not be used in new -packages</footnote> -<p> - -They must be at least two characters and must start with an -alphanumeric. In current versions of dpkg they are sort of -case-sensitive<footnote>This is a bug.</footnote>; use lowercase -package names unless the package you're building (or referring to, in -other fields) is already using uppercase. - -<sect1 id="f-Version"><tt/Version/ -<p> - -This lists the source or binary package's version number - see <ref -id="versions">. - -<sect1 id="f-Architecture"><tt/Architecture/ -<p> - -This is the architecture string; it is a single word for the CPU -architecture. -<p> - -<prgn/dpkg/ will check the declared architecture of a binary package -against its own compiled-in value before it installs it. -<p> - -The special value <tt/all/ indicates that the package is -architecture-independent. -<p> - -In the main <tt>debian/control</> file in the source package, or in -the source package control file <tt/.dsc/, a list of architectures -(separated by spaces) is also allowed, as is the special value -<tt/any/. A list indicates that the source will build an -architecture-dependent package, and will only work correctly on the -listed architectures. <tt/any/ indicates that though the source -package isn't dependent on any particular architecture and should -compile fine on any one, the binary package(s) produced are not -architecture-independent but will instead be specific to whatever the -current build architecture is. -<p> - -In a <tt/.changes/ file the <tt/Architecture/ field lists the -architecture(s) of the package(s) currently being uploaded. This will -be a list; if the source for the package is being uploaded too the -special entry <tt/source/ is also present. -<p> - -The current build architecture can be determined using <tt/dpkg ---print-architecture/.<footnote>This actually invokes -<example> -gcc --print-libgcc-file-name -</example> -and parses and decomposes the output and looks the CPU type from the -GCC configuration in a table in <prgn/dpkg/. This is so that it will -work if you're cross-compiling. -</footnote> -This value is automatically used by <prgn/dpkg-gencontrol/ when -building the control file for a binary package for which the source -control information doesn't specify architecture <tt/all/. -<p> - -There is a separate option, <tt/--print-installation-architecture/, -for finding out what architecture <prgn/dpkg/ is willing to install. -This information is also in the output of <tt/dpkg --version/. - -<sect1 id="f-Maintainer"><tt/Maintainer/ -<p> - -The package maintainer's name and email address. The name should come -first, then the email address inside angle brackets <tt/<>/ (in -RFC822 format). -<p> - -If the maintainer's name contains a full stop then the whole field -will not work directly as an email address due to a misfeature in the -syntax specified in RFC822; a program using this field as an address -must check for this and correct the problem if necessary (for example -by putting the name in round brackets and moving it to the end, and -bringing the email address forward). -<p> - -In a <tt/.changes/ file or parsed changelog data this contains the -name and email address of the person responsible for the particular -version in question - this may not be the package's usual maintainer. -<p> - -This field is usually optional in as far as the <prgn/dpkg/ are -concerned, but its absence when building packages usually generates a -warning. - -<sect1 id="f-Source"><tt/Source/ -<p> - -This field identifies the source package name. -<p> - -In a main source control information or a <tt/.changes/ or <tt/.dsc/ -file or parsed changelog data this may contain only the name of the -source package. -<p> - -In the control file of a binary package (or in a <tt/Packages/ file) -it may be followed by a version number in parentheses.<footnote>It is -usual to leave a space after the package name if a version number is -specified.</footnote> This version number may be omitted (and is, by -<prgn/dpkg-gencontrol/) if it has the same value as the <tt/Version/ -field of the binary package in question. The field itself may be -omitted from a binary package control file when the source package has -the same name and version as the binary package. - -<sect1>Package interrelationship fields: -<tt/Depends/, <tt/Pre-Depends/, <tt/Recommends/ -<tt/Suggests/, <tt/Conflicts/, <tt/Provides/, <tt/Replaces/ -<p> - -These fields describe the package's relationships with other packages. -Their syntax and semantics are described in <ref id="relationships">. - -<sect1 id="f-Description"><tt/Description/ -<p> - -In a binary package <tt/Packages/ file or main source control file -this field contains a description of the binary package, in a special -format. See <ref id="descriptions"> for details. -<p> - -In a <tt/.changes/ file it contains a summary of the descriptions for -the packages being uploaded. The part of the field before the first -newline is empty; thereafter each line has the name of a binary -package and the summary description line from that binary package. -Each line is indented by one space. - -<sect1 id="f-Essential"><tt/Essential/ -<p> - -This is a boolean field which may occur only in the control file of a -binary package (or in the <tt/Packages/ file) or in a per-package -fields paragraph of a main source control data file. -<p> - -If set to <tt/yes/ then <prgn/dpkg/ and <prgn/dselect/ will refuse to -remove the package (though it can be upgraded and/or replaced). The -other possible value is <tt/no/, which is the same as not having the -field at all. - -<sect1 id="f-classification"><tt/Section/ and <tt/Priority/ -<p> - -These two fields classify the package. The <tt/Priority/ represents -how important that it is that the user have it installed; the -<tt/Section/ represents an application area into which the package has -been classified. -<p> - -When they appear in the <tt>debian/control</> file these fields give -values for the section and priority subfields of the <tt/Files/ field -of the <tt/.changes/ file, and give defaults for the section and -priority of the binary packages. -<p> - -The section and priority are represented, though not as separate -fields, in the information for each file in the <qref -id="f-Files"><tt/Files/</> field of a <tt/.changes/ file. The -section value in a <tt/.changes/ file is used to decide where to -install a package in the FTP archive. -<p> - -These fields are not used by by <prgn/dpkg/ proper, but by -<prgn/dselect/ when it sorts packages and selects defaults. See the -Debian policy manual for the priorities in use and the criteria for -selecting the priority for a Debian package, and look at the Debian -FTP archive for a list of currently in-use priorities. -<p> - -These fields may appear in binary package control files, in which case -they provide a default value in case the <tt/Packages/ files are -missing the information. <prgn/dpkg/ and <prgn/dselect/ will only use -the value from a <tt/.deb/ file if they have no other information; a -value listed in a <tt/Packages/ file will always take precedence. By -default <prgn/dpkg-genchanges/ does not include the section and -priority in the control file of a binary package - use the <tt/-isp/, -<tt/-is/ or <tt/-ip/ options to achieve this effect. - -<sect1 id="f-Binary"><tt/Binary/ -<p> - -This field is a list of binary packages. -<p> - -When it appears in the <tt/.dsc/ file it is the list of binary -packages which a source package can produce. It does not necessarily -produce all of these binary packages for every architecture. The -source control file doesn't contain details of which architectures are -appropriate for which of the binary packages. -<p> - -When it appears in a <tt/.changes/ file it lists the names of the -binary packages actually being uploaded. -<p> - -The syntax is a list of binary packages separated by -commas.<footnote>A space after each comma is conventional.</footnote> -Currently the packages must be separated using only spaces in the -<tt/.changes/ file. - -<sect1 id="f-Installed-Size"><tt/Installed-Size/ -<p> - -This field appears in the control files of binary packages, and in the -<tt/Packages/ files. It gives the total amount of disk space -required to install the named package. -<p> - -The disk space is represented in kilobytes as a simple decimal number. - -<sect1 id="f-Files"><tt/Files/ -<p> - -This field contains a list of files with information about each one. -The exact information and syntax varies with the context. In all -cases the the part of the field contents on the same line as the field -name is empty. The remainder of the field is one line per file, each -line being indented by one space and containing a number of sub-fields -separated by spaces. -<p> - -In the <tt/.dsc/ (Debian source control) file each line contains the -MD5 checksum, size and filename of the tarfile and (if applicable) -diff file which make up the remainder of the source -package.<footnote>That is, the parts which are not the -<tt/.dsc/.</footnote> The exact forms of the filenames are described -in <ref id="sourcearchives">. -<p> - -In the <tt/.changes/ file this contains one line per file being -uploaded. Each line contains the MD5 checksum, size, section and -priority and the filename. The section and priority are the values of -the corresponding fields in the main source control file - see <ref -id="f-classification">. If no section or priority is specified then -<tt/-/ should be used, though section and priority values must be -specified for new packages to be installed properly. -<p> - -The special value <tt/byhand/ for the section in a <tt/.changes/ file -indicates that the file in question is not an ordinary package file -and must by installed by hand by the distribution maintainers. If the -section is <tt/byhand/ the priority should be <tt/-/. -<p> - -If a new Debian revision of a package is being shipped and no new -original source archive is being distributed the <tt/.dsc/ must still -contain the <tt/Files/ field entry for the original source archive -<tt/<var/package/-<var/upstream-version/.orig.tar.gz/, but the -<tt/.changes/ file should leave it out. In this case the original -source archive on the distribution site must match exactly, -byte-for-byte, the original source archive which was used to generate -the <tt/.dsc/ file and diff which are being uploaded. - - -<sect1 id="f-Standards-Version"><tt/Standards-Version/ -<p> - -The most recent version of the standards (the <prgn/dpkg/ programmers' -and policy manuals and associated texts) with which the package -complies. This is updated manually when editing the source package to -conform to newer standards; it can sometimes be used to tell when a -package needs attention. -<p> - -Its format is the same as that of a version number except that no -epoch or Debian revision is allowed - see <ref id="versions">. - - -<sect1 id="f-Distribution"><tt/Distribution/ -<p> - -In a <tt/.changes/ file or parsed changelog output this contains the -(space-separated) name(s) of the distribution(s) where this version of -the package should be or was installed. Distribution names follow the -rules for package names. (See <ref id="f-Package">). -<p> - -Current distribution values are: -<taglist> -<tag/<em/stable// -<item> -This is the current `released' version of Debian GNU/Linux. A new -version is released approximately every 3 months after the -<em/development/ code has been <em/frozen/ for a month of testing. -Once the distribution is <em/stable/ only major bug fixes are -allowed. When changes are made to this distribution, the minor version -number is increased (for example: 1.2 becomes 1.2.1 then 1.2.2, etc). - -<tag/<em/unstable// -<item> -This distribution value refers to the <em/developmental/ part of the Debian -distribution tree. New packages, new upstream versions of packages and -bug fixes go into the <em/unstable/ directory tree. Download -from this distribution at your own risk. - -<tag/<em/contrib// -<item> -The packages with this distribution value do not meet the criteria for -inclusion in the main Debian distribution as defined by the Policy -Manual, but meet the criteria for the <em/contrib/ Distribution. There -is currently no distinction between stable and unstable packages in -the <em/contrib/ or <em/non-free/ distributions. Use your best -judgement in downloading from this Distribution. - -<tag/<em/non-free// -<item> -Like the packages in the <em/contrib/ seciton, the packages in -<em/non-free/ do not meet the criteria for inclusion in the main -Debian distribution as defined by the Policy Manual. Again, use your -best judgement in downloading from this Distribution. - -<tag/<em/experimental// -<item> -The packages with this distribution value are deemed by their -maintainers to be high risk. Oftentimes they represent early beta or -developmental packages from various sources that the maintainers want -people to try, but are not ready to be a part of the other parts of -the Debian distribution tree. Download at your own risk. - -<tag/<em/frozen// -<item> -From time to time, (currently, every 3 months) the <em/unstable/ -distribution enters a state of `code-freeze' in anticipation of -release as a <em/stable/ version. During this period of testing -(usually 4 weeks) only fixes for existing or newly-discovered bugs -will be allowed. - -</taglist> -<p> -You should list <em/all/ distributions that the package should be -installed into. Except in unusual circumstances, installations to -<em/stable/ should also go into <em/frozen/ (if it exists) and -<em/unstable/. Likewise, installations into <em/frozen/ should also go -into <em/unstable/. - -<sect1 id="f-Urgency"><tt/Urgency/ -<p> - -This is a description of how important it is to upgrade to this -version from previous ones. It consists of a single keyword usually -taking one of the values <tt/LOW/, <tt/MEDIUM/ or <tt/HIGH/) followed -by an optional commentary (separated by a space) which is usually in -parentheses. For example: -<example> -Urgency: LOW (HIGH for diversions users) -</example> -<p> - -This field appears in the <tt/.changes/ file and in parsed changelogs; -its value appears as the value of the <tt/urgency/ attribute in a -<prgn/dpkg/-style changelog (see <ref id="dpkgchangelog">). -<p> - -Urgency keywords are not case-sensitive. - -<sect1 id="f-Date"><tt/Date/ -<p> - -In <tt/.changes/ files and parsed changelogs, this gives the date the -package was built or last edited. - -<sect1 id="f-Format"><tt/Format/ -<p> - -This field occurs in <tt/.changes/ files, and specifies a format -revision for the file. The format described here is version <tt/1.5/. -The syntax of the format value is the same as that of a package -version number except that no epoch or Debian revision is allowed - -see <ref id="versions">. - -<sect1 id="f-Changes"><tt/Changes/ -<p> - -In a <tt/.changes/ file or parsed changelog this field contains the -human-readable changes data, describing the differences between the -last version and the current one. -<p> - -There should be nothing in this field before the first newline; all -the subsequent lines must be indented by at least one space; blank -lines must be represented by a line consiting only of a space and a -full stop. -<p> - -Each version's change information should be preceded by a `title' line -giving at least the version, distribution(s) and urgency, in a -human-readable way. -<p> - -If data from several versions is being returned the entry for the most -recent version should be returned first, and entries should be -separated by the representation of a blank line (the `title' line may -also be followed by the representation of blank line). - -<sect1 id="f-Filename"><tt/Filename/ and <tt/MSDOS-Filename/ -<p> - -These fields in <tt/Packages/ files give the filename(s) of (the parts -of) a package in the distribution directories, relative to the root of -the Debian hierarchy. If the package has been split into several -parts the parts are all listed in order, separated by spaces. - -<sect1 id="f-Size"><tt/Size/ and <tt/MD5sum/ -<p> - -These fields in <tt/Packages/ files give the size (in bytes, expressed -in decimal) and MD5 checksum of the file(s) which make(s) up a binary -package in the distribution. If the package is split into several -parts the values for the parts are listed in order, separated by -spaces. - -<sect1 id="f-Status"><tt/Status/ -<p> - -This field in <prgn/dpkg/'s status file records whether the user wants a -package installed, removed or left alone, whether it is broken -(requiring reinstallation) or not and what its current state on the -system is. Each of these pieces of information is a single word. - -<sect1 id="f-Config-Version"><tt/Config-Version/ -<p> - -If a package is not installed or not configured, this field in -<prgn/dpkg/'s status file records the last version of the package which -was successfully configured. - -<sect1 id="f-Conffiles"><tt/Conffiles/ -<p> - -This field in <prgn/dpkg/'s status file contains information about the -automatically-managed configuration files held by a package. This -field should <em/not/ appear anywhere in a package! - -<sect1>Obsolete fields -<p> - -These are still recognised by <prgn/dpkg/ but should not appear anywhere -any more. - -<taglist compact> - -<tag><tt/Revision/ -<tag><tt/Package-Revision/ -<tag><tt/Package_Revision/ -<item> -The Debian revision part of the package version was at one point in a -separate control file field. This field went through several names. - -<tag><tt/Recommended/ -<item>Old name for <tt/Recommends/ - -<tag><tt/Optional/ -<item>Old name for <tt/Suggests/. - -<tag><tt/Class/ -<item>Old name for <tt/Priority/. - -</taglist> - -<chapt id="versions">Version numbering -<p> - -Every package has a version number, in its <tt/Version/ control file -field. -<p> - -<prgn/dpkg/ imposes an ordering on version numbers, so that it can tell -whether packages are being up- or downgraded and so that <prgn/dselect/ -can tell whether a package it finds available is newer than the one -installed on the system. The version number format has the most -significant parts (as far as comparison is concerned) at the -beginning. -<p> - -The version number format is: -&lsqb<var/epoch/<tt/:/]<var/upstream-version/[<tt/-/<var/debian-revision/]. -<p> - -The three components here are: - -<taglist> - -<tag><var/epoch/ -<item> - -This is a single unsigned integer, which should usually be small. It -may be omitted, in which case zero is assumed. If it is omitted then -the <var/upstream-version/ may not contain any colons. -<p> - -It is provided to allow mistakes in the version numbers of older -versions of a package, and also a package's previous version numbering -schemes, to be left behind. -<p> - -<prgn/dpkg/ will not usually display the epoch unless it is essential -(non-zero, or if the <var/upstream-version/ contains a colon); -<prgn/dselect/ does not display epochs at all in the main part of the -package selection display. - -<tag><var/upstream-version/ -<item> - -This is the main part of the version. It is usually version number of -the original (`upstream') package of which the <tt/.deb/ file has been -made, if this is applicable. Usually this will be in the same format -as that specified by the upstream author(s); however, it may need to -be reformatted to fit into <prgn/dpkg/'s format and comparison scheme. -<p> - -The comparison behaviour of <prgn/dpkg/ with respect to the -<var/upstream-version/ is described below. The <var/upstream-version/ -portion of the version number is mandatory. -<p> - -The <var/upstream-version/ may contain only alphanumerics and the -characters <tt/+/ <tt/./ <tt/-/ <tt/:/ (full stop, plus, hyphen, -colon) and should start with a digit. If there is no -<var/debian-revision/ then hyphens are not allowed; if there is no -<var/epoch/ then colons are not allowed. - -<tag><var/debian-revision/ -<item> - -This part of the version represents the version of the modifications -that were made to the package to make it a Debian binary package. It -is in the same format as the <var/upstream-version/ and <prgn/dpkg/ -compares it in the same way. -<p> - -It is optional; if it isn't present then the <var/upstream-version/ -may not contain a hyphen. This format represents the case where a -piece of software was written specifically to be turned into a Debian -binary package, and so there is only one `debianization' of it and -therefore no revision indication is required. -<p> - -It is conventional to restart the <var/debian-revision/ at <tt/1/ each -time the <var/upstream-version/ is increased. -<p> - -<prgn/dpkg/ will break the <var/upstream-version/ and -<var/debian-revision/ apart at the last hyphen in the string. The -absence of a <var/debian-revision/ compares earlier than the presence -of one (but note that the <var/debian-revision/ is the least -significant part of the version number). -<p> - -The <var/debian-revision/ may contain only alphanumerics and the -characters <tt/+/ and <tt/./ (plus and full stop). - -</taglist> - -The <var/upstream-version/ and <var/debian-revision/ parts are -compared by <prgn/dpkg/ using the same algorithm: -<p> - -The strings are compared from left to right. -<p> - -First the initial part of each string consisting entirely of non-digit -characters is determined. These two parts (one of which may be empty) -are compared lexically. If a difference is found it is returned. The -lexical comparison is a comparison of ASCII values modified so that -all the letters sort earlier than all the non-letters. -<p> - -Then the initial part of the remainder of each string which consists -entirely of digit characters is determined. The numerical values of -these two parts are compared, and any difference found is returned as -the result of the comparison. For these purposes an empty string -(which can only occur at the end of one or both version strings being -compared) counts as zero. -<p> - -These two steps are repeated (chopping initial non-digit strings and -initial digit strings off from the start) until a difference is found -or both strings are exhausted. -<p> - -Note that the purpose of epochs is to allow us to leave behind -mistakes in version numbering, and to cope with situations where the -version numbering changes. It is <em/not/ there to cope with version -numbers containing strings of letters which <prgn/dpkg/ cannot interpret -(such as <tt/ALPHA/ or <tt/pre-/), or with silly orderings (the author -of this manual has heard of a package whose versions went <tt/1.1/, -<tt/1.2/, <tt/1.3/, <tt/1/, <tt/2.1/, <tt/2.2/, <tt/2/ and so forth). -<p> - -If an upstream package has problematic version numbers they should be -converted to a sane form for use in the <tt/Version/ field. -<p> - -If you need to compare version numbers ina script, you may use -<tt>dpkg --compare-versions ...</>. Type <tt>dpkg --help</> --> ---for details on arguments. - -<chapt id="maintainerscripts">Package maintainer scripts -and installation procedure -<sect>Introduction to package maintainer scripts -<p> - -It is possible supply scripts as part of a package which <prgn/dpkg/ -will run for you when your package is installed, upgraded or removed. -<p> - -These scripts should be the files <tt/preinst/, <tt/postinst/, -<tt/prerm/ and <tt/postrm/ in the control area of the package. They -must be proper exectuable files; if they are scripts (which is -recommended) they must start with the usual <tt/#!/ convention. They -should be readable and executable to anyone, and not world-writeable. -<p> - -<prgn/dpkg/ looks at the exit status from these scripts. It is -important that they exit with a non-zero status if there is an error, -so that <prgn/dpkg/ can stop its processing. For shell scripts this -means that you <em/almost always/ need to use <tt/set -e/ (this is -usually true when writing shell scripts, in fact). It is also -important, of course, that they don't exit with a non-zero status if -everything went well. -<p> - -It is necessary for the error recovery procedures that the scripts be -idempotent: ie, invoking the same script several times in the same -situation should do no harm. If the first call failed, or aborted -half way through for some reason, the second call should merely do the -things that were left undone the first time, if any, and exit with a -success status. -<p> - -When a package is upgraded a combination of the scripts from the old -and new packages is called in amongst the other steps of the upgrade -procedure. If your scripts are going to be at all complicated you -need to be aware of this, and may need to check the arguments to your -scripts. -<p> - -Broadly speaking the <prgn/preinst/ is called before (a particular -version of) a package is installed, and the <prgn/postinst/ afterwards; -the <prgn/prerm/ before (a version of) a package is removed and the -<prgn/postrm/ afterwards. -<p> -<!-- - next paragraph by Guy Maor to close bug #2481 - --> - -Programs called from maintainer scripts should not normally have a -path prepended to them. Before installation is started <prgn/dpkg/ -checks to see if the programs <prgn/ldconfig/, -<prgn/start-stop-daemon/, <prgn/install-info/, and <prgn/update-rc.d/ -can be found via the <tt/PATH/ environment variable. Those programs, -and any other program that one would expect to on the <tt/PATH/, -should thus be invoked without an absolute pathname. Maintainer -scripts should also not reset the <tt/PATH/, though they might choose -to modify it by pre- or appending package-specific directories. These -considerations really apply to all shell scripts. - -<sect id="mscriptsinstact">Summary of ways maintainer scripts are called -<p> - -<list compact> -<item><var/new-preinst/ <tt/install/ -<item><var/new-preinst/ <tt/install/ <var/old-version/ -<item><var/new-preinst/ <tt/upgrade/ <var/old-version/ -<item><var/old-preinst/ <tt/abort-upgrade/ <var/new-version/ -</list> -<p> - -<list compact> -<item><var/postinst/ <tt/configure/ <var/most-recently-configured-version/ -<item><var/old-postinst/ <tt/abort-upgrade/ <var/new version/ -<item><var/conflictor's-postinst/ <tt/abort-remove/ - <tt/in-favour/ <var/package/ <var/new-version/ -<item><var/deconfigured's-postinst/ <tt/abort-deconfigure/ - <tt/in-favour/ <var/failed-install-package/ <var/version/ - <tt/removing/ <var/conflicting-package/ <var/version/ -</list> -<p> - -<list compact> -<item><var/prerm/ <tt/remove/ -<item><var/old-prerm/ <tt/upgrade/ <var/new-version/ -<item><var/new-prerm/ <tt/failed-upgrade/ <var/old-version/ -<item><var/conflictor's-prerm/ <tt/remove/ <tt/in-favour/ - <var/package/ <var/new-version/ -<item><var/deconfigured's-prerm/ <tt/deconfigure/ - <tt/in-favour/ <var/package-being-installed/ <var/version/ - <tt/removing/ <var/conflicting-package/ <var/version/ -</list> -<p> - -<list compact> -<item><var/postrm/ <tt/remove/ -<item><var/postrm/ <tt/purge/ -<item><var/old-postrm/ <tt/upgrade/ <var/new-version/ -<item><var/new-postrm/ <tt/failed-upgrade/ <var/old-version/ -<item><var/new-postrm/ <tt/abort-install/ -<item><var/new-postrm/ <tt/abort-install/ <var/old-version/ -<item><var/new-postrm/ <tt/abort-upgrade/ <var/old-version/ -<item><var/disappearer's-postrm/ <tt/disappear/ <var/overwriter/ <var/new-version/ -</list> - - -<sect id="unpackphase">Details of unpack phase of installation or upgrade -<p> - -The procedure on installation/upgrade/overwrite/disappear (ie, when -running <tt/dpkg --unpack/, or the unpack stage of <tt/dpkg ---install/) is as follows. In each case if an error occurs the -actions in are general run backwards - this means that the maintainer -scripts are run with different arguments in reverse order. These are -the `error unwind' calls listed below. - -<enumlist> -<item> - -<enumlist> -<item> -If a version the package is already -installed, call -<example> -<var/old-prerm/ upgrade <var/new-version/ -</example> - -<item> -If this gives an error (ie, a non-zero exit status), dpkg will -attempt instead: -<example> -<var/new-prerm/ failed-upgrade <var/old-version/ -</example> -Error unwind, for both the above cases: -<example> -<var/old-postinst/ abort-upgrade <var/new-version/ -</example> - -</enumlist> - -<item> -If a `conflicting' package is being removed at the same time: -<enumlist> - -<item> -If any packages depended on that conflicting package and -<tt/--auto-deconfigure/ is specified, call, for each such package: -<example> -<var/deconfigured's-prerm/ deconfigure \ - in-favour <var/package-being-installed/ <var/version/ \ - removing <var/conflicting-package/ <var/version/ -</example> -Error unwind: -<example> -<var/deconfigured's-postinst/ abort-deconfigure \ - in-favour <var/package-being-installed-but-failed/ <var/version/ \ - removing <var/conflicting-package/ <var/version/ -</example> -The deconfigured packages are marked as requiring configuration, so -that if <tt/--install/ is used they will be configured again if -possible. - -<item> -To prepare for removal of the conflicting package, call: -<example> -<var/conflictor's-prerm/ remove in-favour <var/package/ <var/new-version/ -</example> -Error unwind: -<example> -<var/conflictor's-postinst/ abort-remove \ - in-favour <var/package/ <var/new-version/ -</example> - -</enumlist> - -<item> -<enumlist> -<item> -If the package is being upgraded, call: -<example> -<var/new-preinst/ upgrade <var/old-version/ -</example> - -<item> -Otherwise, if the package had some configuration files from a previous -version installed (ie, it is in the `configuration files only' state): -<example> -<var/new-preinst/ install <var/old-version/ -</example> - -<item> -Otherwise (ie, the package was completely purged): -<example> -<var/new-preinst/ install -</example> -Error unwind versions, respectively: -<example> -<var/new-postrm/ abort-upgrade <var/old-version/ -<var/new-postrm/ abort-install <var/old-version/ -<var/new-postrm/ abort-install -</example> - -</enumlist> - -<item> -The new package's files are unpacked, overwriting any that may be on -the system already, for example any from the old version of the same -package or from another package (backups of the old files are left -around, and if anything goes wrong dpkg will attempt to put them back -as part of the error unwind). -<p> - -It is an error for a package to contains files which are on the system -in another package, unless <tt/Replaces/ is used (see -<ref id="replaces">). Currently the <tt/--force-overwrite/ flag is -enabled, downgrading it to a warning, but this may not always be the -case. -<p> - -It is a more serious error for a package to contain a plain file or -other kind of nondirectory where another package has a directory -(again, unless <tt/Replaces/ is used). This error can be overridden -if desired using <tt/--force-overwrite-dir/, but this is not advisable. -<p> - -Packages which overwrite each other's files produce behaviour which -though deterministic is hard for the system administrator to -understand. It can easily lead to `missing' programs if, for example, -a package is installed which overwrites a file from another package, -and is then removed again.<footnote>Part of the problem is due to what -is arguably a bug in <prgn/dpkg/.</footnote> -<p> - -A directory will never be replaced by a symbolic links to a directory -or vice versa; instead, the existing state (symlink or not) will be -left alone and <prgn/dpkg/ will follow the symlink if there is one. - -<item> - -<enumlist> -<item> -If the package is being upgraded, call -<example> -<var/old-postrm/ upgrade <var/new-version/ -</example> - -<item> -If this fails, <prgn/dpkg/ will attempt: -<example> -<var/new-postrm/ failed-upgrade <var/old-version/ -</example> -Error unwind, for both cases: -<example> -<var/old-preinst/ abort-upgrade <var/new-version/ -</example> - -</enumlist> - -This is the point of no return - if <prgn/dpkg/ gets this far, it won't -back off past this point if an error occurs. This will leave the -package in a fairly bad state, which will require a successful -reinstallation to clear up, but it's when <prgn/dpkg/ starts doing -things that are irreversible. - -<item> -Any files which were in the old version of the package but not in the -new are removed. - -<item> -The new file list replaces the old. - -<item> -The new maintainer scripts replace the old. - -<item> -Any packages all of whose files have been overwritten during the -installation, and which aren't required for dependencies, are considered -to have been removed. For each such package, - -<enumlist> -<item> -<prgn/dpkg/ calls: -<example> -<var/disappearer's-postrm/ disappear \ - <var/overwriter/ <var/overwriter-version/ -</example> - -<item> -The package's maintainer scripts are removed. - -<item> -It is noted in the status database as being in a sane state, namely -not installed (any conffiles it may have are ignored, rather than -being removed by <prgn/dpkg/). Note that disappearing packages do not -have their prerm called, because <prgn/dpkg/ doesn't know in advance -that the package is going to vanish. - -</enumlist> - -<item> -Any files in the package we're unpacking that are also listed in the -file lists of other packages are removed from those lists. (This will -lobotomise the file list of the `conflicting' package if there is one.) - -<item> -The backup files made during installation, above, are deleted. - -<item> -The new package's status is now sane, and recorded as `unpacked'. Here -is another point of no return - if the conflicting package's removal -fails we do not unwind the rest of the installation; the conflicting -package is left in a half-removed limbo. - -<item> -If there was a conflicting package we go and do the removal actions -(described below), starting with the removal of the conflicting -package's files (any that are also in the package being installed -have already been removed from the conflicting package's file list, -and so do not get removed now). - -</enumlist> - -<sect>Details of configuration -<p> - -When we configure a package (this happens with <tt/dpkg --install/, or -with <tt/--configure/), we first update the conffiles and then call: -<example> -<var/postinst/ configure <var/most-recently-configured-version/ +<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: 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 also documents the interface + between <prgn>dselect</prgn> and its access method scripts. + 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. + + <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 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> -<p> - -No attempt is made to unwind after errors during configuration. -<p> - -If there is no most recently configured version <prgn/dpkg/ will pass a -null argument; older versions of dpkg may pass -<tt><unknown></tt> (including the angle brackets) in this case. -Even older ones do not pass a second argument at all, under any -circumstances. - -<sect>Details of removal and/or configuration purging -<p> - -<enumlist> -<item> + To view the copyright file for a package you could use this command: <example> -<var/prerm/ remove -</example> +dpkg --fsys-tarfile <var>filename</var>.deb | tar xof usr/doc/<var>\*</var>copyright | less +</example></p> + + <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 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: + <example> + dpkg-gencontrol + </example> + </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> + 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 executable(s) 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> + </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><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> + </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="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> (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="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 fields 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>t</tt>t> <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 CPU 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> + The current build architecture can be determined using <tt>dpkg + --print-architecture</tt>. + <footnote> + <p> + This actually invokes + <example> + gcc --print-libgcc-file-name + </example> and parses and decomposes the output and + looks the CPU type from the GCC configuration in a + table in <prgn>dpkg</prgn>. This is so that it will + work if you're cross-compiling. + </p> + </footnote> This value is automatically used by + <prgn>dpkg-gencontrol</prgn> when building the control + file for a binary package for which the source control + information doesn't specify architecture <tt>all</tt>. + </p> + + <p> + There is a separate option, + <tt>--print-installation-architecture</tt>, for finding + out what architecture <prgn>dpkg</prgn> is willing to + install. This information is also in the output of + <tt>dpkg --version</tt>.</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-genchanges</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 minor version number is increased + (for example: 1.2 becomes 1.2.1 then 1.2.2, 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> + </chapt> + + <chapt id="maintainerscripts"><heading>Package maintainer scripts + and installation procedure + </heading> + + <sect><heading>Introduction to package maintainer scripts + </heading> + + <p> + It is possible 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>r>overwrit</var>r> + <var>new-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> + + <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> + and <tt>Pre-Depends</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> + </sect> + + <sect><heading>Dependencies - <tt>Depends</tt>, <tt>Recommends</tt>, + <tt>tt>Sugge</tt>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 be 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 packages - + <tt>tt>Confli</tt>tt> and <tt>Replaces</tt> + </heading> + + <p> + When one 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. + </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>Recommends</tt>, <tt>Suggests</tt> and + <tt>Conflicts</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 were 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 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 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> + </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 - ie, + if the user edits their file, but the package maintainer + doesn't ship a different version, the user's changes will + stay, silently, but if the maintainer ships a new version + and the user hasn't edited it the new version will be + installed (with an informative message). If both have + changed their version the user is prompted about the problem + and must resolve the differences themselves. + </p> + + <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" ]; 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, and <em>this + is very important</em>, 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. Currently the way to ensure the ordering is done + properly is to install the library in the appropriate + <tt>debian/tmp/.../lib</tt> directory before creating the + symlink, by putting the commands in the <tt>debian/rules</tt> + in the appropriate order. + </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> calls <prgn>ldd</prgn> to + determine the shared libraries used by the compiled + binaries passed through 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/*.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> -<item> -The package's files are removed (except conffiles). -<item> -<example> -<var/postrm/ remove -</example> -<item> -All the maintainer scripts except the postrm are removed. -<p> -If we aren't purging the package we stop here. Note that packages -which have no postrm and no conffiles are automatically purged when -removed, as there is no difference except for the <prgn/dpkg/ status. -<item> -The conffiles and any backup files (<tt/~/-files, <tt/#*#/ files, -<tt/%/-files, <tt/.dpkg-{old,new,tmp}/, etc.) are removed. -<item> -<example> -<var/postrm/ purge -</example> -<item> -The package's file list is removed. -</enumlist> -No attempt is made to unwind after errors during removal. -<chapt id="descriptions">Descriptions of packages - the -<tt/Description/ field -<p> -The <tt/Description/ control file field is used by <prgn/dselect/ when -the user is selecting which packages to install and by <prgn/dpkg/ -when it displays information about the status of packages and so -forth. It is included on the FTP site in the <prgn/Packages/ files, -and may also be used by the Debian WWW pages. -<p> -The description is intended to describe the program to a user who has -never met it before so that they know whether they want to install it. -It should also give information about the significant dependencies and -conflicts between this package and others, so that the user knows why -these dependencies and conflicts have been declared. -<p> -The field's format is as follows: -<example> -Description: <var/single line synopsis/ - <var/extended description over several lines/ -</example> -<p> - -The synopsis is often printed in lists of packages and so forth, and -should be as informative as possible. Every package should also have -an extended description. -<p> - -<sect>Types of formatting line in the extended description -<p> - -<list> -<item> -Those starting with a single space are part of a paragraph. -Successive lines of this form will be word-wrapped when displayed. -The leading space will usually be stripped off. - -<item> -Those starting with two or more spaces. These will be displayed -verbatim. If the display cannot be panned horizontally the -displaying program will linewrap them `hard' (ie, without taking -account of word breaks). If it can they will be allowed to trail -off to the right. None, one or two initial spaces may be deleted, -but the number of spaces deleted from each line will be the same -(so that you can have indenting work correctly, for example). - -<item> -Those containing a single space followed by a single full stop -character. These are rendered as blank lines. This is the <em/only/ -way to get a blank line - see below. - -<item> -Those containing a space, a full stop and some more characters. These -are for future expansion. Do not use them. -</list> - -<sect>Notes about writing descriptions -<p> - -<em/Always/ start extended description lines with at least one -whitespace character. Fields in the control file and in the Packages -file are separated by field names starting in the first column, just -as message header fields are in RFC822. Forgetting the whitespace -will cause <prgn/dpkg-deb/<footnote>Version 0.93.23 or -later.</footnote> to produce a syntax error when trying to build the -package. If you force it to build anyway <prgn/dpkg/ will refuse to -install the resulting mess. -<p> - -<em/Do not/ include any completely <em/empty/ lines. These separate -different records in the Packages file and different packages in the -<tt>debian/control</> file, and are forbidden in package control -files. See the previous paragraph for what happens if you get this -wrong. -<p> - -The single line synopsis should be kept brief - certainly under 80 -characters. <prgn/dselect/ displays between 25 and 49 characters -without panning if you're using an 80-column terminal, depending on -what display options are in effect. -<p> - -Do not include the package name in the synopsis line. The display -software knows how to display this already, and you do not need to -state it. Remember that in many situations the user may only see -the synopsis line - make it as informative as you can. -<p> - -The extended description should describe what the package does and -how it relates to the rest of the system (in terms of, for -example, which subsystem it is which part of). -<p> - -The blurb that comes with a program in its announcements and/or -<prgn/README/ files is rarely suitable for use in a description. It -is usually aimed at people who are already in the community where the -package is used. The description field needs to make sense to anyone, -even people who have no idea about any of the -things the package deals with. -<p> - -Put important information first, both in the synopis and extended -description. Sometimes only the first part of the synopsis or of -the description will be displayed. You can assume that there will -usually be a way to see the whole extended description. -<p> - -You may include information about dependencies and so forth in the -extended description, if you wish. -<p> - -Do not use tab characters. Their effect is not predictable. -<p> - -Do not try to linewrap the summary (the part on the same line as the -field name <tt/Description/) into the extended description. This will -not work correctly when the full description is displayed, and makes -no sense where only the summary is available. - -<sect>Example description in control file for Smail -<p> -<example> -Package: smail -Version: 3.1.29.1-13 -Maintainer: Ian Jackson <iwj10@cus.cam.ac.uk> -Recommends: pine | mailx | elm | emacs | mail-user-agent -Suggests: metamail -Depends: cron, libc5 -Conflicts: sendmail -Provides: mail-transport-agent -Description: Electronic mail transport system. - Smail is the recommended mail transport agent (MTA) for Debian. - . - An MTA is the innards of the mail system - it takes messages from - user-friendly mailer programs and arranges for them to be delivered - locally or passed on to other systems as required. - . - In order to make use of it you must have one or more user level - mailreader programs such as elm, pine, mailx or Emacs (which has Rmail - and VM as mailreaders) installed. If you wish to send messages other - than just to other users of your system you must also have appropriate - networking support, in the form of IP or UUCP. -</example> -<chapt id="relationships">Declaring relationships between packages -<p> - -Packages can declare in their control file that they have certain -relationships to other packages - for example, that they may not be -installed at the same time as certain other packages, and/or that they -depend on the presence of others, or that they should overwrite files -in certain other packages if present. -<p> - -This is done using the <tt/Depends/, <tt/Recommends/, <tt/Suggests/, -<tt/Conflicts/, <tt/Provides/ and <tt/Replaces/ control file fields. -<p> - -<sect id="depsyntax">Syntax of relationship fields -<p> - -These fields all have a uniform syntax. They are a list of package -names separated by commas. -<p> - -In <tt/Depends/, <tt/Recommends/, <tt/Suggests/ and <tt/Pre-Depends/ -(the fields which declare dependencies of the package in which they -occur on other packages) these package names may also be lists of -alternative package names, separated by vertical bar symbols <tt/|/ -(pipe symbols). -<p> - -All the fields except <tt/Provides/ may restrict their applicability -to particular versions of each named package. This is done in -parentheses after each individual package name; the parentheses should -contain a relation from the list below followed by a version number, -in the format described in <ref id="versions">. -<p> - -The relations allowed are -<tt/<</, -<tt/<=/, -<tt/=/, -<tt/>=/ and -<tt/>>/ -for strictly earlier, earlier or equal, exactly equal, later or equal -and strictly later, respectively. The forms <tt/</ and <tt/>/ -were used to mean earlier/later or equal, rather than strictly -earlier/later, so they should not appear in new packages (though -<prgn/dpkg/ still supports them). -<p> - -Whitespace may appear at any point in the version specification, and -must appear where it's necessary to disambiguate; it is not otherwise -significant. For consistency and in case of future changes to -<prgn/dpkg/ it is recommended that a single space be used after a -version relationship and before a version number; it is usual also to -put a single space after each comma, on either side of each vertical -bar, and before each open parenthesis. -<p> - -For example: -<example> -Package: metamail -Version: 2.7-3 -Depends: libc5 (>= 5.2.18-4), mime-support, csh | tcsh -</example> -<sect>Dependencies - <tt/Depends/, <tt/Recommends/, <tt/Suggests/, <tt/Pre-Depends/ -<p> - -These four fields are used to declare a dependency by one package on -another. They appear in the depending package's control file. -<p> - -All but <tt/Pre-Depends/ (discussed below) take effect <em/only/ when -a package is to be configured. They do not prevent a package being on -the system in an unconfigured state while its dependencies are -unsatisfied, and it is possible to replace a package whose -dependencies are satisfied and which is properly installed with a -different version whose dependencies are not and cannot be satisfied; -when this is done the depending package will be left unconfigured -(since attempts to configure it will give errors) and will not -function properly. -<p> - -For this reason packages in an installation run are usually all -unpacked first and all configured later; this gives later versions of -packages with dependencies on later versions of other packages the -opportunity to have their dependencies satisfied. -<p> - -Thus <tt/Depends/ allows package maintainers to impose an order in -which packages should be configured. - -<taglist> -<tag><tt/Depends/ -<item> - -This declares an absolute dependency. -<p> - -<prgn/dpkg/ will not configure -packages whose dependencies aren't satisfied. If it is asked to make -an installation which would cause an installed package's dependencies -to become unsatisfied it will complain<footnote>Current versions -(1.2.4) of <prgn/dpkg/ have a bug in this area which will cause some of -these problems to be ignored.</footnote>, unless -<tt/--auto-deconfigure/ is specified, in which case those packages -will be deconfigured before the installation proceeds. -<p> - -<prgn/dselect/ makes it hard for the user to select packages for -installation, removal or upgrade in a way that would mean that -packages' <prgn/Depends/ fields would be unsatisfied. The user can -override this if they wish, for example if they know that <prgn/dselect/ -has an out-of-date view of the real package relationships. -<p> - -The <tt/Depends/ field should be used if the depended-on package is -required for the depending package to provide a significant amount of -functionality. - -<tag><tt/Recommends/ -<item> -This declares a strong, but not absolute, dependency. -<p> - -<tt/Recommends/ is ignored by <prgn/dpkg/, so that users using the -command-line (who are presumed to know what they're doing) will not be -impeded. -<p> - -It is treated by <prgn/dselect/ exactly as <tt/Depends/ is; this makes -it hard for the user to select things so as to leave <tt/Recommends/ -fields unsatisfied, but they are able to do so by being persistent. -<p> - -The <tt/Recommends/ field should list packages that would be found -together with this one in all but unusual installations. - -<tag><tt/Suggests/ -<item> - -This is used to declare that one package may be more useful with one -or more others. Using this field tells the packaging system and the -user that the listed packages are be related to this one and can -perhaps enhance its usefulness, but that installing this one without -them is perfectly reasonable. -<p> - -<prgn/dselect/ will offer suggsted packages to the system administrator -when they select the suggesting package, but the default is not to -install the suggested package. - -<tag><tt/Pre-Depends/ -<item> - -This field is like <tt/Depends/, except that it also forces <prgn/dpkg/ -to complete installation of the packages named before even starting -the installation of the package which declares the predependency. -<p> - -<prgn/dselect/ checks for predependencies when it is doing an -installation run, and will attempt to find the packages which are -required to be installed first and do so in the right order. -<p> - -However, this process is slow (because it requires repeated -invocations of <prgn/dpkg/) and troublesome (because it requires -guessing where to find the appropriate files). -<p> - -For these reasons, and because this field imposes restrictions on the -order in which packages may be unpacked (which can be difficult for -installations from multipart media, for example), <tt/Pre-Depends/ -should be used sparingly, preferably only by packages whose premature -upgrade or installation would hamper the ability of the system to -continue with any upgrade that might be in progress. -<p> - -When the package declaring it is being configured, a -<tt/Pre-Dependency/ will be considered satisfied only if the depending -package has been correctly configured, just as if an ordinary -<tt/Depends/ had been used. -<p> - -However, when a package declaring a predependency is being unpacked -the predependency can be satisfied even if the depended-on package(s) -are only unpacked or half-configured, provided that they have been -configured correctly at some point in the past (and not removed or -partially removed since). In this case both the previously-configured -and currently unpacked or half-configured versions must satisfy any -version clause in the <tt/Pre-Depends/ field. - -</taglist> - -When selecting which level of dependency to use you should consider -how important the depended-on package is to the functionality of the -one declaring the dependency. Some packages are composed of -components of varying degrees of importance. Such a package should -list using <tt/Depends/ the package(s) which are required by the more -important components. The other components' requirements may be -mentioned as Suggestions or Recommendations, as appropriate to the -components' relative importance. - -<sect1>Dependencies on shared libraries -<p> - -The dependency fields listed above are used by packages which need -shared libraries to declare dependencies on the appropriate packages. -<p> - -These dependencies are usually determined automatically using -<prgn/dpkg-shlibdeps/ and inserted in the package control file using -the control file substitution variables mechanism; see <ref -id="srcsubstvars"> and <ref id="sourcetools">. - -<sect1>Deconfiguration due to removal during bulk installations -<p> - -If <prgn/dpkg/ would like to remove a package due to a conflict, as -described above, but this would violate a dependency of some other -package on the system, <prgn/dpkg/ will usually not remove the -conflicting package and halt with an error. -<p> - -However, if the <tt/--auto-deconfigure/ (<tt/-B/) option is used -<prgn/dpkg/ will automatically `deconfigure' the package with the -problematic dependency, so that the conflicting package can be removed -and the package we're trying to install can be installed. If -<prgn/dpkg/ is being asked to install packages (rather than just -unpacking them) it will try to reconfigure the package when it has -unpacked all its arguments, in the hope that one of the other packages -it is installing will satisfy the problematic dependency. -<p> - -<prgn/dselect/ supplies this argument to <prgn/dpkg/ when it invokes it, -so that bulk installations proceed smoothly. - -<sect id="conflicts">Alternative packages - <tt/Conflicts/ and <tt/Replaces/ -<p> - -When one package declares a conflict with another <prgn/dpkg/ will -refuse to allow them to be installed on the system at the same time. -<p> - -If one package is to be installed, the other must be removed first - -if the package being installed is marked as replacing (<ref -id="replaces">) the one on the system, or the one on the system is -marked as deselected, or both packages are marked <tt/Essential/, then -<prgn/dpkg/ will automatically remove the package which is causing the -conflict, otherwise it will halt the installation of the new package -with an error. -<p> - -<prgn/dselect/ makes it hard to select conflicting packages, though the -user can override this if they wish. If they do not override it then -<prgn/dselect/ will select one of the packages for removal, and the user -must make sure it is the right one. In the future <prgn/dselect/ will -look for the presence of a <tt/Replaces/ field to help decide which -package should be installed and which removed. -<p> - -A package will not cause a conflict merely because its configuration -files are still installed; it must be at least half-installed. -<p> - -A special exception is made for packages which declare a conflict with -their own package name, or with a virtual package which they provide -(see below): this does not prevent their installation, and allows a -package to conflict with others providing a replacement for it. You -use this feature when you want the package in question to be the only -package providing something. -<p> - -A <tt/Conflicts/ entry should almost never have an `earlier than' -version clause. This would prevent <prgn/dpkg/ from upgrading or -installing the package which declared such a conflict until the -upgrade or removal of the conflicted-with package had been completed. -This aspect of installation ordering is not handled by <prgn/dselect/, -so that the use <tt/Conflicts/ in this way is likely to cause problems -for `bulk run' upgrades and installations. -<p> - - -<sect id="virtual">Virtual packages - <tt/Provides/ -<p> - -As well as the names of actual (`concrete') packages, the package -relationship fields <tt/Depends/, <tt/Recommends/, <tt/Suggests/ and -<tt/Conflicts/ may mention virtual packages. -<p> - -A virtual package is one which appears in the <tt/Provides/ control -file field of another package. The effect is as if the package(s) -which provide a particular virtual package name had been listed by -name everywhere were the virtual package name appears. -<p> - -If there are both a real and a virtual package of the same name then -the dependency may be satisfied (or the conflict caused) by either the -real package or any of the virtual packages which provide it. This is -so that, for example, supposing we have -<example> -Package: vm -Depends: emacs -</example> -and someone else releases an xemacs package they can say -<example> -Package: xemacs -Provides: emacs -</example> -and all will work in the interim (until a purely virtual package name -is decided on and the <tt/emacs/ and <tt/vm/ packages are changed to -use it). -<p> - -If a dependency or a conflict has a version number attached then only -real packages will be considered to see whether the relationship is -satisfied (or the prohibition violated, for a conflict) - it is -assumed that a real package which provides virtual package is not of -the `right' version. So, a <tt/Provides/ field may not contain -version numbers, and the version number of the concrete package which -provides a particular virtual package will not be looked at when -considering a dependency on or conflict with the virtual package name. -<p> - -It is likely that the ability will be added in a future release of -<prgn/dpkg/ to specify a version number for each virtual package it -provides. This feature is not yet present, however, and is expected -to be used only infrequently. -<p> - -If you want to specify which of a set of real packages should be the -default to satisfy a particular dependency on a virtual package, you -should list the real package as alternative before the virtual. -<p> - - -<sect id="replaces"><tt/Replaces/ - overwriting files and replacing packages -<p> - -The <tt/Replaces/ control file field has two purposes, which come into -play in different situations. -<p> - -Virtual packages (<ref id="virtual">) are not considered when looking -at a <tt/Replaces/ field - the packages declared as being replaced -must be mentioned by their real names. - -<sect1>Overwriting files in other packages -<p> - -Firstly, as mentioned before, it is usually an error for a package to -contains files which are on the system in another package, though -currently the <tt/--force-overwrite/ flag is enabled by default, -downgrading the error to a warning, -<p> - -If the overwriting package declares that it replaces the one -containing the file being overwritten then <prgn/dpkg/ will proceed, and -replace the file from the old package with that from the new. The -file will no longer be listed as `owned' by the old package. -<p> - -If a package is completely replaced in this way, so that <prgn/dpkg/ -does not know of any files it still contains, it is considered to have -disappeared. It will be marked as not wanted on the system (selected -for removal) and not installed. Any conffiles details noted in the -package will be ignored, as they will have been taken over by the -replacing package(s). The package's <prgn/postrm/ script will be run to -allow the package to do any final cleanup required. -See <ref id="mscriptsinstact">. -<p> - -In the future <prgn/dpkg/ will discard files which overwrite those from -another package which declares that it replaces the one being -installed (so that you can install an older version of a package -without problems). -<p> - -This usage of <tt/Replaces/ only takes effect when both packages are -at least partially on the system at once, so that it can only happen -if they do not conflict or if the conflict has been overridden. - -<sect1>Replacing whole packages, forcing their removal -<p> - -Secondly, <tt/Replaces/ allows <prgn/dpkg/ and <prgn/dselect/ to resolve -which package should be removed when a conflict - see -<ref id="conflicts">. This usage only takes effect when the two -packages <em/do/ conflict, so that the two effects do not interfere -with each other. -<p> - -<sect>Defaults for satisfying dependencies - ordering -<p> - -Ordering is significant in dependency fields. -<p> - -Usually dselect will suggest to the user that they select the package -with the most `fundamental' class (eg, it will prefer Base packages to -Optional ones), or the one that they `most wanted' to select in some -sense. -<p> - -In the absence of other information <prgn/dselect/ will offer a -default selection of the first named package in a list of -alternatives. -<p> - -However, there is no way to specify the `order' of several packages -which all provide the same thing, when that thing is listed as a -dependency. -<p> - -Therefore a dependency on a virtual package should contain a concrete -package name as the first alternative, so that this is the default. -<p> - -For example, consider the set of packages: -<example> -Package: glibcdoc -Recommends: info-browser -Package: info -Provides: info-browser -Package: emacs -Provides: info-browser -</example> -<p> -If <prgn/emacs/ and <prgn/info/ both have the same priority then -<prgn/dselect/'s choice is essentially random. Better would be -<example> -Package: glibcdoc -Recommends: info | info-browser -</example> -so that <prgn/dselect/ defaults to selecting the lightweight standalone -info browser. - - - -<chapt id="conffiles">Configuration file handling -<p> - -<prgn/dpkg/ can do a certain amount of automatic handling of package -configuration files. -<p> - -Whether this mechanism is appropriate depends on a number of factors, -but basically there are two approaches to any particular configuration -file. -<p> - -The easy method is to ship a best-effort configuration in the package, -and use <prgn/dpkg/'s conffile mechanism to handle updates. If the user -is unlikely to want to edit the file, but you need them to be able to -without losing their changes, and a new package with a changed version -of the file is only released infrequently, this is a good approach. -<p> - -The hard method is to build the configuration file from scratch in the -<prgn/postinst/ script, and to take the responsibility for fixing any -mistakes made in earlier versions of the package automatically. This -will be appropriate if the file is likely to need to be different on -each system. - -<sect>Automatic handling of configuration files by <prgn/dpkg/ -<p> - -A package may contain a control area file called <tt/conffiles/. This -file should be a list of filenames of configuration files needing -automatic handling, separated by newlines. The filenames should be -absolute pathnames, and the files referred to should actually exist in -the package. -<p> - -When a package is upgraded <prgn/dpkg/ will process the configuration -files during the configuration stage, shortly before it runs the -package's <prgn/postinst/ script, -<p> - -For each file it checks to see whether the version of the file -included in the package is the same as the one that was included in -the last version of the package (the one that is being upgraded -from); it also compares the version currently installed on the system -with the one shipped with the last version. -<p> - -If neither the user nor the package maintainer has changed the file, -it is left alone. If one or the other has changed their version, then -the changed version is preferred - ie, if the user edits their file, -but the package maintainer doesn't ship a different version, the -user's changes will stay, silently, but if the maintainer ships a new -version and the user hasn't edited it the new version will be -installed (with an informative message). If both have changed their -version the user is prompted about the problem and must resolve the -differences themselves. -<p> - -The comparisons are done by calculating the MD5 message digests of the -files, and storing the MD5 of the file as it was included in the most -recent version of the package. -<p> - -When a package is installed for the first time <prgn/dpkg/ will install -the file that comes with it, unless that would mean overwriting a file -already on the filesystem. -<p> - -However, note that <prgn/dpkg/ will <em/not/ replace a conffile that -was removed by the user (or by a script). This is necessary because -with some programs a missing file produces an effect hard or -impossible to achieve in another way, so that a missing file needs to -be kept that way if the user did it. -<p> - -Note that a package should <em/not/ modify a <prgn/dpkg/-handled -conffile in its maintainer scripts. Doing this will lead to -<prgn/dpkg/ giving the user confusing and possibly dangerous options -for conffile update when the package is upgraded. - -<sect>Fully-featured maintainer script configuration handling -<p> - -For files which contain site-specific information such as the hostname -and networking details and so forth, it is better to create the file -in the package's <prgn/postinst/ script. -<p> - -This will typically involve examining the state of the rest of the -system to determine values and other information, and may involve -prompting the user for some information which can't be obtained some -other way. -<p> - -When using this method there are a couple of important issues which -should be considered: -<p> - -If you discover a bug in the program which generates the configuration -file, or if the format of the file changes from one version to the -next, you will have to arrange for the postinst script to do something -sensible - usually this will mean editing the installed configuration -file to remove the problem or change the syntax. You will have to do -this very carefully, since the user may have changed the file, perhaps -to fix the very problem that your script is trying to deal with - you -will have to detect these situations and deal with them correctly. -<p> - -If you do go down this route it's probably a good idea to make the -program that generates the configuration file(s) a separate program in -<tt>/usr/sbin</>, by convention called <tt/<var/package/config/ and -then run that if appropriate from the post-installation script. The -<tt/<var/package/config/ program should not unquestioningly overwrite -an existing configuration - if its mode of operation is geared towards -setting up a package for the first time (rather than any arbitrary -reconfiguration later) you should have it check whether the -configuration already exists, and require a <tt/--force/ flag to -overwrite it. - - - -<chapt id="alternatives">Alternative versions of an interface - -<prgn/update-alternatives/ -<p> - -When several packages all provide different versions of the same -program or file it is useful to have the system select a default, but -to allow the system administrator to change it and have their -decisions respected. -<p> - -For example, there are several versions of the <prgn/vi/ editor, and -there is no reason to prevent all of them from being installed at -once, each under their own name (<prgn/nvi/, <prgn/vim/ or whatever). -Nevertheless it is desirable to have the name <tt/vi/ refer to -something, at least by default. -<p> - -If all the packages involved cooperate, this can be done with -<prgn/update-alternatives/. -<p> - -Each package provides its own version under its own name, and calls -<prgn/update-alternatives/ in its postinst to register its version -(and again in its prerm to deregister it). -<p> - -See the manpage <manref name=update-alternatives section=8> for -details. -<p> - -If <prgn/update-alternatives/ does not seem appropriate you may wish -to consider using diversions instead. - - -<chapt id="diversions">Diversions - overriding a package's version of a file -<p> - -It is possible to have <prgn/dpkg/ not overwrite a file when it -reinstalls the package it belongs to, and to have it put the file from -the package somewhere else instead. -<p> - -This can be used locally to override a package's version of a file, or -by one package to override another's version (or provide a wrapper for -it). -<p> - -Before deciding to use a diversion, read <ref id="alternatives"> to -see if you really want a diversion rather than several alternative -versions of a program. -<p> - -There is a diversion list, which is read by <prgn/dpkg/, and updated -by a special program <prgn/dpkg-divert/. Please see <manref -name=dpkg-divert section=8> for full details of its operation. -<p> - -When a package wishes to divert a file from another, it should call -<prgn/dpkg-divert/ in its preinst to add the diversion and rename the -existing file. For example, supposing that a <prgn/smailwrapper/ -package wishes to install a wrapper around <tt>/usr/sbin/smail</>: -<example> -if [ install = "$1" ]; then - dpkg-divert --package smailwrapper --add --rename \ - --divert /usr/sbin/smail.real /usr/sbin/smail -fi -</example> -Testing <tt/$1/ is necessary so that the script doesn't try to add the -diversion again when <prgn/smailwrapper/ is upgraded. The -<tt/--package smailwrapper/ ensures that <prgn/smailwrapper/'s copy of -<tt>/usr/sbin/smail</> can bypass the diversion and get installed as -the true version. -<p> - -The postrm has to do the reverse: -<example> -if [ remove = "$1" ]; then - dpkg-divert --package smailwrapper --remove --rename \ - --divert /usr/sbin/smail.real /usr/sbin/smail -fi -</example> -<p> - -Do not attempt to divert a file which is vitally important for the -system's operation - when using <prgn/dpkg-divert/ there is a time, -after it has been diverted but before <prgn/dpkg/ has installed the -new version, when the file does not exist. - - -<chapt id="sharedlibs">Shared libraries -<p> - -Packages containing shared libraries must be constructed with a little -care to make sure that the shared library is always available. This -is especially important for packages whose shared libraries are -vitally important, such as the libc. -<p> - -Firstly, your package should install the shared libraries under their -normal names. For example, the <prgn/libgdbm1/ package should install -<tt/libgdbm.so.1.7.3/ as <tt>/usr/lib/libgdbm.so.1.7.3</tt>. The -files should not be renamed or relinked by any prerm or postrm -scripts; <prgn/dpkg/ will take care of renaming things safely without -affecting running programs, and attempts to interfere with this are -likely to lead to problems. -<p> - -Secondly, your package should include the symlink that <prgn/ldconfig/ -would create for the shared libraries. For example, the -<prgn/libgdbm1/ package should include a symlink from -<tt>/usr/lib/libgdbm.so.1</tt> to <tt/libgdbm.so.1.7.3/. This is -needed so that <prgn/ld.so/ can find the library in between the time -<prgn/dpkg/ installs it and <prgn/ldconfig/ is run in the -<prgn/postinst/ script. Futhermore, and <em/this is very important/, -the library must be placed before the symlink pointing to it in the -<tt/.deb/ file. This is so that by the time <prgn/dpkg/ comes to -install the symlink (overwriting the previous symlink pointing at an -older version of the library) the new shared library is already in -place. Currently the way to ensure the ordering is done properly is -to install the library in the appropriate <tt>debian/tmp/.../lib</> -directory before creating the symlink, by putting the commands in the -<tt>debian/rules</> in the appropriate order. -<p> - -<!-- - next Paragraph added to close Bug #5299, Guy Maor - --> - -Thirdly, the development package should contain a symlink for the -shared library without a version number. For example, the -<tt/libgdbm1-dev/ package should include a symlink from -<tt>/usr/lib/libgdm.so</> to <tt/libgdm.so.1.7.3/. This symlink is -needed by <prgn/ld/ when compiling packages as it will only look for -<tt/libgdm.so/ and <tt/libgdm.a/ when compiling dynamically or -statically, respectively. -<p> - -<!-- - next paragraph changed by Christian Schwarz (see policy weekly #6) - --> - -Any package installing shared libraries in a directory that's listed -in <tt>/etc/ld.so.conf</tt> or in one of the default library -directories of <prgn/ld.so/ (currently, these are <tt>/usr/lib</tt> -and <tt>/lib</tt>) must call <prgn/ldconfig/ in its <prgn/postinst/ -script if and only if the first argument is `configure'. However, it -is important not to call <prgn/ldconfig/ in the postrm or preinst -scripts in the case where the package is being upgraded (see <ref -id="unpackphase">), as <prgn/ldconfig/ will see the temporary names -that <prgn/dpkg/ uses for the files while it is installing them and -will make the shared library links point to them, just before -<prgn/dpkg/ continues the installation and removes the links! -<p> - -<!-- - moved from section 2.2 , DMorris - --> - -<sect id="shlibs">The <tt/shlibs/ File Format -<p> - -This file is for use by <prgn/dpkg-shlibdeps/ and is required when -your package provides shared libraries. -<p> - -Each line is of the form: -<example> -<var/library-name/ <var/version-or-soname/ <var/dependencies .../ -</example> -<p> - -<var/library-name/ is the name of the shared library, for example -<tt/libc5/. -<p> - -<var/version-or-soname/ is the soname of the library - ie, the thing -that must exactly match for the library to be recognised by -<prgn/ld.so/. Usually this is major version number of the library. -<p> - -<var/dependencies/ has the same syntax as a dependency field in a -binary package control file. It should give details of which -package(s) are required to satisfy a binary built against the version -of the library contained in the package. See <ref id="depsyntax">. -<p> - -For example, if the package <tt/foo/ contains <tt/libfoo.so.1.2.3/, -where the soname of the library is <tt/libfoo.so.1/, and the first -version of the package which contained a minor number of at least -<tt/2.3/ was <var/1.2.3-1/, then the package's <var/shlibs/ could -say: -<example> -libfoo 1 foo (>= 1.2.3-1) -</example> -<p> - -The version-specific dependency is to avoid warnings from <prgn/ld.so/ -about using older shared libraries with newer binaries. - -<sect>Further Technical information on <tt/shlibs/</> - -<!-- - following section mostly provided by Heiko Schlittermann - edited by DMorris - --> - -<sect1><em/What/ are the <tt/shlibs/ files? -<p> - -The <tt>debian/shlibs</> file provides a way of checking -for shared library dependencies on packaged binaries. They are -intended to be used by package maintainers to make their lives easier. -<p> - -Other <tt/shlibs/ files that exist on a Debian system are -<list> -<item> <tt>/etc/dpkg/shlibs.default</> -<item> <tt>/etc/dpkg/shlibs.override</> -<item> <tt>/var/lib/dpkg/info/*.shlibs</> -<item> <tt>debian/shlibs.local</> -</list> - -These files are used by <prgn/dpkg-shlibdeps/ when creating a binary -package. - -<sect1><em/How/ does <prgn/dpkg-shlibdeps/ work? -<p> - -<prgn/dpkg-shlibdeps/ calls <prgn/ldd/ to determine the shared libraries -used by the compiled binaries passed through its command line. -<p> - -For each shared library, <prgn/dpkg-shlibdeps/ needs to know -<list compact> -<item>the package containing the library, and -<item>the library version number, -</list> -<p> -it scans the following files in this order. -<enumlist compact> -<item><tt>debian/shlibs.local</> -<item><tt>/etc/dpkg/shlibs.override</> -<item><tt>/var/lib/dpkg/info/*.shlibs</> -<item><tt>/etc/dpkg/shlibs.default</> -</enumlist> - -<sect1><em/Who/ maintains the various <tt/shlibs/ files? -<p> - -<list compact> -<item><tt>/etc/dpkg/shlibs.default</> - the maintainer of dpkg -<item><tt>/var/lib/dpkg/info/<var/package/.shlibs</> - the maintainer of each -package -<item><tt>/etc/dpkg/shlibs.override</> - the local system administrator -<item><tt>debian/shlibs.local</> - the maintainer of the package -</list> - -The <tt/shlibs.default/ file is managed by <prgn/dpkg/. The entries in -<tt/shlibs.default/ that are provided by <prgn/dpkg/ are just there to -fix things until the shared library packages all have <tt/shlibs/ -files. - -<sect1><em/How/ to use <prgn/dpkg-shlibdeps/ and the <tt/shlibs/ files? - -<sect2>If your package doesn't provide a shared library -<p> - -Put a call to <prgn/dpkg-shlibs/ into your <tt>debian/rules</> file. -If your package contains only binaries (e.g. no scripts) use: -<example> -dpkg-shlibdeps debian/tmp/usr/{bin,sbin}/* -</example> - -If <prgn/dpkg-shlibdeps/ doesn't complain, you're done. If it does -complain you might need to create your own <tt>debian/shlibs.local</> -file. - -<sect2>If your package provides a shared library -<p> - -Create a <tt>debian/shlibs</> file and let <tt>debian/rules</> install -it in the control area: - -<example> -install -m644 debian/shlibs debian/tmp/DEBIAN -</example> - -If your package contains additional binaries see above. - -<sect1><em/How/ to write <tt>debian/shlibs.local</> -<p> - -This file is intended only as a <em/temporary/ fix if your binaries -depend on a library which doesn't provide its own -<tt>/var/lib/dpkg/*.shlibs</> file yet. -<p> - -Let's assume you are packaging a binary <tt/foo/. Your output in -building the package might look like this. - -<example> -$ ldd foo -libbar.so.1 => /usr/X11R6/lib/libbar.so.1.0 -libc.so.5 => /lib/libc.so.5.2.18 -libX11.so.6 => /usr/X11R6/lib/libX11.so.6.0 -</example> - -And when you ran <prgn/dpkg-shlibdeps/ - -<example> -$ dpkg-shlibdeps -o foo -dpkg-shlibdeps: warning: unable to find dependency information -for shared library libbar -(soname 1, path /usr/X11R6/lib/libbar.so.1.0, dependency field Depends) -shlibs:Depends=elf-x11r6lib, libc5 (>= 5.2.18) -</example> - -The <prgn/foo/ binary depends on the <prgn/libbar/ shared library, but -no package seems to provide a <tt/*.shlibs/ file in -<tt//var/lib/dpkg/info/. Let's determine the package responsible: -<p> - -<example> -$ dpkg -S /usr/X11R6/lib/libbar.so.1.0 -bar1: /usr/X11R6/lib/libbar.so.1.0 -$ dpkg -s bar1 | grep Version -Version: 1.0-1 -</example> - -This tells us that the <prgn/bar1/ package, version 1.0-1 is the one -we are using. Now we can create our own <tt>debian/shlibs.local</> to -temporarly fix the above problem. Include the following line into your -<tt>debian/shlibs.local</> file. - -<example> - libbar 1 bar1 (>= 1.0-1) -</example> - -Now your package build should work. As soon as the maintainer of -<prgn/libbar1/ provides a <tt/shlibs/ file, you can remove your -<tt>debian/shlibs.local</> file. - -<chapt id="methif"><prgn/dselect/'s interface to its installation methods -<p> - -<prgn/dselect/ calls scripts from its installation methods when it -needs to actually access data from the distribution. The core program -<prgn/dselect/ itself just calls these scripts and provides the -package and access method selection interfaces. The installation -methods are responsible for invoking <prgn/dpkg/ as appropriate. -<p> - -Each installation method has three scripts: -<list compact> -<item>Setup installation parameters. -<item>Update list of available packages. -<item>Install. -</list> -<p> - -<prgn/dselect/ searches for methods in <tt>/usr/lib/dpkg/methods</> -and <tt>/usr/local/lib/dpkg/methods</>. - -<sect>Functions of the method scripts -<p> - -The setup script is run just after the user has chosen an installation -method. It should prompt the user for parameters like the site to -NFS-mount or FTP from, the directory to use, or the directory or -filesystem where the <tt/.deb/ files can be found, or the tape or -floppy device to install from. It should store the responses under -<tt>/var/lib/dpkg/methods</> - see below. If no available -packages list is available it should perhaps offer to scan the -available packages. -<p> - -The update script should obtain a list of available packages if -possible, and run <tt/dpkg --update-avail/, <tt/dpkg --merge-avail/ -and/or <tt/dpkg --forget-old-unavail/ to load it into <prgn/dpkg/ and -<prgn/dselect/'s database of available packages. If no packages list -was available and the user was offered and accepted the option of -scanning the actual files available this scan should be done here, -using <tt/dpkg --record-avail/. -<p> - -The install script should feed all the available <tt/.deb/ files to -<tt/dpkg --iGOEB/ (this is equivalent to <tt/dpkg --install ---refuse-downgrade --selected-only --skip-same-version ---auto-deconfigure/). The <tt/-R/ (<tt/--recursive/) option for -traversing subdirectories may also be useful here). -<p> - -If any of these scripts needs to display a message for the user, it -should wait for the user to hit `return' before exiting so that -dselect doesn't immediately rewrite the screen. -<p> - -If a method script succeeds (returns a zero exit status) -<prgn/dselect/ will return immediately to the main menu, with the -`next' option highlighted ready for the user to select it. If it -fails <prgn/dselect/ will display a message and wait for the user to -hit return. - -<sect>Location and arguments of the method scripts -<p> - -A set of scripts (henceforth known as a group) may provide several -methods on the `main menu' with different behaviour. For example, -there might be a generic get-packages-by-FTP group which might provide -methods in the main menu for installation directly from one of the -Debian mirror sites as well as for installation from a user-specified -site. -<p> - -Each group of methods implemented by the same set of scripts should -have a subdirectory <tt>/usr/lib/dpkg/methods/<var/group/</> or -<tt>/usr/local/lib/dpkg/methods/<var/group/</>, containing: -<taglist compact> -<tag><tt/names/ -<item>a list of user-visible methods provided by these scripts. -<tag><tt/setup/ -<tag><tt/update/ -<tag><tt/install/ -<item>executable programs, the scripts themselves. -<tag><tt/desc.<var/option// -<item>description file. -</taglist> -<p> - -<tt/names/ will be formatted as a list of lines, each containing: -<example> -<var/sequence/ <var/method/ <var/summary/ -</example> -<p> - -<var/sequence/ is a two-digit number that will be used much like -<tt/rc.d/ prefixes to control the order in the main menu. If in doubt -use 50. -<p> - -<var/method/ is a name which is displayed by <prgn/dselect/ as the -name of the method, and which will be passed to <tt/setup/, -<tt/update/ and <tt/unpack/ as their first argument. -<p> - -<var/summary/ is the brief description string for <prgn/dselect/'s menu. -<p> - -Each of the three scripts gets the same three arguments: <var/vardir/, -<var/group/ and <var/method/. <var/vardir/ is the base directory for -storing <prgn/dpkg/ and <prgn/dselect/'s state, usually -<tt>/var/lib/dpkg</>; this is passed in so that the <tt/--admindir/ -option to <prgn/dselect/ is honoured). -<p> - -Each option may have an extended description in -<tt/desc.<var/option//. This should be formatted like the extended -description part of a <tt/Description/ field entry <em/shifted one -character to the left/. -<p> - -<tt><var/vardir//methods</> will exist, and a method group may use a -<tt><var/vardir//methods/<var/group/</> directory to store its state. -<p> - -The group name and method name must follow the rules for C identifiers. - -<chapt id="conversion">Conversion procedure from old source packages -<p> - -This is a brief summary of the procedure for converting a -pre-2.0.0.0-format source package into the new format. -<p> - -You are strongly advised to download and examine the <prgn/hello/ -package, and to read the section in the <prgn/dpkg/ programmers' -manual describing the source packaging tools. More detail about the -exact functionality of these tools is available in <manref -name=dpkg-source section=1>. -<p> - -<list> - -<item> -Download the original source code from wherever it can be found and do -any rearrangement required to make it look like the original tree of -the Debian source. Put it in -<tt><var/package/-<var/upstream-version/.orig/</> or -<tt/<var/package/_<var/upstream-version/.orig.tar.gz/. - -<item> -Rename all files <tt/debian.*/ to <tt>debian/*</>. There may be some -exceptions to this, but this is a good start. - -<item> -Edit the <tt>debian/changelog</> - create or rename it if necessary. -Add a new revision to the top with the appropriate details, and a -local variables entry to the bottom to set Emacs to the right mode: -<example> -Local variables: -mode: debian-changelog -End: -</example> -<item> -Edit/create <tt>debian/control</>: -<list compact> -<item> -Remove the <tt/Version/ field. If it is generated unusually (not -equal to the source version) you must use the -v option to -dpkg-gencontrol (see below). <tt/Section/, <tt/Priority/, -<tt/Maintainer/ go above the first blank line, most of the rest below. - -<item> -Reorder the fields and add a blank line at an appropriate point, -separating the source package fields from the binary package -fields. - -<item> -Add the <tt/Source/ field. - -<item> -Add the <tt/Standards-Version/ field. (Please check out the Debian -Policy Manual for details about this field.) - -<item> -Change the <tt/Architecture/ field for each package to <tt/any/, -<tt/all/ or whatever. If there isn't an <tt/Architecture/ field add -one. - -<item> -If any other use of sed or things used to happen to make the binary -control files use <prgn/dpkg-gencontrol/'s variable substitution -features to achieve the same effect. Use <tt>debian/substvars</> if -you need to put unusally-generated information (apart from details of -<tt/.deb/ files) in the <tt/.changes/ file too. -</list> - -<item> -Edit the <tt>debian/rules</>: -<list compact> -<item> -Remove the <prgn/source/ and <prgn/diff/ and any <prgn/changes/ and -<prgn/dist/ targets. These things now happen in a package-independent -way and are not done by <tt>debian/rules</>. -<item> -Split the <prgn/binary/ target into <prgn/binary-arch/ and -<prgn/binary-indep/; in many cases all of <prgn/binary/ should go into -<prgn/binary-arch/. Create the <prgn/binary/ target and the unused of -the two other <prgn/binary-*/ targets if there is one - you can copy -the ones from the <prgn/hello/ package. -<item> -Change the <prgn/binary/ target to use <prgn/dpkg-gencontrol/ to make -the package control file(s). Move it to after all the files have been -installed but just before the last <prgn/chown/ and <prgn/chmod/ in -the target. -<item> -Change occurrences of <tt/debian-tmp/ to <tt>debian/tmp</>. -<item> -Change occurrences of <tt/debian.{post,pre}{inst,rm}/ to -<tt>debian/*</>. -<item> -Remove the version number setting at the top, if there is one. -<item> -Ensure that the package's Debian-specific and upstream changelogs are -installed. -</list> - -<item> -Change the package to use <prgn/dpkg-shlibdeps/ to determine its -shared library dependencies and substitute them in. Shared library -dependencies should no longer be hardwired in the source package. - -<item> -Check that the <tt>debian/README</> is really the copyright file, and -if so rename it to <tt>debian/copyright</> and edit -<tt>debian/rules</> to cope with this and to change the installation -of the copyright file from <tt>/usr/doc/<var/package//copyright</> -to <tt>/usr/doc/copyright/<var/package/</>. If it isn't then -find <tt>debian/copyright</> and decide what to do with the -<tt>README</>. - -<item> -Check for various other anachronisms and problems: -<list compact> -<item> -Remove any <tt/Package_Revision/, <tt/Package-Revision/ or -<tt/Revision/ fields. -<item> -Rename <tt/Optional/ to <tt/Suggests/, <tt/Recommended/ to -<tt/Recommends/. -<item> -Change <tt>/usr/doc/examples/<var/package/</> to -<tt>/usr/doc/<var/package//examples</>. -<item> -Make sure that manpages are installed compressed. -<item> -Check that the description has an extended description, is -well-formatted and meaningful and helpful to people wanting to know -whether to install a package. -</list> - -<item> -Look everything over. - -<item> -Do a test build using <tt/dpkg-buildpackage -us -uc -sa --r<var/whatever//. Check the permissions and locations of files in -the resulting package by examining the output of <tt/dpkg-deb ---contents/, and check that the source build happened OK. Test -install the binary package(s) and test extract the source package(s). - -<item> -Sign the release: either rebuild everything with <tt/dpkg-buildpackage --sa/, or PGP-sign the <tt/.dsc/, rebuild the <tt/.changes/ using -<tt/dpkg-genchanges -sa/, and then PGP-sign the <tt/.changes/. - -</list> -<p> - -The use of <tt/-sa/ on <prgn/dpkg-buildpackage/ and -<prgn/dpkg-genchanges/ is important when doing the first -build/uploading of a new-format source package. Unless this happens -to be Debian revision <tt/0/ or <tt/1/ by default the original source -tarfile will not be included in the uploaded files listed in the -<tt/.changes/ file, and so it won't be installed on the FTP site. -<tt/-sa/ requests that the original source be included regardless. - -</book>