From 88a29ddc386bab01a2d6d88ee043616873ce4a08 Mon Sep 17 00:00:00 2001 From: Manoj Srivastava Date: Thu, 16 Jun 2005 05:04:58 +0000 Subject: [PATCH] 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 --- packaging.sgml | 8571 ++++++++++++++++++++++++++++-------------------- 1 file changed, 5030 insertions(+), 3541 deletions(-) diff --git a/packaging.sgml b/packaging.sgml index 4a3f0a5..a040af4 100644 --- a/packaging.sgml +++ b/packaging.sgml @@ -1,4 +1,8 @@ - + + %versiondata; +]> - - -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 + + Ian Jackson + ijackson@gnu.ai.mit.edu + + + Revised: David A. Morris + bweaver@debian.org + + + Maintainer: Christian Schwarz + schwarz@debian.org + + + Maintainer: Manoj Srivastava + srivasta@debian.org + + + Maintainer: The Debian Policy group + debian-policy@lists.debian.org + + version &version;, &date; + + + This manual describes the technical aspects of creating Debian + binary and source packages. It also documents the interface + between dselect and its access method scripts. + It does not deal with the Debian Project policy requirements, + and it assumes familiarity with dpkg's functions + from the system administrator's perspective. + + + Copyright ©1996 Ian Jackson. +

+ 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. +

+ +

+ This is distributed in the hope that it will be useful, but + without any warranty; without even the implied + warranty of merchantability or fitness for a particular + purpose. See the GNU General Public License for more + details. +

+ +

+ A copy of the GNU General Public License is available as + /usr/doc/copyright/GPL in the Debian GNU/Linux + distribution or on the World Wide Web at + http://www.gnu.org/copyleft/gpl.html. You can also + obtain it by writing to the Free Software Foundation, Inc., + 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +

+ + + + + + + + Introduction and scope of this manual + +

+ dpkg is a suite of programs for creating binary + package files and installing and removing them on Unix + systems. +

+ dpkg is targetted primarily at Debian + GNU/Linux, but may work on or be ported to other + systems. +

+ +

+ +

+ 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.

+ +

+ This manual describes the technical aspects of creating Debian + binary packages (.deb files). It documents the + behaviour of the package management programs + dpkg, dselect et al. and and the way + they interact with packages.

+ +

+ It also documents the interaction between + 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.

+ +

+ 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. +

+ +

+ The utility programs which are provided with dpkg + for managing various system configuration and similar issues, + such as update-rc.d and + install-info, are not described in detail here - + please see their manpages. +

+ +

+ It does 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.) +

+ +

+ It is assumed that the reader is reasonably familiar with the + dpkg System Administrators' manual. + Unfortunately this manual does not yet exist. +

+ +

+ The Debian version of the FSF's GNU hello program is provided + as an example for people wishing to create Debian + packages. The Debian 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.

+ + + Binary packages + + +

+ The binary package has two main sections. The first part + consists of various control information files and scripts used + by dpkg when installing and removing. See . +

+ +

+ The second part is an archive containing the files and + directories to be installed. +

+ +

+ 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 + deb(5) manpage. +

+ + + Creating package files - + dpkg-deb + + +

+ All manipulation of binary package files is done by + dpkg-deb; it's the only program that has + knowledge of the format. (dpkg-deb may be + invoked by calling dpkg, as dpkg + will spot that the options requested are appropriate to + dpkg-deb and invoke that instead with the same + arguments.) +

+ +

+ 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 + debian/tmp, relative to the top of the package's + source tree. +

+ +

+ 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. +

+ +

+ With current versions of 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. +

+ +

+ You need to add one special directory to the root of the + miniature filesystem tree you're creating: + DEBIAN. It should contain the control + information files, notably the binary package control file + (see ). +

+ +

+ The DEBIAN directory will not appear in the + filesystem archive of the package, and so won't be installed + by dpkg when the package is installed. +

+ +

+ When you've prepared the package, you should invoke: + + dpkg --build directory + +

+ +

+ This will build the package in + directory.deb. (dpkg knows + that --build is a dpkg-deb option, so + it invokes dpkg-deb with the same arguments to + build the package.) +

+ +

+ See the manpage for details of how + to examine the contents of this newly-created file. You may find the + output of following commands enlightening: + +dpkg-deb --info filename.deb +dpkg-deb --contents filename.deb +dpkg --contents filename.deb -

- -No attempt is made to unwind after errors during configuration. -

- -If there is no most recently configured version <unknown> (including the angle brackets) in this case. -Even older ones do not pass a second argument at all, under any -circumstances. - -Details of removal and/or configuration purging -

- - - + To view the copyright file for a package you could use this command: - +dpkg --fsys-tarfile filename.deb | tar xof usr/doc/\*copyright | less +

+ + + + Package control information files + + +

+ The control information portion of a binary package is a + collection of files with names known to dpkg. + It will treat the contents of these files specially - some + of them contain information used by dpkg when + installing or removing the package; others are scripts which + the package maintainer wants dpkg to run. +

+ +

+ 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). +

+ +

+ Here is a brief list of the control info files supported by + dpkg and a summary of what they're used for. +

+ +

+ + control + + +

+ This is the key description file used by + 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 . +

+ +

+ It is usually generated automatically from information + in the source package by the + dpkg-gencontrol program, and with + assistance from dpkg-shlibdeps. See .

+ + + postinst, preinst, postrm, + prerm + + + +

+ These are exectuable files (usually scripts) which + 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 dpkg. Details of when and + how they are called are in . +

+ +

+ It is very important to make these scripts + idempotent. + +

+ 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. +

+ This is so that if an error occurs, the + user interrupts dpkg or some other + unforeseen circumstance happens you don't leave the + user with a badly-broken package. +

+ +

+ 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 /dev/tty, since + 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 $|=1 so that the + output is printed immediately rather than being + buffered. +

+ +

+ Each script should return a zero exit status for + success, or a nonzero one for failure.

+ + + conffiles + + + +

+ This file contains a list of configuration files which + are to be handled automatically by dpkg + (see ). Note that not necessarily + every configuration file should be listed here.

+ + + shlibs + + + +

+ This file contains a list of the shared libraries + supplied by the package, with dependency details for + each. This is used by dpkg-shlibdeps + when it determines what dependencies are required in a + package control file. The shlibs file format + is described on . +

+ + +

+ + + + The main control information file: control + +

+ The most important control information file used by + dpkg when it installs a package is + control. It contains all the package's `vital + statistics'. +

+ +

+ The binary package control files of packages built from + Debian sources are made by a special tool, + dpkg-gencontrol, which reads + debian/control and debian/changelog to + find the information it needs. See for + more details. +

+ +

+ The fields in binary package control files are: + + +

Package (mandatory)

+ + +

Version (mandatory)

+ +

Architecture + (mandatory) + +

+ This field should appear in all packages, though + dpkg doesn't require it yet so that + old packages can still be installed. +

+ +

+ + +

Depends, + Provides et al.

+ + +

Essential

+ + +

Maintainer

+ + +

Section, + Priority

+ + +

Source

+ + +

Description

+ + +

+ Installed-Size +

+ + + +

+ A description of the syntax of control files and the purpose + of these fields is available in . +

+ + + Time Stamps +

+ Maintainers are encouraged to preserve the modification + times of the upstream source files in a package, as far as + is reasonably possible. + +

+ 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. +

+ +

+ + + + Source packages + +

+ 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. +

+ +

+ 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. +

+ + + Tools for processing source packages + +

+ 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. +

+ +

+ They are introduced and typical uses described here; see + for full + documentation about their arguments and operation. +

+ +

+ 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 hello example + package. +

+ + + + dpkg-source - packs and unpacks Debian source + packages + + +

+ This program is frequently used by hand, and is also + called from package-independent automated building scripts + such as dpkg-buildpackage. +

+ +

+ To unpack a package it is typically invoked with + + dpkg-source -x .../path/to/filename.dsc + +

+ +

+ with the filename.tar.gz and + filename.diff.gz (if applicable) in + the same directory. It unpacks into + package-version, and if + applicable + package-version.orig, in + the current directory. +

+ +

+ To create a packed source archive it is typically invoked: + + dpkg-source -b package-version + +

+ +

+ This will create the .dsc, .tar.gz and + .diff.gz (if appropriate) in the current + directory. dpkg-source does not clean the + source tree first - this must be done separately if it is + required. +

+ +

+ See also .

+ + + + + + dpkg-buildpackage - overall package-building + control script + + +

+ dpkg-buildpackage is a script which invokes + dpkg-source, the debian/rules + targets clean, build and + binary, dpkg-genchanges and + pgp to build a signed source and binary + package upload. +

+ +

+ 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: + + -uc, -us + +

+ Do not PGP-sign the .changes file or the + source package .dsc file, respectively.

+ + -ppgp-command + +

+ Invoke pgp-command instead of finding + pgp on the PATH. + pgp-command must behave just like + pgp.

+ + -rroot-command + +

+ When root privilege is required, invoke the command + root-command. root-command + should invoke its first argument as a command, from + the PATH if necessary, and pass its + second and subsequent arguments to the command it + calls. If no root-command is supplied + then 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.

+ + -b, -B + +

+ Two types of binary-only build and upload - see + . +

+ + +

+ + + + + dpkg-gencontrol - generates binary package + control files + + +

+ This program is usually called from debian/rules + (see ) in the top level of the source + tree. +

+ +

+ 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 + dpkg-deb/ + +

+ This is so that the control file which is produced has + the right permissions +

+ . +

+ +

+ 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. +

+ +

+ It is also necessary for dpkg-gencontrol to + be run after dpkg-shlibdeps so that the + variable substitutions created by + dpkg-shlibdeps in debian/substvars + are available. +

+ +

+ For a package which generates only one binary package, and + which builds it in debian/tmp relative to the top + of the source package, it is usually sufficient to call: + + dpkg-gencontrol + +

+ +

+ Sources which build several binaries will typically need + something like: + + dpkg-gencontrol -Pdebian/tmp-pkg -ppackage + The -P tells + dpkg-gencontrol that the package is being + built in a non-default directory, and the -p + tells it which package's control file should be generated. +

+ +

+ dpkg-gencontrol also adds information to the + list of files in debian/files, for the benefit of + (for example) a future invocation of + dpkg-genchanges.

+ + + + + dpkg-shlibdeps - calculates shared library + dependencies + + +

+ This program is usually called from debian/rules + just before dpkg-gencontrol (see ), in the top level of the source tree. +

+ +

+ Its arguments are executables + +

+ 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. +

+ for which shared library dependencies should + be included in the binary package's control file. +

+ +

+ If some of the executable(s) shared libraries should only + warrant a Recommends or Suggests, or if + some warrant a Pre-Depends, this can be achieved + by using the -ddependency-field option + before those executable(s). (Each -d option + takes effect until the next -d.) +

+ +

+ dpkg-shlibdeps does not directly cause the + output control file to be modified. Instead by default it + adds to the debian/substvars file variable + settings like shlibs:Depends. These variable + settings must be referenced in dependency fields in the + appropriate per-binary-package sections of the source + control file. +

+ +

+ For example, the procps package generates two + kinds of binaries, simple C binaries like ps + which require a predependency and full-screen ncurses + binaries like top which require only a + recommendation. It can say in its debian/rules: + + dpkg-shlibdeps -dPre-Depends ps -dRecommends top + + and then in its main control file debian/control: + + ... + Package: procps + Pre-Depends: ${shlibs:Pre-Depends} + Recommends: ${shlibs:Recommends} + ... + +

+ +

+ Sources which produce several binary packages with + different shared library dependency requirements can use + the -pvarnameprefix option to override + the default shlib: prefix (one invocation of + dpkg-shlibdeps per setting of this option). + They can thus produce several sets of dependency + variables, each of the form + varnameprefix:dependencyfield, + which can be referred to in the appropriate parts of the + binary package control files. +

+ + + + + + dpkg-distaddfile - adds a file to + debian/files + + +

+ Some packages' uploads need to include files other than + the source and binary package files. +

+ +

+ dpkg-distaddfile adds a file to the + debian/files file so that it will be included in + the .changes file when + dpkg-genchanges is run. +

+ +

+ It is usually invoked from the binary target of + debian/rules: + + dpkg-distaddfile filename section priority + + The filename is relative to the directory where + dpkg-genchanges will expect to find it - this + is usually the directory above the top level of the source + tree. The debian/rules target should put the + file there just before or just after calling + dpkg-distaddfile. +

+ +

+ The section and priority are passed + unchanged into the resulting .changes file. See + . +

+ + + + dpkg-genchanges - generates a .changes upload + control file + + +

+ This program is usually called by package-independent + automatic building scripts such as + dpkg-buildpackage, but it may also be called + by hand. +

+ +

+ It is usually called in the top level of a built source + tree, and when invoked with no arguments will print out a + straightforward .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. +

+ + + + dpkg-parsechangelog - produces parsed representation of + a changelog + + +

+ This program is used internally by + dpkg-source et al. It may also occasionally + be useful in debian/rules and elsewhere. It + parses a changelog, debian/changelog by default, + and prints a control-file format representation of the + information in it to standard output. +

+ + + + The Debianised source tree + + +

+ 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. +

+ +

+ The extra files created for Debian are in the subdirectory + debian of the top level of the Debianised source + tree. They are described below. +

+ + debian/rules - the main building + script + + +

+ 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. +

+ +

+ It must start with the line #!/usr/bin/make -f, + so that it can be invoked by saying its name rather than + invoking make explicitly. +

+ +

+ Since an interactive debian/rules script makes it + impossible to autocompile that package and also makes it + hard for other people to reproduce the same binary + package, all required targets have to be + non-interactive. At a minimul, required targets are the + ones called by dpkg-buildpackage, namely, + clean, binary, binary-arch, and + build. It also follows that any target that these + targets depend on must also be non-interactive. +

+ +

+ The targets which are required to be present are: + + build + +

+ 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. +

+ +

+ For some packages, notably ones where the same + source tree is compiled in different ways to produce + two binary packages, the build target + does not make much sense. For these packages it is + good enough to provide two (or more) targets + (build-a and build-b or whatever) + for each of the ways of building the package, and a + build target that does nothing. The + binary target will have to build the + package in each of the possible ways and make the + binary package out of each. +

+ +

+ The build target must not do anything + that might require root privilege. +

+ +

+ The build target may need to run + clean first - see below. +

+ +

+ When a package has a configuration routine that + takes a long time, or when the makefiles are poorly + designed, or when build needs to run + clean first, it is a good idea to + touch build when the build process is + complete. This will ensure that if debian/rules + build is run again it will not rebuild the + whole program. +

+ + + binary, binary-arch, + binary-indep + + +

+ The binary 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: + binary-arch builds the packages' output + files which are specific to a particular + architecture, and binary-indep builds + those which are not. +

+ +

+ binary should usually be a target with + no commands which simply depends on + binary-arch and + binary-indep. +

+ +

+ Both binary-* targets should depend on + the 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 dpkg-gencontrol to make their + control files and dpkg-deb to build + them and place them in the parent of the top level + directory. +

+ +

+ If one of the 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 + must still exist, but should always + succeed. +

+ +

+ describes how to construct + binary packages. +

+ +

+ The binary targets must be invoked as + root. +

+ + + clean + + +

+ This should undo any effects that the + build and binary targets + may have had, except that it should leave alone any + output files created in the parent directory by a + run of binary. This target is required + to be non-interactive. +

+ +

+ If a build file is touched at the end + of the build target, as suggested + above, it must be removed as the first thing that + clean does, so that running + build again after an interrupted + clean doesn't think that everything is + already done. +

+ +

+ The clean target must be invoked as + root if binary has been invoked since + the last clean, or if + build has been invoked as root (since + build may create directories, for + example). +

+ + + get-orig-source (optional) + + +

+ 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. +

+ +

+ This target may be invoked in any directory, and + should take care to clean up any temporary files it + may have left. +

+ +

+ This target is optional, but providing it if + possible is a good idea. +

+ + + +

+ The build, binary and + clean targets must be invoked with a current + directory of the package's top-level directory. +

+ + +

+ Additional targets may exist in debian/rules, + either as published or undocumented interfaces or for the + package's internal use. +

+ + + + debian/control + + +

+ This file contains version-independent details about the + source package and about the binary packages it creates. +

+ +

+ 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. +

+ +

+ The syntax and semantics of the fields are described below + in . +

+ +

+ The general (binary-package-independent) fields are: + + +

Source (mandatory)

+ + +

Maintainer

+ + +

+ Section and + Priority + (classification, mandatory) +

+ + +

+ Standards-Version +

+ + + +

+ The per-binary-package fields are: + + +

Package (mandatory)

+ + +

+ Architecture + (mandatory)

+ + +

Description

+ + +

+ Section and + Priority (classification)

+ + +

Essential

+ + +

+ Depends et + al. (package interrelationships) +

+ + + +

+ These fields are used by dpkg-gencontrol to + generate control files for binary packages (see below), by + dpkg-genchanges to generate the + .changes file to accompany the upload, and by + dpkg-source when it creates the .dsc + source control file as part of a source archive. +

+ +

+ The fields here may contain variable references - their + values will be substituted by + dpkg-gencontrol, dpkg-genchanges + or dpkg-source when they generate output + control files. See for details. +

+ +

User-defined fields + + +

+ 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. +

+ +

+ If you wish to add additional unsupported fields to + these output files you should use the mechanism + described here. +

+ +

+ Fields in the main source control information file with + names starting X, followed by one or more of + the letters BCS and a hyphen -, 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 B is used the field + will appear in binary package control files, where the + letter S is used in source package control + files and where C is used in upload control + (.changes) files. +

+ +

+ For example, if the main source information control file + contains the field + + XBS-Comment: I stand between the candle and the star. + + then the binary and source package control files will contain the + field + + Comment: I stand between the candle and the star. + +

+ + + + + debian/changelog + + +

+ This file records the changes to the Debian-specific parts of the + package + +

+ 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. +

+ . +

+ +

+ 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. +

+ +

+ That format is a series of entries like this: + + package (version) distribution(s); + urgency=urgency + + * change details + more change details + * even more change details + + -- maintainer name and email address date + +

+ +

+ package and version are the source + package name and version number. +

+ +

+ distribution(s) lists the distributions where + this version should be installed when it is uploaded - it + is copied to the Distribution field in the + .changes file. See . +

+ +

+ urgency is the value for the Urgency + field in the .changes file for the upload. See + . It is not possible to specify an + urgency containing commas; commas are used to separate + keyword=value settings in + the dpkg changelog format (though there is + currently only one useful keyword, + urgency). +

+ +

+ 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. +

+ +

+ The maintainer name and email address should not + necessarily be those of the usual package maintainer. + They should be the details of the person doing + this version. The information here will be + copied to the .changes file, and then later used + to send an acknowledgement when the upload has been + installed. +

+ +

+ The date should be in RFC822 format + +

+ This is generated by the 822-date + program. +

+ ; it should include the timezone specified + numerically, with the timezone name or abbreviation + optionally present as a comment. +

+ +

+ 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. +

+ +

+ An Emacs mode for editing this format is available: it is + called 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. +

+ + Defining alternative changelog formats + + +

+ It is possible to use a different format to the standard + one, by providing a parser for the format you wish to + use. +

+ +

+ In order to have dpkg-parsechangelog run your + parser, you must include a line within the last 40 lines + of your file matching the Perl regular expression: + \schangelog-format:\s+([0-9a-z]+)\W The part in + parentheses should be the name of the format. For + example, you might say: + + @@@ changelog-format: joebloggs @@@ + + Changelog format names are non-empty strings of alphanumerics. +

+ +

+ If such a line exists then dpkg-parsechangelog + will look for the parser as + /usr/lib/dpkg/parsechangelog/format-name + or + /usr/local/lib/dpkg/parsechangelog/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 dpkg, and a parser for it is provided with + the dpkg package. +

+ +

+ 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 + -vversion option to return changes + information from all versions present strictly + after version, and it should then be an + error for version not to be present in the + changelog. +

+ +

+ The fields are: + + +

Source

+ + +

Version (mandatory)

+ + +

+ Distribution + (mandatory) +

+ + +

Urgency (mandatory)

+ + +

+ Maintainer + (mandatory) +

+ + +

Date

+ + +

+ Changes + (mandatory) +

+ + + +

+ If several versions are being returned (due to the use + of -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. +

+ +

+ For the format of the Changes field see . +

+ +

+ 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. +

+ +

+ 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. +

+ +

+ 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. +

+ +

+ A changelog parser may not interact with the user at + all.

 + + + debian/substvars + and variable substitutions + + +

+ When dpkg-gencontrol, + dpkg-genchanges and dpkg-source + generate control files they do variable substitutions on + their output just before writing it. Variable + substitutions have the form + ${variable-name}. The optional file + debian/substvars contains variable substitutions + to be used; variables can also be set directly from + debian/rules using the -V option to the + source packaging commands, and certain predefined + variables are available. +

+ +

+ The is usually generated and modified dynamically by + debian/rules targets; in this case it must be + removed by the clean target. +

+ +

+ See for full + details about source variable substitutions, including the + format of debian/substvars.

+ + + debian/files + + +

+ This file is not a permanent part of the source tree; it + is used while building packages to record which files are + being generated. dpkg-genchanges uses it + when it generates a .changes file. +

+ +

+ It should not exist in a shipped source package, and so it + (and any backup files or temporary files such as + files.new + +

+ files.new is used as a temporary file by + dpkg-gencontrol and + dpkg-distaddfile - they write a new + version of files here before renaming it, + to avoid leaving a corrupted copy if an error + occurs +

+ ) should be removed by the + clean target. It may also be wise to + ensure a fresh start by emptying or removing it at the + start of the binary target. +

+ +

+ dpkg-gencontrol adds an entry to this file + for the .deb file that will be created by + 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 clean. +

+ +

+ If a package upload includes files besides the source + package and any binary packages whose control files were + made with dpkg-gencontrol then they should be + placed in the parent of the package's top-level directory + and dpkg-distaddfile should be called to add + the file to the list in debian/files.

+ + + debian/tmp + + +

+ This is the canonical temporary location for the + construction of binary packages by the binary + target. The directory 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 DEBIAN subdirectory. See . +

+ +

+ If several binary packages are generated from the same + source tree it is usual to use several + debian/tmpsomething directories, for + example tmp-a or tmp-doc. +

+ +

+ Whatever tmp directories are created and used by + binary must of course be removed by the + clean target.

 + + + + Source packages as archives + + +

+ 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. +

+ +

+ + Debian source control file - .dsc + + +

+ 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 . + + +

Source

+ + +

Version

+ + +

Maintainer

+ + +

Binary

+ + +

Architecture

+ + +

+ Standards-Version

+ + +

Files

+ + + +

+ The source package control file is generated by + 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.

+ + + + Original source archive - + + package_upstream-version.orig.tar.gz + + + + + +

+ This is a compressed (with gzip -9) + tar file containing the source code from + the upstream authors of the program. The tarfile + unpacks into a directory + package-upstream-version.orig, + and does not contain files anywhere other than in + there or in its subdirectories.

+ + + + Debianisation diff - + + package_upstream_version-revision.diff.gz + + + + +

+ This is a unified context diff (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. +

+ +

+ All the directories in the diff must exist, except the + debian subdirectory of the top of the source + tree, which will be created by + dpkg-source if necessary when unpacking. +

+ +

+ The dpkg-source program will + automatically make the debian/rules file + executable (see below).

 + + + +

+ 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 + package_version.tar.gz and + contains a directory + package-version. +

+ + + Unpacking a Debian source package without + dpkg-source + + +

+ 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: + + +

+ Untar the tarfile, which will create a .orig + directory.

+ + +

Rename the .orig directory to + package-version.

+ + +

+ Create the subdirectory debian at the top of + the source tree.

+ +

Apply the diff using patch -p0.

+ +

Untar the tarfile again if you want a copy of the original + source code alongside the Debianised version.

+ + + +

+ It is not possible to generate a valid Debian source archive + without using dpkg-source. In particular, + attempting to use diff directly to generate the + .diff.gz file will not work. +

+ + Restrictions on objects in source packages + + +

+ The source package may not contain any hard links + +

+ This is not currently detected when building source + packages, but only when extracting + them. +

+ + +

+ Hard links may be permitted at some point in the + future, but would require a fair amount of + work. +

+ , device special files, sockets or setuid or + setgid files. + +

+ Setgid directories are allowed. +

+ +

+ +

+ The source packaging tools manage the changes between the + original and Debianised source using diff and + patch. Turning the original source tree as + included in the .orig.tar.gz into the debianised + source must not involve any changes which cannot be + handled by these tools. Problematic changes which cause + dpkg-source to halt with an error when + building the source package are: + +

Adding or removing symbolic links, sockets or pipes.

+ +

Changing the targets of symbolic links.

+ +

Creating directories, other than debian.

+ +

Changes to the contents of binary files.

 + Changes which cause dpkg-source to + print a warning but continue anyway are: + + +

+ Removing files, directories or symlinks. + +

+ 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.

+ +

+ + +

+ Changed text files which are missing the usual final + newline (either in the original or the modified + source tree). +

+ + + Changes which are not represented, but which are not detected by + dpkg-source, are: + +

Changing the permissions of files (other than + debian/rules) and directories.

 + +

+ +

+ The debian directory and debian/rules + are handled specially by dpkg-source - before + applying the changes it will create the debian + directory, and afterwards it will make + debian/rules world-exectuable. +

+ + + + + Control files and their fields + + +

+ Many of the tools in the dpkg suite manipulate + data in a common format, known as control files. Binary and + source packages have control data as do the .changes + files which control the installation of uploaded files, and + dpkg's internal databases are in a similar + format. +

+ + Syntax of control files + + +

+ 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. +

+ +

+ 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. +

+ +

+ Some fields' values may span several lines; in this case + each continuation line must start with a space or + tab. Any trailing spaces or tabs at the end of individual + lines of a field value are ignored. +

+ +

+ 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. +

+ +

+ Field names are not case-sensitive, but it is usual to + capitalise the fields using mixed case as shown below. +

+ +

+ 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. +

+ +

+ It is important to note that there are several fields which + are optional as far as 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 must read + the Debian policy manual in conjuction with the details + below and the list of fields for the particular file.

+ + + List of fields + + + Package + + +

+ The name of the binary package. Package names consist of + the alphanumerics and + - . + (plus, minus and full stop). + +

+ The characters @ : = + 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 +

+ +

+ +

+ They must be at least two characters and must start with + an alphanumeric. In current versions of dpkg they are + sort of case-sensitive

This is a + bug.

; use lowercase package names unless + the package you're building (or referring to, in other + fields) is already using uppercase.

+ + + Version + + +

+ This lists the source or binary package's version number - + see . +

+ + + + Architecture + + +

+ This is the architecture string; it is a single word for + the CPU architecture. +

+ +

+ dpkg will check the declared architecture of + a binary package against its own compiled-in value before + it installs it. +

+ +

+ The special value all indicates that the package + is architecture-independent. +

+ +

+ In the main debian/control file in the source + package, or in the source package control file + .dsc, a list of architectures (separated by + spaces) is also allowed, as is the special value + any. A list indicates that the source will build + an architecture-dependent package, and will only work + correctly on the listed architectures. 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. +

+ +

+ In a .changes file the 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 source is also present. +

+ +

+ The current build architecture can be determined using dpkg + --print-architecture. + +

+ This actually invokes + + gcc --print-libgcc-file-name + and parses and decomposes the output and + looks the CPU type from the GCC configuration in a + table in dpkg. This is so that it will + work if you're cross-compiling. +

+ This value is automatically used by + dpkg-gencontrol when building the control + file for a binary package for which the source control + information doesn't specify architecture all. +

+ +

+ There is a separate option, + --print-installation-architecture, for finding + out what architecture dpkg is willing to + install. This information is also in the output of + dpkg --version.

+ + + Maintainer + + +

+ The package maintainer's name and email address. The name + should come first, then the email address inside angle + brackets <> (in RFC822 format). +

+ +

+ 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). +

+ +

+ In a .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. +

+ +

+ This field is usually optional in as far as the + dpkg are concerned, but its absence when + building packages usually generates a warning.

+ + + Source + + +

+ This field identifies the source package name. +

+ +

+ In a main source control information or a + .changes or .dsc file or parsed + changelog data this may contain only the name of the + source package. +

+ +

+ In the control file of a binary package (or in a + Packages file) it may be followed by a version + number in parentheses. + +

+ It is usual to leave a space after the package name if + a version number is specified. +

+ This version number may be omitted (and is, by + dpkg-gencontrol) if it has the same value as + the 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. +

+ + + Package interrelationship fields: + Depends, Pre-Depends, + Recommends Suggests, Conflicts, + Provides, Replaces + + +

+ These fields describe the package's relationships with + other packages. Their syntax and semantics are described + in .

+ + + Description + + +

+ In a binary package Packages file or main source + control file this field contains a description of the + binary package, in a special format. See for details. +

+ +

+ In a .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.

+ + + Essential + + +

+ This is a boolean field which may occur only in the + control file of a binary package (or in the + Packages file) or in a per-package fields + paragraph of a main source control data file. +

+ +

+ If set to yes then dpkg and + dselect will refuse to remove the package + (though it can be upgraded and/or replaced). The other + possible value is no, which is the same as not + having the field at all.

+ + + Section and + Priority + + +

+ These two fields classify the package. The + Priority represents how important that it is that + the user have it installed; the Section + represents an application area into which the package has + been classified. +

+ +

+ When they appear in the debian/control file these + fields give values for the section and priority subfields + of the Files field of the .changes file, + and give defaults for the section and priority of the + binary packages. +

+ +

+ The section and priority are represented, though not as + separate fields, in the information for each file in the + -Filefield of a + .changes file. The section value in a + .changes file is used to decide where to install + a package in the FTP archive. +

+ +

+ These fields are not used by by dpkg proper, + but by 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. +

+ +

+ These fields may appear in binary package control files, + in which case they provide a default value in case the + Packages files are missing the information. + dpkg and dselect will only use + the value from a .deb file if they have no other + information; a value listed in a Packages file + will always take precedence. By default + dpkg-genchanges does not include the section + and priority in the control file of a binary package - use + the -isp, -is or -ip options to + achieve this effect.

+ + + Binary + + +

+ This field is a list of binary packages. +

+ +

+ When it appears in the .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. +

+ +

+ When it appears in a .changes file it lists the + names of the binary packages actually being uploaded. +

+ +

+ The syntax is a list of binary packages separated by + commas. + +

+ A space after each comma is conventional. +

+ Currently the packages must be separated using + only spaces in the .changes file.

+ + + Installed-Size + + +

+ This field appears in the control files of binary + packages, and in the Packages files. It gives + the total amount of disk space required to install the + named package. +

+ +

+ The disk space is represented in kilobytes as a simple + decimal number.

+ + + Files + + +

+ 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. +

+ +

+ In the .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. + +

+ That is, the parts which are not the + .dsc. +

+ The exact forms of the filenames are described + in . +

+ +

+ In the .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 . If no section or priority is + specified then - should be used, though section + and priority values must be specified for new packages to + be installed properly. +

+ +

+ The special value byhand for the section in a + .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 + byhand the priority should be -. +

+ +

+ If a new Debian revision of a package is being shipped and + no new original source archive is being distributed the + .dsc must still contain the Files field + entry for the original source archive + package-upstream-version.orig.tar.gz, + but the .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 + .dsc file and diff which are being uploaded.

+ + + + Standards-Version + + +

+ The most recent version of the standards (the + 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. +

+ +

+ Its format is the same as that of a version number except + that no epoch or Debian revision is allowed - see .

+ + + + Distribution + + +

+ In a .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 ). +

+ +

+ Current distribution values are: + + stable + +

+ This is the current `released' version of Debian + GNU/Linux. A new version is released approximately + every 3 months after the development code has + been frozen for a month of testing. Once the + distribution is 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). +

+ + + unstable + +

+ This distribution value refers to the + developmental part of the Debian distribution + tree. New packages, new upstream versions of packages + and bug fixes go into the unstable directory + tree. Download from this distribution at your own + risk.

+ + + contrib + +

+ 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 contrib + Distribution. There is currently no distinction + between stable and unstable packages in the + contrib or non-free + distributions. Use your best judgement in downloading + from this Distribution.

+ + + non-free + +

+ Like the packages in the contrib seciton, + the packages in 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.

+ + experimental + +

+ 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.

+ + + frozen + +

+ From time to time, (currently, every 3 months) the + unstable distribution enters a state of + `code-freeze' in anticipation of release as a + stable version. During this period of testing + (usually 4 weeks) only fixes for existing or + newly-discovered bugs will be allowed. +

+ + You should list all distributions that + the package should be installed into. Except in unusual + circumstances, installations to stable should also + go into frozen (if it exists) and + unstable. Likewise, installations into + frozen should also go into unstable.

+ + + Urgency + + +

+ 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 LOW, + MEDIUM or HIGH) followed by an optional + commentary (separated by a space) which is usually in + parentheses. For example: + + Urgency: LOW (HIGH for diversions users) + +

+ +

+ This field appears in the .changes file and in + parsed changelogs; its value appears as the value of the + urgency attribute in a dpkg-style + changelog (see ). +

+ +

+ Urgency keywords are not case-sensitive.

+ + + Date + + +

+ In .changes files and parsed changelogs, this + gives the date the package was built or last edited.

+ + + Format + + +

+ This field occurs in .changes files, and + specifies a format revision for the file. The format + described here is version 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 .

+ + + Changes + + +

+ In a .changes file or parsed changelog this field + contains the human-readable changes data, describing the + differences between the last version and the current one. +

+ +

+ 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. +

+ +

+ 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. +

+ +

+ 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).

+ + + Filename and + MSDOS-Filename + + +

+ These fields in 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.

+ + + Size and MD5sum + + +

+ These fields in 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.

+ + + Status + + +

+ This field in 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.

+ + + Config-Version + + +

+ If a package is not installed or not configured, this + field in dpkg's status file records the last + version of the package which was successfully + configured.

+ + + Conffiles + + +

+ This field in dpkg's status file contains + information about the automatically-managed configuration + files held by a package. This field should not + appear anywhere in a package!

+ + + Obsolete fields + + +

+ These are still recognised by dpkg but should + not appear anywhere any more. + + + Revision + Package-Revision + Package_Revision + +

+ The Debian revision part of the package version was + at one point in a separate control file field. This + field went through several names.

+ + + Recommended +

Old name for Recommends

+ + + Optional +

Old name for Suggests.

+ + Class +

Old name for Priority.

+ + +

+ + + + + Version numbering + + +

+ Every package has a version number, in its Version + control file field. +

+ +

+ dpkg imposes an ordering on version numbers, so + that it can tell whether packages are being up- or downgraded + and so that 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. +

+ +

+ The version number format is: + &lsqbepoch/:]upstream-version[-/debian-revision]. +

+ +

+ The three components here are: + + epoch + + +

+ 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 + upstream-version may not contain any colons. +

+ +

+ 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. +

+ +

+ dpkg will not usually display the epoch + unless it is essential (non-zero, or if the + upstream-version contains a colon); + dselect does not display epochs at all in + the main part of the package selection display.

+ + + upstream-version + + +

+ This is the main part of the version. It is usually + version number of the original (`upstream') package of + which the .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 + dpkg's format and comparison scheme. +

+ +

+ The comparison behaviour of dpkg with + respect to the upstream-version is described + below. The upstream-version portion of the + version number is mandatory. +

+ +

+ The upstream-version may contain only + alphanumerics and the characters + . + - : (full stop, plus, hyphen, colon) + and should start with a digit. If there is no + debian-revision then hyphens are not allowed; + if there is no epoch then colons are not + allowed.

+ + + debian-revision + + +

+ 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 + upstream-version and dpkg + compares it in the same way. +

+ +

+ It is optional; if it isn't present then the + 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. +

+ +

+ It is conventional to restart the + debian-revision at 1 each time the + upstream-version is increased. +

+ +

+ dpkg will break the + upstream-version and + debian-revision apart at the last hyphen in + the string. The absence of a debian-revision + compares earlier than the presence of one (but note that + the debian-revision is the least significant + part of the version number). +

+ +

+ The debian-revision may contain only + alphanumerics and the characters + and + . (plus and full stop). +

+ + + The upstream-version and debian-revision parts are + compared by dpkg using the same algorithm: +

+ +

+ The strings are compared from left to right. +

+ +

+ 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. +

+ +

+ 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. +

+ +

+ 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. +

+ +

+ 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 not there + to cope with version numbers containing strings of letters + which dpkg cannot interpret (such as + ALPHA or pre-), or with silly orderings (the + author of this manual has heard of a package whose versions + went 1.1, 1.2, 1.3, 1, + 2.1, 2.2, 2 and so forth). +

+ +

+ If an upstream package has problematic version numbers they + should be converted to a sane form for use in the + Version field. +

+ +

+ If you need to compare version numbers in a script, you may use + dpkg --compare-versions .... Type dpkg + --help --> --for details on arguments. +

+ + + Package maintainer scripts + and installation procedure + + + Introduction to package maintainer scripts + + +

+ It is possible supply scripts as part of a package which + dpkg will run for you when your package is + installed, upgraded or removed. +

+ +

+ These scripts should be the files preinst, + postinst, prerm and 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 #! convention. They should be + readable and executable to anyone, and not world-writeable. +

+ +

+ 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 dpkg can + stop its processing. For shell scripts this means that you + almost always need to use 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. +

+ +

+ 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. +

+ +

+ 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. +

+ +

+ Broadly speaking the preinst is called before + (a particular version of) a package is installed, and the + postinst afterwards; the prerm + before (a version of) a package is removed and the + postrm afterwards. +

+ + +

Programs called from maintainer scripts should not + normally have a path prepended to them. Before installation + is started dpkg checks to see if the programs + ldconfig, start-stop-daemon, + install-info, and update-rc.d can + be found via the PATH environment variable. Those + programs, and any other program that one would expect to on + the PATH, should thus be invoked without an + absolute pathname. Maintainer scripts should also not reset + the PATH, though they might choose to modify it by + pre- or appending package-specific directories. These + considerations really apply to all shell scripts.

+ + + Summary of ways maintainer + scripts are called + + +

+ + +

new-preinst install

+ + +

new-preinst install + old-version

+ + +

new-preinst upgrade + old-version

+ + +

old-preinst abort-upgrade + new-version +

+ + + +

+ + +

postinst configure + most-recently-configured-version

+ + +

old-postinst abort-upgrade + new version

+ + +

conflictor's-postinst abort-remove + in-favour package + new-version

+ + +

+ deconfigured's-postinst + abort-deconfigure in-favour + failed-install-package version + removing conflicting-package + version +

+ + + +

+ + +

prerm remove

+ + +

old-prerm upgrade + new-version

+ + +

new-prerm failed-upgrade + old-version

+ + +

conflictor's-prerm remove + in-favour package + new-version

+ + +

+ deconfigured's-prerm deconfigure + in-favour package-being-installed + version removing + conflicting-package + version +

+ + + +

+ + +

postrm remove

+ + +

postrm purge

+ + +

+ old-postrm upgrade + new-version

+ + +

new-postrm failed-upgrade + old-version

+ + +

new-postrm abort-install

+ + +

new-postrm abort-install + old-version

+ + +

new-postrm abort-upgrade + old-version

+ + +

+ disappearer's-postrm disappear + r>overwritr> + new-version

 + +

+ + + Details of unpack phase of + installation or upgrade + + +

+ The procedure on installation/upgrade/overwrite/disappear + (ie, when running dpkg --unpack, or the unpack + stage of 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. + + + +

+ + +

If a version the package is already + installed, call + + old-prerm upgrade new-version +

+ + +

+ If this gives an error (ie, a non-zero exit + status), dpkg will attempt instead: + + new-prerm failed-upgrade old-version + + Error unwind, for both the above cases: + + old-postinst abort-upgrade new-version + +

+ + +

+ + +

If a `conflicting' package is being removed at the same time: + + +

+ If any packages depended on that conflicting + package and --auto-deconfigure is + specified, call, for each such package: + + deconfigured's-prerm deconfigure \ + in-favour package-being-installed version \ + removing conflicting-package version + + Error unwind: + + deconfigured's-postinst abort-deconfigure \ + in-favour package-being-installed-but-failed version \ + removing conflicting-package version + + The deconfigured packages are marked as + requiring configuration, so that if + --install is used they will be + configured again if possible.

+ + +

To prepare for removal of the conflicting package, call: + + conflictor's-prerm remove in-favour package new-version + + Error unwind: + + conflictor's-postinst abort-remove \ + in-favour package new-version + +

+ + +

+ + +

+ + +

If the package is being upgraded, call: + + new-preinst upgrade old-version +

+ + +

+ Otherwise, if the package had some configuration + files from a previous version installed (ie, it + is in the `configuration files only' state): + + new-preinst install old-version +

+ + +

Otherwise (ie, the package was completely purged): + + new-preinst install + + Error unwind versions, respectively: + + new-postrm abort-upgrade old-version + new-postrm abort-install old-version + new-postrm abort-install + +

+ + +

+ + + +

+ 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). +

+ +

+ It is an error for a package to contains files which + are on the system in another package, unless + Replaces is used (see ). + Currently the --force-overwrite flag is + enabled, downgrading it to a warning, but this may not + always be the case. +

+ +

+ 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 + Replaces is used). This error can be + overridden if desired using + --force-overwrite-dir, but this is not + advisable. +

+ +

+ 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. + +

+ Part of the problem is due to what is arguably a + bug in dpkg . +

+ +

+ +

+ 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 + dpkg will follow the symlink if there is + one.

+ + + + +

+ +

If the package is being upgraded, call + + old-postrm upgrade new-version +

+ + +

If this fails, dpkg will attempt: + + new-postrm failed-upgrade old-version + + Error unwind, for both cases: + + old-preinst abort-upgrade new-version + +

+ + + This is the point of no return - if 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 + dpkg starts doing things that are + irreversible.

+ + +

+ Any files which were in the old version of the package + but not in the new are removed.

+ + +

The new file list replaces the old.

+ + +

The new maintainer scripts replace the old.

+ + + +

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, + + +

dpkg calls: + + disappearer's-postrm disappear \ + overwriter overwriter-version +

+ + +

The package's maintainer scripts are removed. +

+ + +

+ 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 dpkg). Note that + disappearing packages do not have their prerm + called, because dpkg doesn't know + in advance that the package is going to + vanish. +

+ + +

+ + +

+ 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.) +

+ + +

+ The backup files made during installation, above, are + deleted. +

+ + + +

+ 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. +

+ + +

+ 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). +

+ + +

+ + + Details of configuration + + +

+ When we configure a package (this happens with dpkg + --install, or with --configure), we first + update the conffiles and then call: + + postinst configure most-recently-configured-version + +

+ +

+ No attempt is made to unwind after errors during + configuration. +

+ +

+ If there is no most recently configured version + dpkg will pass a null argument; older versions + of dpkg may pass <unknown> (including the + angle brackets) in this case. Even older ones do not pass a + second argument at all, under any circumstances. +

+ + + Details of removal and/or configuration purging + + +

+ + +

+ prerm remove +

+ + +

+ The package's files are removed (except conffiles). +

+ + +

+ postrm remove +

+ + +

All the maintainer scripts except the postrm are removed. +

+ +

+ 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 dpkg + status.

+ + +

+ The conffiles and any backup files (~-files, + #*# files, %-files, + .dpkg-{old,new,tmp}, etc.) are removed.

+ + +

+ postrm purge +

+ + +

The package's file list is removed.

+ + + No attempt is made to unwind after errors during + removal.

+ + + + Descriptions of packages - the + Description field + + +

+ The Description control file field is used by + dselect when the user is selecting which packages + to install and by dpkg when it displays + information about the status of packages and so forth. It is + included on the FTP site in the Packages files, + and may also be used by the Debian WWW pages. +

+ +

+ 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. +

+ +

+ The field's format is as follows: + + Description: single line synopsis + extended description over several lines + +

+ +

+ 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. +

+ + Types of formatting line in the extended + description + + +

+ + +

+ 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. +

+ + + +

+ 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). +

+ + + +

Those containing a single space followed by a single full stop + character. These are rendered as blank lines. This + is the only way to get a blank line - see + below.

+ + + +

+ Those containing a space, a full stop and some more + characters. These are for future expansion. Do not + use them.

+ + +

+ + + Notes about writing descriptions + + +

+ 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 dpkg-deb + +

+ Version 0.93.23 or later. +

+ to produce a syntax error when trying to build + the package. If you force it to build anyway + dpkg will refuse to install the resulting + mess. +

+ +

+ Do not include any completely empty + lines. These separate different records in the Packages file + and different packages in the debian/control file, + and are forbidden in package control files. See the + previous paragraph for what happens if you get this wrong. +

+ +

+ The single line synopsis should be kept brief - certainly + under 80 characters. 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. +

+ +

+ 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. +

+ +

+ 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). +

+ +

+ The blurb that comes with a program in its announcements + and/or 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. +

+ +

+ 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. +

+ +

+ You may include information about dependencies and so forth + in the extended description, if you wish. +

+ +

+ Do not use tab characters. Their effect is not predictable. +

+ +

+ Do not try to linewrap the summary (the part on the same + line as the field name 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.

+ + + Example description in control file for Smail + + +

+ + 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. + +

+ + + + Declaring relationships between + packages + + +

+ 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. +

+ +

+ This is done using the Depends, Recommends, + Suggests, Conflicts, Provides and + Replaces control file fields. +

+ + Syntax of relationship fields + + +

+ These fields all have a uniform syntax. They are a list of + package names separated by commas. +

+ +

+ In Depends, Recommends, Suggests + and 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 + | (pipe symbols). +

+ +

+ All the fields except 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 . +

+ +

+ The relations allowed are <<, <=, + =, >= and >> for + strictly earlier, earlier or equal, exactly equal, later or + equal and strictly later, respectively. The forms + < and > were used to mean + earlier/later or equal, rather than strictly earlier/later, + so they should not appear in new packages (though + dpkg still supports them). +

+ +

+ 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 + 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. +

+ +

+ For example: + + Package: metamail + Version: 2.7-3 + Depends: libc5 (>= 5.2.18-4), mime-support, csh | tcsh + +

+ + + Dependencies - Depends, Recommends, + tt>Suggett>, Pre-Depends + + +

+ These four fields are used to declare a dependency by one + package on another. They appear in the depending package's + control file. +

+ +

+ All but Pre-Depends (discussed below) take effect + 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. +

+ +

+ 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. +

+ +

+ Thus Depends allows package maintainers to impose + an order in which packages should be configured. + + Depends + + +

This declares an absolute dependency. +

+ +

+ 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 + +

+ Current versions (1.2.4) of dpkg have + a bug in this area which will cause some of these + problems to be ignored. +

+ , unless --auto-deconfigure is + specified, in which case those packages will be + deconfigured before the installation proceeds. +

+ +

+ dselect makes it hard for the user to + select packages for installation, removal or upgrade + in a way that would mean that packages' + Depends fields would be unsatisfied. The + user can override this if they wish, for example if + they know that dselect has an out-of-date + view of the real package relationships. +

+ +

+ The Depends field should be used if the + depended-on package is required for the depending + package to provide a significant amount of + functionality.

+ + + Recommends + +

This declares a strong, but not absolute, dependency. +

+ +

+ Recommends is ignored by dpkg, + so that users using the command-line (who are presumed + to know what they're doing) will not be impeded. +

+ +

+ It is treated by dselect exactly as + Depends is; this makes it hard for the user + to select things so as to leave Recommends + fields unsatisfied, but they are able to do so by + being persistent. +

+ +

+ The Recommends field should list packages + that would be found together with this one in all but + unusual installations.

+ + + Suggests + + +

+ 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. +

+ +

+ 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.

+ + + Pre-Depends + + +

This field is like Depends, except that it also forces + dpkg to complete installation of the + packages named before even starting the installation + of the package which declares the predependency. +

+ +

+ 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. +

+ +

+ However, this process is slow (because it requires + repeated invocations of dpkg) and + troublesome (because it requires guessing where to + find the appropriate files). +

+ +

+ 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), + 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. +

+ +

+ When the package declaring it is being configured, a + Pre-Dependency will be considered satisfied + only if the depending package has been correctly + configured, just as if an ordinary Depends + had been used. +

+ +

+ 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 Pre-Depends field. +

+ + +

+

+ 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 + 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. +

+ + Dependencies on shared libraries + + +

+ The dependency fields listed above are used by packages + which need shared libraries to declare dependencies on the + appropriate packages. +

+ +

+ These dependencies are usually determined automatically + using dpkg-shlibdeps and inserted in the + package control file using the control file substitution + variables mechanism; see and + . +

+ + + Deconfiguration due to removal during bulk + installations + + +

+ If 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, + dpkg will usually not remove the conflicting + package and halt with an error. +

+ +

+ However, if the --auto-deconfigure (-B) + option is used 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 + 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. +

+ +

+ dselect supplies this argument to + dpkg when it invokes it, so that bulk + installations proceed smoothly. +

+ + + Alternative packages - + tt>Conflitt> and Replaces + + +

+ When one package declares a conflict with another + dpkg will refuse to allow them to be installed + on the system at the same time. +

+ +

+ If one package is to be installed, the other must be removed first - + if the package being installed is marked as replacing () the one on the system, or the one on the system is + marked as deselected, or both packages are marked + Essential, then dpkg will + automatically remove the package which is causing the + conflict, otherwise it will halt the installation of the new + package with an error. +

+ +

+ dselect makes it hard to select conflicting + packages, though the user can override this if they wish. + If they do not override it then dselect will + select one of the packages for removal, and the user must + make sure it is the right one. In the future + dselect will look for the presence of a + Replaces field to help decide which package should + be installed and which removed. +

+ +

+ A package will not cause a conflict merely because its + configuration files are still installed; it must be at least + half-installed. +

+ +

+ 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. +

+ +

+ A Conflicts entry should almost never have an + `earlier than' version clause. This would prevent + 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 + dselect, so that the use Conflicts in + this way is likely to cause problems for `bulk run' upgrades + and installations. +

+ + + Virtual packages - Provides + + +

+ As well as the names of actual (`concrete') packages, the + package relationship fields Depends, + Recommends, Suggests and + Conflicts may mention virtual packages. +

+ +

+ A virtual package is one which appears in the + 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. +

+ +

+ 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 + + Package: vm + Depends: emacs + + and someone else releases an xemacs package they can say + + Package: xemacs + Provides: emacs + and all will work in the interim (until a purely + virtual package name is decided on and the emacs + and vm packages are changed to use it). +

+ +

+ 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 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. +

+ +

+ It is likely that the ability will be added in a future + release of 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. +

+ +

+ 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. +

+ + + + Replaces - overwriting + files and replacing packages + + +

+ The Replaces control file field has two purposes, + which come into play in different situations. +

+ +

+ Virtual packages () are not considered + when looking at a Replaces field - the packages + declared as being replaced must be mentioned by their real + names. +

+ + Overwriting files in other packages + + +

+ 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 + --force-overwrite flag is enabled by default, + downgrading the error to a warning, +

+ +

+ If the overwriting package declares that it replaces the + one containing the file being overwritten then + 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. +

+ +

+ If a package is completely replaced in this way, so that + 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 + postrm script will be run to allow the + package to do any final cleanup required. See . +

+ +

+ In the future 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). +

+ +

+ This usage of 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.

+ + + Replacing whole packages, forcing their + removal + + +

+ Secondly, Replaces allows dpkg and + dselect to resolve which package should be + removed when a conflict - see . This + usage only takes effect when the two packages do + conflict, so that the two effects do not interfere with + each other. +

+ + + + Defaults for satisfying dependencies - ordering + + +

+ Ordering is significant in dependency fields. +

+ +

+ 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. +

+ +

+ In the absence of other information dselect + will offer a default selection of the first named package in + a list of alternatives. +

+ +

+ 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. +

+ +

+ Therefore a dependency on a virtual package should contain a + concrete package name as the first alternative, so that this + is the default. +

+ +

+ For example, consider the set of packages: + + Package: glibcdoc + Recommends: info-browser + + Package: info + Provides: info-browser + + Package: emacs + Provides: info-browser + +

+ +

+ If emacs and info both have the + same priority then dselect's choice is + essentially random. Better would be + + Package: glibcdoc + Recommends: info | info-browser + + so that dselect defaults to selecting the + lightweight standalone info browser. +

+ + + + Configuration file handling + + +

+ dpkg can do a certain amount of automatic + handling of package configuration files. +

+ +

+ Whether this mechanism is appropriate depends on a number of + factors, but basically there are two approaches to any + particular configuration file. +

+ +

+ The easy method is to ship a best-effort configuration in the + package, and use 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. +

+ +

+ The hard method is to build the configuration file from + scratch in the 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. +

+ + Automatic handling of configuration files by + dpkg + + +

+ A package may contain a control area file called + 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. +

+ +

+ When a package is upgraded dpkg will process + the configuration files during the configuration stage, + shortly before it runs the package's postinst + script, +

+ +

+ 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. +

+ +

+ 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. +

+ +

+ 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. +

+ +

+ When a package is installed for the first time + dpkg will install the file that comes with it, + unless that would mean overwriting a file already on the + filesystem. +

+ +

+ However, note that dpkg will 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. +

+ +

+ Note that a package should not modify a + dpkg-handled conffile in its maintainer + scripts. Doing this will lead to dpkg giving + the user confusing and possibly dangerous options for + conffile update when the package is upgraded.

+ + + Fully-featured maintainer script configuration + handling + + +

+ 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 + postinst script. +

+ +

+ 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. +

+ +

+ When using this method there are a couple of important + issues which should be considered: +

+ +

+ 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. +

+ +

+ 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 /usr/sbin, by convention called + packageconfig and then run that if + appropriate from the post-installation script. The + packageconfig 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 --force flag to + overwrite it.

 + + + + + Alternative versions of an interface - + update-alternatives + + +

+ 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. +

+ +

+ For example, there are several versions of the vi + editor, and there is no reason to prevent all of them from + being installed at once, each under their own name + (nvi, vim or whatever). + Nevertheless it is desirable to have the name vi + refer to something, at least by default. +

+ +

+ If all the packages involved cooperate, this can be done with + update-alternatives. +

+ +

+ Each package provides its own version under its own name, and + calls update-alternatives in its postinst to + register its version (and again in its prerm to deregister + it). +

+ +

+ See the manpage for details. +

+ +

+ If update-alternatives does not seem appropriate + you may wish to consider using diversions instead.

+ + + + Diversions - overriding a + package's version of a file + + +

+ It is possible to have 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. +

+ +

+ 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). +

+ +

+ Before deciding to use a diversion, read to see if you really want a diversion + rather than several alternative versions of a program. +

+ +

+ There is a diversion list, which is read by dpkg, + and updated by a special program dpkg-divert. + Please see for full + details of its operation. +

+ +

+ When a package wishes to divert a file from another, it should + call dpkg-divert in its preinst to add the + diversion and rename the existing file. For example, + supposing that a smailwrapper package wishes to + install a wrapper around /usr/sbin/smail: + + if [ install = "$1" ]; then + dpkg-divert --package smailwrapper --add --rename \ + --divert /usr/sbin/smail.real /usr/sbin/smail + fi + Testing $1 is necessary so that the script + doesn't try to add the diversion again when + smailwrapper is upgraded. The --package + smailwrapper ensures that smailwrapper's + copy of /usr/sbin/smail can bypass the diversion and + get installed as the true version. +

+ +

+ The postrm has to do the reverse: + + if [ remove = "$1" ]; then + dpkg-divert --package smailwrapper --remove --rename \ + --divert /usr/sbin/smail.real /usr/sbin/smail + fi + +

+ +

+ Do not attempt to divert a file which is vitally important for + the system's operation - when using dpkg-divert + there is a time, after it has been diverted but before + dpkg has installed the new version, when the file + does not exist.

+ + + + Shared libraries + + +

+ 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. +

+ +

+ Firstly, your package should install the shared libraries + under their normal names. For example, the + libgdbm1 package should install + libgdbm.so.1.7.3 as + /usr/lib/libgdbm.so.1.7.3. The files should not be + renamed or relinked by any prerm or postrm scripts; + dpkg will take care of renaming things safely + without affecting running programs, and attempts to interfere + with this are likely to lead to problems. +

+ +

+ Secondly, your package should include the symlink that + ldconfig would create for the shared libraries. + For example, the libgdbm1 package should include + a symlink from /usr/lib/libgdbm.so.1 to + libgdbm.so.1.7.3. This is needed so that + ld.so can find the library in between the time + dpkg installs it and ldconfig is run + in the postinst script. Futhermore, and this + is very important, the library must be placed before the + symlink pointing to it in the .deb file. This is so + that by the time 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 + debian/tmp/.../lib directory before creating the + symlink, by putting the commands in the debian/rules + in the appropriate order. +

+ + + +

+ Thirdly, the development package should contain a symlink for + the shared library without a version number. For example, the + libgdbm1-dev package should include a symlink from + /usr/lib/libgdm.so to libgdm.so.1.7.3. This + symlink is needed by ld when compiling packages + as it will only look for libgdm.so and + libgdm.a when compiling dynamically or statically, + respectively. +

+ + + +

+ Any package installing shared libraries in a directory that's listed + in /etc/ld.so.conf or in one of the default library + directories of ld.so (currently, these are /usr/lib + and /lib) must call ldconfig in its postinst + script if and only if the first argument is `configure'. However, it + is important not to call ldconfig in the postrm or preinst + scripts in the case where the package is being upgraded (see ), as ldconfig will see the temporary names + that dpkg uses for the files while it is + installing them and will make the shared library links point + to them, just before dpkg continues the + installation and removes the links! +

+ + + + The shlibs File Format + + +

+ This file is for use by dpkg-shlibdeps and is + required when your package provides shared libraries. +

+ +

+ Each line is of the form: + + library-name version-or-soname dependencies ... + +

+ +

+ library-name is the name of the shared library, + for example libc5. +

+ +

+ version-or-soname is the soname of the library - + ie, the thing that must exactly match for the library to be + recognised by ld.so. Usually this is major + version number of the library. +

+ +

+ 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 . +

+ +

+ For example, if the package foo contains + libfoo.so.1.2.3, where the soname of the library is + libfoo.so.1, and the first version of the package + which contained a minor number of at least 2.3 was + 1.2.3-1, then the package's shlibs + could say: + + libfoo 1 foo (>= 1.2.3-1) + +

+ +

+ The version-specific dependency is to avoid warnings from + ld.so about using older shared libraries with + newer binaries.

+ + + Further Technical information on + shlibs + + + + + What are the shlibs files? + + +

+ The 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. +

+ +

+ Other shlibs files that exist on a Debian system are + +

/etc/dpkg/shlibs.default

+

/etc/dpkg/shlibs.override

 +

/var/lib/dpkg/info/*.shlibs

 +

debian/shlibs.local

 + + These files are used by dpkg-shlibdeps when + creating a binary package.

+ + + How does dpkg-shlibdeps + work? + + +

+ dpkg-shlibdeps calls ldd to + determine the shared libraries used by the compiled + binaries passed through its command line. +

+ +

+ For each shared library, dpkg-shlibdeps needs to know + +

the package containing the library, and

+

the library version number,

 + +

+ it scans the following files in this order. + +

debian/shlibs.local

+

/etc/dpkg/shlibs.override

 +

/var/lib/dpkg/info/*.shlibs

 +

/etc/dpkg/shlibs.default

 +

+ + + Who maintains the various + shlibs files? + + +

+ + +

/etc/dpkg/shlibs.default - the maintainer + of dpkg

+ + +

+ /var/lib/dpkg/info/package.shlibs + - the maintainer of each package

+ + +

+ /etc/dpkg/shlibs.override - the local + system administrator

+ + +

debian/shlibs.local - the maintainer of + the package +

+ + + The shlibs.default file is managed by + dpkg. The entries in shlibs.default + that are provided by dpkg are just there to + fix things until the shared library packages all have + shlibs files. +

+ + + How to use dpkg-shlibdeps and + the shlibs files? + + + If your package doesn't provide a shared + library + + +

+ Put a call to dpkg-shlibdeps into your + debian/rules file. If your package contains + only binaries (e.g. no scripts) use: + + dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* + + If dpkg-shlibdeps doesn't complain, you're + done. If it does complain you might need to create your + own debian/shlibs.local file.

+ + + If your package provides a shared library + + +

+ Create a debian/shlibs file and let + debian/rules install it in the control area: + + install -m644 debian/shlibs debian/tmp/DEBIAN + + If your package contains additional binaries see above. +

+ + + + How to write + debian/shlibs.local + + +

+ This file is intended only as a temporary fix if + your binaries depend on a library which doesn't provide + its own /var/lib/dpkg/*.shlibs file yet. +

+ +

+ Let's assume you are packaging a binary foo. Your + output in building the package might look like this. + + $ 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 + + And when you ran dpkg-shlibdeps + + $ 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) + + The foo binary depends on the + libbar shared library, but no package seems + to provide a *.shlibs file in + var/lib/dpkg/info/. Let's determine the package + responsible: +

+ +

+ + $ 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 + + This tells us that the bar1 package, version + 1.0-1 is the one we are using. Now we can create our own + debian/shlibs.local to temporarly fix the above + problem. Include the following line into your + debian/shlibs.local file. + + libbar 1 bar1 (>= 1.0-1) + + Now your package build should work. As soon as the + maintainer of libbar1 provides a + shlibs file, you can remove your + debian/shlibs.local file. +

+ + + + + dselect's interface to + its installation methods + + +

+ dselect calls scripts from its installation + methods when it needs to actually access data from the + distribution. The core program dselect itself + just calls these scripts and provides the package and access + method selection interfaces. The installation methods are + responsible for invoking dpkg as appropriate. +

+ +

+ Each installation method has three scripts: + +

Setup installation parameters.

+

Update list of available packages.

 +

Install.

 + + +

+ dselect searches for methods in + /usr/lib/dpkg/methods and + /usr/local/lib/dpkg/methods. +

+ + Functions of the method scripts + + +

+ 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 + .deb files can be found, or the tape or floppy + device to install from. It should store the responses under + /var/lib/dpkg/methods - see below. If no available + packages list is available it should perhaps offer to scan + the available packages. +

+ +

+ The update script should obtain a list of available packages + if possible, and run dpkg --update-avail, dpkg + --merge-avail and/or dpkg --forget-old-unavail + to load it into dpkg and 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 dpkg --record-avail. +

+ +

+ The install script should feed all the available + .deb files to dpkg --iGOEB (this is + equivalent to dpkg --install + --refuse-downgrade --selected-only --skip-same-version + --auto-deconfigure). The -R + (--recursive) option for traversing subdirectories + may also be useful here). +

+ +

+ 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. +

+ +

+ If a method script succeeds (returns a zero exit status) + dselect will return immediately to the main + menu, with the `next' option highlighted ready for the user + to select it. If it fails dselect will display + a message and wait for the user to hit return.

+ + + Location and arguments of the method scripts + + +

+ 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. +

+ +

+ Each group of methods implemented by the same set of scripts + should have a subdirectory + /usr/lib/dpkg/methods/group or + /usr/local/lib/dpkg/methods/group, + containing: + + names +

a list of user-visible methods provided by these scripts.

+ + setup + update + install +

executable programs, the scripts themselves.

+ + desc.option +

description file.

 + +

+ +

+ names will be formatted as a list of lines, each containing: + + sequence method summary + +

+

+ sequence is a two-digit number that will be used + much like rc.d prefixes to control the order in the + main menu. If in doubt use 50. +

+ +

+ method is a name which is displayed by + dselect as the name of the method, and which + will be passed to setup, update and + unpack as their first argument. +

+ +

+ summary is the brief description string for + dselect's menu. +

+ +

+ Each of the three scripts gets the same three arguments: + vardir, group and method. + vardir is the base directory for storing + dpkg and dselect's state, usually + /var/lib/dpkg; this is passed in so that the + --admindir option to dselect is + honoured). +

+ +

+ Each option may have an extended description in + desc.option. This should be formatted + like the extended description part of a Description + field entry shifted one character to the left. +

+ +

+ vardir/methods will exist, and a method + group may use a + vardir/methods/group + directory to store its state. +

+ +

+ The group name and method name must follow the rules for C + identifiers. +

+ + + + Conversion procedure from old + source packages + + +

+ This is a brief summary of the procedure for converting a + pre-2.0.0.0-format source package into the new format. +

+ +

+ You are strongly advised to download and examine the hello + package, and to read the section in the dpkg programmers' + manual describing the source packaging tools. More detail about the + exact functionality of these tools is available in + . +

+ +

+ + +

+ 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 + package-upstream-version.orig/ + or + package_upstream-version.orig.tar.gz. +

+ + + +

+ Rename all files debian.* to debian/*. + There may be some exceptions to this, but this is a good + start.

+ + + +

+ Edit the 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: + + Local variables: + mode: debian-changelog + End: + +

+ + + +

+ Edit/create debian/control: + + +

+ Remove the Version field. If it is + generated unusually (not equal to the source + version) you must use the -v option to + dpkg-gencontrol (see below). Section, + Priority, Maintainer go above + the first blank line, most of the rest + below. +

+ + + +

+ Reorder the fields and add a blank line at an + appropriate point, separating the source package + fields from the binary package fields. +

+ + + +

Add the Source field.

 + + +

+ Add the Standards-Version field. (Please + check out the Debian Policy Manual for details + about this field.)

+ + + +

+ Change the Architecture field for each + package to any, all or whatever. + If there isn't an Architecture field add + one.

+ + + +

+ If any other use of sed or things used to happen + to make the binary control files use + dpkg-gencontrol's variable + substitution features to achieve the same effect. + Use debian/substvars if you need to put + unusally-generated information (apart from details + of .deb files) in the .changes + file too.

+ + +

+ + + +

Edit the debian/rules: + + +

+ Remove the source and + diff and any changes and + dist targets. These things now + happen in a package-independent way and are not + done by debian/rules.

+ + +

+ Split the binary target into + binary-arch and + binary-indep; in many cases all of + binary should go into + binary-arch. Create the + binary target and the unused of the + two other binary-* targets if there + is one - you can copy the ones from the + hello package.

+ + +

+ Change the binary target to use + dpkg-gencontrol to make the package + control file(s). Move it to after all the files + have been installed but just before the last + chown and chmod in the + target.

+ + +

+ Change occurrences of debian-tmp to + debian/tmp.

+ + +

+ Change occurrences of + debian.{post,pre}{inst,rm} to + debian/*.

+ + +

+ Remove the version number setting at the top, if + there is one.

+ + +

+ Ensure that the package's Debian-specific and + upstream changelogs are installed.

+ + +

+ + + +

+ Change the package to use dpkg-shlibdeps to + determine its shared library dependencies and substitute + them in. Shared library dependencies should no longer + be hardwired in the source package.

+ + + +

+ Check that the debian/README is really the + copyright file, and if so rename it to + debian/copyright and edit debian/rules + to cope with this and to change the installation of the + copyright file from + /usr/doc/package/copyright to + /usr/doc/copyright/package. If it + isn't then find debian/copyright and decide + what to do with the README.

+ + + +

Check for various other anachronisms and problems: + + +

+ Remove any Package_Revision, + Package-Revision or Revision + fields.

+ + +

+ Rename Optional to Suggests, + Recommended to + Recommends.

+ + +

+ Change + /usr/doc/examples/package to + /usr/doc/package/examples.

+ + +

+ Make sure that manpages are installed + compressed.

+ + +

+ 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.

+ + +

+ + + +

Look everything over.

 + + +

+ Do a test build using dpkg-buildpackage -us -uc -sa + -rwhatever. Check the permissions and + locations of files in the resulting package by examining + the output of dpkg-deb --contents, and check + that the source build happened OK. Test install the + binary package(s) and test extract the source + package(s).

+ + + +

+ Sign the release: either rebuild everything with + dpkg-buildpackage -sa, or PGP-sign the + .dsc, rebuild the .changes using + dpkg-genchanges -sa, and then PGP-sign the + .changes.

+ + + +

+ +

+ The use of -sa on dpkg-buildpackage and + dpkg-genchanges is important when doing the first + build/uploading of a new-format source package. Unless this + happens to be Debian revision 0 or 1 by + default the original source tarfile will not be included in + the uploaded files listed in the .changes file, and + so it won't be installed on the FTP site. -sa + requests that the original source be included + regardless.

+ + + + - -The package's files are removed (except conffiles). - - - - -All the maintainer scripts except the postrm are removed. -

-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 -The conffiles and any backup files ( - - - -The package's file list is removed. - -No attempt is made to unwind after errors during removal. -Descriptions of packages - the - -The -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. -

-The field's format is as follows: - -Description: -

- -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. -

- -Types of formatting line in the extended description -

- - - -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. - - -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). - - -Those containing a single space followed by a single full stop -character. These are rendered as blank lines. This is the -Those containing a space, a full stop and some more characters. These -are for future expansion. Do not use them. - - -Notes about writing descriptions -

- -Version 0.93.23 or -later. to produce a syntax error when trying to build the -package. If you force it to build anyway - -debian/control file, and are forbidden in package control -files. See the previous paragraph for what happens if you get this -wrong. -

- -The single line synopsis should be kept brief - certainly under 80 -characters. - -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. -

- -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). -

- -The blurb that comes with a program in its announcements and/or - - -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. -

- -You may include information about dependencies and so forth in the -extended description, if you wish. -

- -Do not use tab characters. Their effect is not predictable. -

- -Do not try to linewrap the summary (the part on the same line as the -field name Example description in control file for Smail -

- -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. - -Declaring relationships between packages -

- -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. -

- -This is done using the - -Syntax of relationship fields -

- -These fields all have a uniform syntax. They are a list of package -names separated by commas. -

- -In - -All the fields except . -

- -The relations allowed are - - -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 - - -For example: - -Package: metamail -Version: 2.7-3 -Depends: libc5 (>= 5.2.18-4), mime-support, csh | tcsh - -Dependencies - - -These four fields are used to declare a dependency by one package on -another. They appear in the depending package's control file. -

- -All but - -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. -

- -Thus - - -This declares an absolute dependency. -

- -Current versions -(1.2.4) of , unless - - - - -The -This declares a strong, but not absolute, dependency. -

- - - -It is treated by - -The - -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. -

- - - -This field is like - - - -However, this process is slow (because it requires repeated -invocations of - -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), - -When the package declaring it is being configured, a - - -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 - -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 Dependencies on shared libraries -

- -The dependency fields listed above are used by packages which need -shared libraries to declare dependencies on the appropriate packages. -

- -These dependencies are usually determined automatically using - and . - -Deconfiguration due to removal during bulk installations -

- -If - -However, if the - -Alternative packages - - -When one package declares a conflict with another - -If one package is to be installed, the other must be removed first - -if the package being installed is marked as replacing () the one on the system, or the one on the system is -marked as deselected, or both packages are marked - - - -A package will not cause a conflict merely because its configuration -files are still installed; it must be at least half-installed. -

- -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. -

- -A - - -Virtual packages - - -As well as the names of actual (`concrete') packages, the package -relationship fields - -A virtual package is one which appears in the - -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 - -Package: vm -Depends: emacs - -and someone else releases an xemacs package they can say - -Package: xemacs -Provides: emacs - -and all will work in the interim (until a purely virtual package name -is decided on and the - -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 - -It is likely that the ability will be added in a future release of - - -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. -

- - - - -The - -Virtual packages () are not considered when looking -at a Overwriting files in other packages -

- -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 - -If the overwriting package declares that it replaces the one -containing the file being overwritten then - -If a package is completely replaced in this way, so that . -

- -In the future - -This usage of Replacing whole packages, forcing their removal -

- -Secondly, . This usage only takes effect when the two -packages - -Defaults for satisfying dependencies - ordering -

- -Ordering is significant in dependency fields. -

- -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. -

- -In the absence of other information - -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. -

- -Therefore a dependency on a virtual package should contain a concrete -package name as the first alternative, so that this is the default. -

- -For example, consider the set of packages: - -Package: glibcdoc -Recommends: info-browser -Package: info -Provides: info-browser -Package: emacs -Provides: info-browser - -

-If -Package: glibcdoc -Recommends: info | info-browser - -so that Configuration file handling -

- - - -Whether this mechanism is appropriate depends on a number of factors, -but basically there are two approaches to any particular configuration -file. -

- -The easy method is to ship a best-effort configuration in the package, -and use - -The hard method is to build the configuration file from scratch in the -Automatic handling of configuration files by - -A package may contain a control area file called - -When a package is upgraded - -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. -

- -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. -

- -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. -

- -When a package is installed for the first time - -However, note that - -Note that a package should Fully-featured maintainer script configuration handling -

- -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 - -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. -

- -When using this method there are a couple of important issues which -should be considered: -

- -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. -

- -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 -/usr/sbin, by convention called Alternative versions of an interface - - - -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. -

- -For example, there are several versions of the - -If all the packages involved cooperate, this can be done with - - -Each package provides its own version under its own name, and calls - - -See the manpage for -details. -

- -If Diversions - overriding a package's version of a file -

- -It is possible to have - -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). -

- -Before deciding to use a diversion, read to -see if you really want a diversion rather than several alternative -versions of a program. -

- -There is a diversion list, which is read by for full details of its operation. -

- -When a package wishes to divert a file from another, it should call -/usr/sbin/smail: - -if [ install = "$1" ]; then - dpkg-divert --package smailwrapper --add --rename \ - --divert /usr/sbin/smail.real /usr/sbin/smail -fi - -Testing /usr/sbin/smail can bypass the diversion and get installed as -the true version. -

- -The postrm has to do the reverse: - -if [ remove = "$1" ]; then - dpkg-divert --package smailwrapper --remove --rename \ - --divert /usr/sbin/smail.real /usr/sbin/smail -fi - -

- -Do not attempt to divert a file which is vitally important for the -system's operation - when using Shared libraries -

- -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. -

- -Firstly, your package should install the shared libraries under their -normal names. For example, the /usr/lib/libgdbm.so.1.7.3. The -files should not be renamed or relinked by any prerm or postrm -scripts; - -Secondly, your package should include the symlink that /usr/lib/libgdbm.so.1 to debian/tmp/.../lib -directory before creating the symlink, by putting the commands in the -debian/rules in the appropriate order. -

- - - -Thirdly, the development package should contain a symlink for the -shared library without a version number. For example, the -/usr/lib/libgdm.so to - - - -Any package installing shared libraries in a directory that's listed -in /etc/ld.so.conf or in one of the default library -directories of /usr/lib -and /lib) must call ), as - - - -The - -This file is for use by - -Each line is of the form: - - -

- - - - - -. -

- -For example, if the package -libfoo 1 foo (>= 1.2.3-1) - -

- -The version-specific dependency is to avoid warnings from Further Technical information on - - - - - -The 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. -

- -Other - /etc/dpkg/shlibs.default - /etc/dpkg/shlibs.override - /var/lib/dpkg/info/*.shlibs - debian/shlibs.local - - -These files are used by - - - -For each shared library, -the package containing the library, and -the library version number, - -

-it scans the following files in this order. - -debian/shlibs.local -/etc/dpkg/shlibs.override -/var/lib/dpkg/info/*.shlibs -/etc/dpkg/shlibs.default - - - - - -/etc/dpkg/shlibs.default - the maintainer of dpkg -/var/lib/dpkg/info/ - the maintainer of each -package -/etc/dpkg/shlibs.override - the local system administrator -debian/shlibs.local - the maintainer of the package - - -The If your package doesn't provide a shared library -

- -Put a call to debian/rules file. -If your package contains only binaries (e.g. no scripts) use: - -dpkg-shlibdeps debian/tmp/usr/{bin,sbin}/* - - -If debian/shlibs.local -file. - -If your package provides a shared library -

- -Create a debian/shlibs file and let debian/rules install -it in the control area: - - -install -m644 debian/shlibs debian/tmp/DEBIAN - - -If your package contains additional binaries see above. - -debian/shlibs.local -

- -This file is intended only as a /var/lib/dpkg/*.shlibs file yet. -

- -Let's assume you are packaging a binary -$ 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 - - -And when you ran -$ 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) - - -The - - -$ 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 - - -This tells us that the debian/shlibs.local to -temporarly fix the above problem. Include the following line into your -debian/shlibs.local file. - - - libbar 1 bar1 (>= 1.0-1) - - -Now your package build should work. As soon as the maintainer of -debian/shlibs.local file. - - - - - -Each installation method has three scripts: - -Setup installation parameters. -Update list of available packages. -Install. - -

- -/usr/lib/dpkg/methods -and /usr/local/lib/dpkg/methods. - -Functions of the method scripts -

- -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 /var/lib/dpkg/methods - see below. If no available -packages list is available it should perhaps offer to scan the -available packages. -

- -The update script should obtain a list of available packages if -possible, and run - -The install script should feed all the available - -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. -

- -If a method script succeeds (returns a zero exit status) -Location and arguments of the method scripts -

- -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. -

- -Each group of methods implemented by the same set of scripts should -have a subdirectory /usr/lib/dpkg/methods/ or -/usr/local/lib/dpkg/methods/, containing: - -a list of user-visible methods provided by these scripts. -executable programs, the scripts themselves. -description file. - -

- - - -

- - - - - - - -Each of the three scripts gets the same three arguments: /var/lib/dpkg; this is passed in so that the - -Each option may have an extended description in - - - will exist, and a method group may use a - directory to store its state. -

- -The group name and method name must follow the rules for C identifiers. - -Conversion procedure from old source packages -

- -This is a brief summary of the procedure for converting a -pre-2.0.0.0-format source package into the new format. -

- -You are strongly advised to download and examine the . -

- - - - -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 - or - -Rename all files debian/*. There may be some -exceptions to this, but this is a good start. - - -Edit the 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: - -Local variables: -mode: debian-changelog -End: - - -Edit/create debian/control: - - -Remove the -Reorder the fields and add a blank line at an appropriate point, -separating the source package fields from the binary package -fields. - - -Add the -Add the -Change the -If any other use of sed or things used to happen to make the binary -control files use debian/substvars if -you need to put unusally-generated information (apart from details of - - - -Edit the debian/rules: - - -Remove the debian/rules. - -Split the -Change the -Change occurrences of debian/tmp. - -Change occurrences of debian/*. - -Remove the version number setting at the top, if there is one. - -Ensure that the package's Debian-specific and upstream changelogs are -installed. - - - -Change the package to use -Check that the debian/README is really the copyright file, and -if so rename it to debian/copyright and edit -debian/rules to cope with this and to change the installation -of the copyright file from /usr/doc/ -to /usr/doc/copyright/. If it isn't then -find debian/copyright and decide what to do with the -README. - - -Check for various other anachronisms and problems: - - -Remove any -Rename -Change /usr/doc/examples/ to -/usr/doc/. - -Make sure that manpages are installed compressed. - -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. - - - -Look everything over. - - -Do a test build using -Sign the release: either rebuild everything with -

- -The use of -- 2.39.5