<prgn/dpkg/ programmers' manual <author>Ian Jackson <email/ijackson@gnu.ai.mit.edu/ <version><date> <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. 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. You should have received a copy of the GNU General Public License with your Debian GNU/Linux system, in <tt>/usr/doc/copyright/GPL</tt>, or with the <prgn/dpkg/ source package as the file <tt>COPYING</tt>. If not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. <toc sect>  <chapt id="scope">Introduction and scope of this manual <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> 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 (<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. 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. 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 <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. 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.) It is assumed that the reader is reasonably familiar with the <prgn/dpkg/ System Administrators' manual. The Debian version of the FSF's GNU hello program is provided as an example for people wishing to create Debian packages. Note that this document is still a draft! <chapt id="binarypkg">Binary packages 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">. The second part is an archive (currently a <prgn/tar/ archive) containing files and directories to be installed. In the future binary packages may also contain other components, such as checksums and digital signatures. <sect id="bincreating">Creating package files - <prgn/dpkg-deb/ 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.) 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. 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 <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. 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">). 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. When you've prepared the package, you should invoke: <example> dpkg --build <var/directory/ </example> 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.) 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 </example> <sect id="controlarea">Package control information files 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. 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 <prgn/dpkg/ and a summary of what they're used for. <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">. <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">. It is very important to make these scripts itempotent.<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. 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. 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. </taglist> <sect id="controlfile">The main control information file: <tt/control/ 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'. 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. 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/</> </list> 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 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. 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. See <manref name=dpkg-source section=1> for details. <sect>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 <tt/debian/ of the top level of the Debianised source tree. They are described below. <sect1><tt>debian/rules</tt> - 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 <tt>#!/usr/bin/make -f</tt>, so that it can be invoked by saying its name rather than invoking <prgn/make/ explicitly. 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. 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. The <prgn/build/ target must not do anything that might require root privilege. The <prgn/build/ target may need to run <prgn/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 <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// <item> This target should be all that is necessary for the user to build the binary package. It 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 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. <ref id="binarypkg"> describes how to construct binary packages. The <prgn/binary/ target 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/. 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. 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// <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. 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. </taglist> The <prgn/build/, <prgn/binary/ and <prgn/clean/ targets must be invoked with a current directory of the package's top-level directory. 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> 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 <ref id="controlfields">. 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> 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> 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. 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. <sect2>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 <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. 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</> 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>. 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: <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> <var/package/ and <var/version/ are the source package name and version number. <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">. <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/). 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 <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. The <var/date/ should be in RFC822 format; 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 <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 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 <tt/dpkg-parsechangelog/ run your parser, you must include a line within the last 40 lines of your file matching the Perl regular expression: <example> \schangelog-format:\s+([0-9a-z]+)\W </example> The part in parentheses should be the name of the format. 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. 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. 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> 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. For the format of the <tt/Changes/ field see <ref id="f-Changes">. 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. <sect1 id="srcsubstvars"><tt>debian/substvars</> and variable substitutions 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. The file may be a static part of the source archive, or generated and modified dynamically by <tt>debian/rules</> targets. In the latter case it must be removed by the <prgn/clean/ target. 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</> 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. 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. <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/. 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</> 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">. 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/. 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 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. <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> 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/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. 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. The <prgn/dpkg-source/ program will automatically make the <tt>debian/rules</tt> file executable (see below). </taglist> 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/ <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> 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 The source package may not contain any device special files, sockets or setuid or setgid files.<footnote>Setgid directories are allowed.</footnote> 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> </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> 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 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 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 <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. 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 <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/ 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> 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/ This lists the source or binary package's version number - see <ref id="versions">. <sect1 id="f-Architecture"><tt/Architecture/ This is the architecture string; it is a single word for the CPU architecture. <prgn/dpkg/ will check the declared architecture of a binary package against its own compiled-in value before it installs it. The special value <tt/all/ indicates that the package is architecture-independent. 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. 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. 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/. 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/ The package maintainer's name and email address. The name should come first, then the email address inside angle brackets <tt/<>/ (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 <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. 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/ This field identifies the source package name. 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. 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/ 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/ 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. 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/ 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. 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/ 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. 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. 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. 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. 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/ This field is a list of binary packages. 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. When it appears in a <tt/.changes/ file it lists the names of the binary packages actually being uploaded. 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-Files"><tt/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 <tt/.dsc/ (Debian source control) file each line contains the MD5 checksum, size and filename of the tarfile and (optionally) 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">. 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. The special value <tt/byhand/ for the section 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/-/. <sect1 id="f-Standards-Version"><tt/Standards-Version/ 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. 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/ 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">). Current distribution values are <tt/stable/, <tt/unstable/, <tt/contrib/, <tt/non-free/ and <tt/experimental/. <sect1 id="f-Urgency"><tt/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 <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> 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">). Urgency keywords are not case-sensitive. <sect1 id="f-Date"><tt/Date/ In <tt/.changes/ files and parsed changelogs, this gives the date the package was built or last edited. <sect1 id="f-Format"><tt/Format/ 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/ 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. 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). <sect1 id="f-Filename"><tt/Filename/ and <tt/MSDOS-Filename/ 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/ 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/ 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/ 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/ 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 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 Every package has a version number, in its <tt/Version/ control file field. <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. The version number format is: &lsqb<var/epoch/<tt/:/]<var/upstream-version/[<tt/-/<var/debian-revision/]. 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. 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. <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. 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. 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. 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. It is conventional to restart the <var/debian-revision/ at <tt/1/ each time the <var/upstream-version/ is increased. <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). 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: 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 <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). If an upstream package has problematic version numbers they should be converted to a sane form for use in the <tt/Version/ field. <chapt id="maintainerscripts">Package maintainer scripts and installation procedure <sect>Introduction to package maintainer scripts 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. 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. <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. 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 <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. <sect id="mscriptsinstact">Summary of ways maintainer scripts are called <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> <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> <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> <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>Details of unpack phase of installation or upgrade 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). 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. 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> <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 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/ </example> No attempt is made to unwind after errors during configuration. If there is no most recently configured version <prgn/dpkg/ will pass a null argument; older versions of dpkg may pass <tt><unknown></tt> (including the angle brackets) in this case. Even older ones do not pass a second argument at all, under any circumstances. <sect>Details of removal and/or configuration purging <enumlist> <item> <example> <var/prerm/ remove </example> <item> The package's files are removed (except conffiles). <item> <example> <var/postrm/ remove </example> <item> All the maintainer scripts except the postrm are removed. If we aren't purging the package we stop here. Note that packages which have no postrm and no conffiles are automatically purged when removed, as there is no difference except for the <prgn/dpkg/ status. <item> The conffiles and any backup files (<tt/~/-files, <tt/#*#/ files, <tt/%/-files, <tt/.dpkg-{old,new,tmp}/, etc.) are removed. <item> <example> <var/postrm/ purge </example> <item> The package's file list is removed. </enumlist> No attempt is made to unwind after errors during removal. <chapt id="descriptions">Descriptions of packages - the <tt/Description/ field The <tt/Description/ control file field is used by <prgn/dselect/ when the user is selecting which packages to install and by <prgn/dpkg/ when it displays information about the status of packages and so forth. It is included on the FTP site in the <prgn/Packages/ files, and may also be used by the Debian WWW pages. 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: <example> Description: <var/single line synopsis/ <var/extended description over several lines/ </example> 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. <sect>Types of formatting line in the extended description <list> <item> Those starting with a single space are part of a paragraph. Successive lines of this form will be word-wrapped when displayed. The leading space will usually be stripped off. <item> Those starting with two or more spaces. These will be displayed verbatim. If the display cannot be panned horizontally the displaying program will linewrap them `hard' (ie, without taking account of word breaks). If it can they will be allowed to trail off to the right. None, one or two initial spaces may be deleted, but the number of spaces deleted from each line will be the same (so that you can have indenting work correctly, for example). <item> Those containing a single space followed by a single full stop character. These are rendered as blank lines. This is the <em/only/ way to get a blank line - see below. <item> Those containing a space, a full stop and some more characters. These are for future expansion. Do not use them. </list> <sect>Notes about writing descriptions <em/Always/ start extended description lines with at least one whitespace character. Fields in the control file and in the Packages file are separated by field names starting in the first column, just as message header fields are in RFC822. Forgetting the whitespace will cause <prgn/dpkg-deb/<footnote>Version 0.93.23 or later.</footnote> to produce a syntax error when trying to build the package. If you force it to build anyway <prgn/dpkg/ will refuse to install the resulting mess. <em/Do not/ include any completely <em/empty/ lines. These separate different records in the Packages file and different packages in the <tt>debian/control</> file, and are forbidden in package control files. See the previous paragraph for what happens if you get this wrong. The single line synopsis should be kept brief - certainly under 80 characters. <prgn/dselect/ displays between 25 and 49 characters without panning if you're using an 80-column terminal, depending on what display options are in effect. 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 <prgn/README/ files is rarely suitable for use in a description. It is usually aimed at people who are already in the community where the package is used. The description field needs to make sense to anyone, even people who have no idea about any of the things the package deals with. 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 <tt/Description/) into the extended description. This will not work correctly when the full description is displayed, and makes no sense where only the summary is available. <sect>Example description in control file for Smail <example> Package: smail Version: 3.1.29.1-13 Maintainer: Ian Jackson <iwj10@cus.cam.ac.uk> Recommends: pine | mailx | elm | emacs | mail-user-agent Suggests: metamail Depends: cron, libc5 Conflicts: sendmail Provides: mail-transport-agent Description: Electronic mail transport system. Smail is the recommended mail transport agent (MTA) for Debian. . An MTA is the innards of the mail system - it takes messages from user-friendly mailer programs and arranges for them to be delivered locally or passed on to other systems as required. . In order to make use of it you must have one or more user level mailreader programs such as elm, pine, mailx or Emacs (which has Rmail and VM as mailreaders) installed. If you wish to send messages other than just to other users of your system you must also have appropriate and VM as mailreaders) installed. If you wish to send messages other than just to other users of your system you must also have appropriate networking support, in the form of IP or UUCP. </example> <chapt id="relationships">Declaring relationships between packages 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 <tt/Depends/, <tt/Recommends/, <tt/Suggests/, <tt/Conflicts/, <tt/Provides/ and <tt/Replaces/ control file fields. <sect>Syntax of relationship fields These fields all have a uniform syntax. They are a list of package names separated by commas. In <tt/Depends/, <tt/Recommends/, <tt/Suggests/ and <tt/Pre-Depends/ (the fields which declare dependencies of the package in which they occur on other packages) these package names may also be lists of alternative package names, separated by vertical bar symbols <tt/|/ (pipe symbols). All the fields except <tt/Provides/ may restrict their applicability to particular versions of each named package. This is done in parentheses after each individual package name; the parentheses should contain a relation from the list below followed by a version number, in the format described in <ref id="versions">. The relations allowed are <tt/<</, <tt/<=/, <tt/=/, <tt/>=/ and <tt/>>/ for strictly earlier, earlier or equal, exactly equal, later or equal and strictly later, respectively. The forms <tt/</ and <tt/>/ were used to mean earlier/later or equal, rather than strictly earlier/later, so they should not appear in new packages (though <prgn/dpkg/ still supports them). Whitespace may appear at any point in the version specification, and must appear where it's necessary to disambiguate; it is not otherwise significant. For consistency and in case of future changes to <prgn/dpkg/ it is recommended that a single space be used after a version relationship and before a version number; it is usual also to put a single space after each comma, on either side of each vertical bar, and before each open parenthesis. For example: <example> Package: metamail Version: 2.7-3 Depends: libc5 (>= 5.2.18-4), mime-support, csh | tcsh </example> <sect>Dependencies - <tt/Depends/, <tt/Recommends/, <tt/Suggests/, <tt/Pre-Depends/ 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 <tt/Pre-Depends/ (discussed below) take effect <em/only/ when a package is to be configured. They do not prevent a package being on the system in an unconfigured state while its dependencies are unsatisfied, and it is possible to replace a package whose dependencies are satisfied and which is properly installed with a different version whose dependencies are not and cannot be satisfied; when this is done the depending package will be left unconfigured (since attempts to configure it will give errors) and will not function properly. 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 <tt/Depends/ allows package maintainers to impose an order in which packages should be configured. <taglist> <tag><tt/Depends/ <item> This declares an absolute dependency. <prgn/dpkg/ will not configure packages whose dependencies aren't satisfied. If it is asked to make an installation which would cause an installed package's dependencies to become unsatisfied it will complain<footnote>Current versions (1.2.4) of <prgn/dpkg/ have a bug in this area which will cause some of these problems to be ignored.</footnote>, unless <tt/--auto-deconfigure/ is specified, in which case those packages will be deconfigured before the installation proceeds. <prgn/dselect/ makes it hard for the user to select packages for installation, removal or upgrade in a way that would mean that packages' <prgn/Depends/ fields would be unsatisfied. The user can override this if they wish, for example if they know that <prgn/dselect/ has an out-of-date view of the real package relationships. The <tt/Depends/ field should be used if the depended-on package is required for the depending package to provide a significant amount of functionality. <tag><tt/Recommends/ <item> This declares a strong, but not absolute, dependency. <tt/Recommends/ is ignored by <prgn/dpkg/, so that users using the command-line (who are presumed to know what they're doing) will not be impeded. It is treated by <prgn/dselect/ exactly as <tt/Depends/ is; this makes it hard for the user to select things so as to leave <tt/Recommends/ fields unsatisfied, but they are able to do so by being persistent. The <tt/Recommends/ field should list packages that would be found together with this one in all but unusual installations. <tag><tt/Suggests/ <item> This is used to declare that one package may be more useful with one or more others. Using this field tells the packaging system and the user that the listed packages are be related to this one and can perhaps enhance its usefulness, but that installing this one without them is perfectly reasonable. <prgn/dselect/ will offer suggsted packages to the system administrator when they select the suggesting package, but the default is not to install the suggested package. <tag><tt/Pre-Depends/ <item> This field is like <tt/Depends/, except that it also forces <prgn/dpkg/ to complete installation of the packages named before even starting the installation of the package which declares the predependency. <prgn/dselect/ checks for predependencies when it is doing an installation run, and will attempt to find the packages which are required to be installed first and do so in the right order. However, this process is slow (because it requires repeated invocations of <prgn/dpkg/) and troublesome (because it requires guessing where to find the appropriate files). For these reasons, and because this field imposes restrictions on the order in which packages may be unpacked (which can be difficult for installations from multipart media, for example), <tt/Pre-Depends/ should be used sparingly, preferably only by packages whose premature upgrade or installation would hamper the ability of the system to continue with any upgrade that might be in progress. When the package declaring it is being configured, a <tt/Pre-Dependency/ will be considered satisfied only if the depending package has been correctly configured, just as if an ordinary <tt/Depends/ had been used. However, when a package declaring a predependency is being unpacked the predependency can be satisfied even if the depended-on package(s) are only unpacked or half-configured, provided that they have been configured correctly at some point in the past (and not removed or partially removed since). In this case both the previously-configured and currently unpacked or half-configured versions must satisfy any version clause in the <tt/Pre-Depends/ field. </taglist> <sect1>Deconfiguration due to removal during bulk installations If <prgn/dpkg/ would like to remove a package due to a conflict, as described above, but this would violate a dependency of some other package on the system, <prgn/dpkg/ will usually not remove the conflicting package and halt with an error. However, if the <tt/--auto-deconfigure/ (<tt/-B/) option is used <prgn/dpkg/ will automatically `deconfigure' the package with the problematic dependency, so that the conflicting package can be removed and the package we're trying to install can be installed. If <prgn/dpkg/ is being asked to install packages (rather than just unpacking them) it will try to reconfigure the package when it has unpacked all its arguments, in the hope that one of the other packages it is installing will satisfy the problematic dependency. <prgn/dselect/ supplies this argument to <prgn/dpkg/ when it invokes it, so that bulk installations proceed smoothly. <sect id="conflicts">Alternative packages - <tt/Conflicts/ and <tt/Replaces/ When one package declares a conflict with another <prgn/dpkg/ will refuse to allow them to be installed on the system at the same time. If one package is to be installed, the other must be removed first - if the package being installed is marked as replacing (<ref id="replaces">) the one on the system, or the one on the system is marked as deselected, or both packages are marked <tt/Essential/, then <prgn/dpkg/ will automatically remove the package which is causing the conflict, otherwise it will halt the installation of the new package with an error. <prgn/dselect/ makes it hard to select conflicting packages, though the user can override this if they wish. If they do not override it then <prgn/dselect/ will select one of the packages for removal, and the user must make sure it is the right one. In the future <prgn/dselect/ will look for the presence of a <tt/Replaces/ field to help decide which package should be installed and which removed. 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 <tt/Conflicts/ entry should almost never have an `earlier than' version clause. This would prevent <prgn/dpkg/ from upgrading or installing the package which declared such a conflict until the upgrade or removal of the conflicted-with package had been completed. This aspect of installation ordering is not handled by <prgn/dselect/, so that the use <tt/Conflicts/ in this way is likely to cause problems for `bulk run' upgrades and installations. <sect id="virtual">Virtual packages - <tt/Provides/ As well as the names of actual (`concrete') packages, the package relationship fields <tt/Depends/, <tt/Recommends/, <tt/Suggests/ and <tt/Conflicts/ may mention virtual packages. A virtual package is one which appears in the <tt/Provides/ control file field of another package. The effect is as if the package(s) which provide a particular virtual package name had been listed by name everywhere were the virtual package name appears. If there are both a real and a virtual package of the same name then the dependency may be satisfied (or the conflict caused) by either the real package or any of the virtual packages which provide it. This is so that, for example, supposing we have <example> Package: vm Depends: emacs </example> and someone else releases an xemacs package they can say <example> Package: xemacs Provides: emacs </example> and all will work in the interim (until a purely virtual package name is decided on and the <tt/emacs/ and <tt/vm/ packages are changed to use it). If a dependency or a conflict has a version number attached then only real packages will be considered to see whether the relationship is satisfied (or the prohibition violated, for a conflict) - it is assumed that a real package which provides virtual package is not of the `right' version. So, a <tt/Provides/ field may not contain version numbers, and the version number of the concrete package which provides a particular virtual package will not be looked at when considering a dependency on or conflict with the virtual package name. 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. <sect id="replaces"><tt/Replaces/ - overwriting files and replacing packages The <tt/Replaces/ control file field has two purposes, which come into play in different situations. Virtual packages (<ref id="virtual">) are not considered when looking at a <tt/Replaces/ field - the packages declared as being replaced must be mentioned by their real names. <sect1>Overwriting files in other packages Firstly, as mentioned before, it is usually an error for a package to contains files which are on the system in another package, though currently the <tt/--force-overwrite/ flag is enabled by default, downgrading the error to a warning, If the overwriting package declares that it replaces the one containing the file being overwritten then <prgn/dpkg/ will proceed, and replace the file from the old package with that from the new. The file will no longer be listed as `owned' by the old package. If a package is completely replaced in this way, so that <prgn/dpkg/ does not know of any files it still contains, it is considered to have disappeared. It will be marked as not wanted on the system (selected for removal) and not installed. Any conffiles details noted in the package will be ignored, as they will have been taken over by the replacing package(s). The package's <prgn/postrm/ script will be run to allow the package to do any final cleanup required. See <ref id="mscriptsinstact">. In the future <prgn/dpkg/ will discard files which overwrite those from another package which declares that it replaces the one being installed (so that you can install an older version of a package without problems). This usage of <tt/Replaces/ only takes effect when both packages are at least partially on the system at once, so that it can only happen if they do not conflict or if the conflict has been overridden. <sect1>Replacing whole packages, forcing their removal Secondly, <tt/Replaces/ allows <prgn/dpkg/ and <prgn/dselect/ to resolve which package should be removed when a conflict - see <ref id="conflicts">. This usage only takes effect when the two packages <em/do/ conflict, so that the two effects do not interfere with each other. <sect>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 <prgn/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: <example> Package: glibcdoc Recommends: info-browser Package: info Provides: info-browser Package: emacs Provides: info-browser </example> If <prgn/emacs/ and <prgn/info/ both have the same priority then <prgn/dselect/'s choice is essentially random. Better would be <example> Package: glibcdoc Recommends: info | info-browser </example> so that <prgn/dselect/ defaults to selecting the lightweight standalone info browser. <chapt id="conffiles">Configuration file handling <prgn/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 <prgn/dpkg/'s conffile mechanism to handle updates. If the user is unlikely to want to edit the file, but you need them to be able to without losing their changes, and a new package with a changed version of the file is only released infrequently, this is a good approach. The hard method is to build the configuration file from scratch in the <prgn/postinst/ script, and to take the responsibility for fixing any mistakes made in earlier versions of the package automatically. This will be appropriate if the file is likely to need to be different on each system. <sect>Automatic handling of configuration files by <prgn/dpkg/ A package may contain a control area file called <tt/conffiles/. This file should be a list of filenames of configuration files needing automatic handling, separated by newlines. The filenames should be absolute pathnames, and the files referred to should actually exist in the package. When a package is upgraded <prgn/dpkg/ will process the configuration files during the configuration stage, shortly before it runs the package's <prgn/postinst/ script, 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 <prgn/dpkg/ will install the file that comes with it, unless that would mean overwriting a file already on the filesystem. However, note that <prgn/dpkg/ will <em/not/ replace a conffile that was removed by the user (or by a script). This is necessary because with some programs a missing file produces an effect hard or impossible to achieve in another way, so that a missing file needs to be kept that way if the user did it. Note that a package should <em/not/ modify a <prgn/dpkg/-handled conffile in its maintainer scripts. Doing this will lead to <prgn/dpkg/ giving the user confusing and possibly dangerous options for conffile update when the package is upgraded. <sect>Fully-featured maintainer script configuration handling For files which contain site-specific information such as the hostname and networking details and so forth, it is better to create the file in the package's <prgn/postinst/ script. 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 <tt>/usr/sbin</>, by convention called <tt/<var/package/config/ and then run that if appropriate from the post-installation script. The <tt/<var/package/config/ program should not unquestioningly overwrite an existing configuration - if its mode of operation is geared towards setting up a package for the first time (rather than any arbitrary reconfiguration later) you should have it check whether the configuration already exists, and require a <tt/--force/ flag to overwrite it. <chapt id="alternatives">Alternative versions of an interface - <prgn/update-alternatives/ 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 <prgn/vi/ editor, and there is no reason to prevent all of them from being installed at once, each under their own name (<prgn/nvi/, <prgn/vim/ or whatever). Nevertheless it is desirable to have the name <tt/vi/ refer to something, at least by default. If all the packages involved cooperate, this can be done with <prgn/update-alternatives/. Each package provides its own version under its own name, and calls <prgn/update-alternatives/ in its postinst to register its version (and again in its prerm to deregister it). See the manpage <manref name=update-alternatives section=8> for details. If <prgn/update-alternatives/ does not seem appropriate you may wish to consider using diversions instead. <chapt id="diversions">Diversions - overriding a package's version of a file It is possible to have <prgn/dpkg/ not overwrite a file when it reinstalls the package it belongs to, and to have it put the file from the package somewhere else instead. 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 <ref id="alternatives"> 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 <prgn/dpkg/, and updated by a special program <prgn/dpkg-divert/. Please see <manref name=dpkg-divert section=8> for full details of its operation. When a package wishes to divert a file from another, it should call <prgn/dpkg-divert/ in its preinst to add the diversion and rename the existing file. For example, supposing that a <prgn/smailwrapper/ package wishes to install a wrapper around <tt>/usr/sbin/smail</>: <example> if [ install = "$1" ]; then dpkg-divert --package smailwrapper --add --rename \ --divert /usr/sbin/smail.real /usr/sbin/smail fi </example> Testing <tt/$1/ is necessary so that the script doesn't try to add the diversion again when <prgn/smailwrapper/ is upgraded. The <tt/--package smailwrapper/ ensures that <prgn/smailwrapper/'s copy of <tt>/usr/sbin/smail</> can bypass the diversion and get installed as the true version. The postrm has to do the reverse: <example> if [ remove = "$1" ]; then dpkg-divert --package smailwrapper --remove --rename \ --divert /usr/sbin/smail.real /usr/sbin/smail fi </example> Do not attempt to divert a file which is vitally important for the system's operation - when using <prgn/dpkg-divert/ there is a time, after it has been diverted but before <prgn/dpkg/ has installed the new version, when the file does not exist. <chapt id="sharedlibs">Shared libraries 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 <prgn/libgdbm1/ package should install <tt/libgdbm.so.1.7.3/ as <tt>/usr/lib/libgdbm.so.1.7.3</tt>. The files should not be renamed or relinked by any prerm or postrm scripts; <prgn/dpkg/ will take care of renaming things safely without affecting running programs, and attempts to interfere with this are likely to lead to problems. Secondly, your package should include the symlink that <prgn/ldconfig/ would create for the shared libraries. For example, the <prgn/libgdbm1/ package should include a symlink from <tt>/usr/lib/libgdbm.so.1</tt> to <tt/libgdbm.so.1.7.3/. This is needed so that <prgn/ld.so/ can find the library in between the time <prgn/dpkg/ installs it and <prgn/ldconfig/ is run in the <prgn/postinst/ script. Futhermore, and <em/this is very important/, the symlink must be placed before the library it points to in the <tt/.deb/ file. Currently the way to ensure the ordering is done properly is to create the symlink in the appropriate <tt>debian/tmp/.../lib</tt> directory before installing the library when you build the package. If you do the above your package does not need to call <prgn/ldconfig/ in its maintainer scripts. It is especially important not to call <prgn/ldconfig/ in the postrm or preinst scripts in the case where the package is being upgraded (see the programmer's manual), as <prgn/ldconfig/ will see the temporary names that <prgn/dpkg/ uses for the files while it is installing them and will make the shared library links point to them, just before <prgn/dpkg/ continues the installation and removes the links! <chapt id="sysvinit">Configuration of <prgn/init/ <sect>Introduction to the <tt/init.d/ scheme The <tt>/etc/init.d</> directory contains the scripts executed by <prgn/init/ when init state (or `runlevel') is changed (see <manref name=init section=8>). These scripts are be referenced by symbolic links in the <tt>/etc/rc<var/n/.d</> directories. When changing runlevels, init looks in the directory <tt>/etc/rc<var/n/.d</> for the scripts it should execute, where <var/n/ is the runlevel that is being changed to. The names of the links all have the form <tt/S<var/mm/<var/script// or <tt/K<var/mm/<var/script// where <var/mm/ is a two-digit number and <var/script/ is the name of the script (this should be the same as the name of the actual script in <tt>/etc/init.d</>. When <prgn/init/ changes runlevel first the targets of the links whose names starting with a <tt/K/ are executed, each with the single argument <tt/stop/, followed by the scripts prefixed with an <tt/S/, each with the single argument <tt/start/. The <tt/K/ links are responsible for killing services and the <tt/S/ link for starting services upon entering the runlevel. For example, if we are changing from runlevel 2 to runlevel 3, init will first execute all of the <tt/K/ prefixed scripts it finds in <tt>/etc/rc3.d</>, and then all of the <tt/S/ prefixed scripts. The links starting with <tt/K/ will cause the referred-to file to be executed with an argument of <tt/stop/, and the <tt/S/ links with an argument of <tt/start/. The two-digit number <var/mm/ is used to decide which order to start and stop things in - low-numbered links have their scripts run first. For example, the <tt/K20/ scripts will be executed before the <tt/K30/ scripts. This is used when a certain service must be started before another. For example, the name server <prgn/bind/ might need to be started before the news server <prgn/inn/ so that <prgn/inn/ can set up its access lists. In this case, the script that starts <prgn/bind/ should have a lower number than the script that starts <prgn/inn/ so that it runs first: <example> /etc/rc2.d/S17bind /etc/rc2.d/S70inn </example> <sect>Writing <tt/init.d/ scripts Packages can and should place scripts in <tt>/etc/init.d</> to start or stop services at boot time or during a change of runlevel. These scripts should be named <tt>/etc/init.d/<var/package/</>, and they should accept one argument, saying what to do: <tt/start/, meaning to starts the service, or <tt/stop/, to stop the service. Optionally they can support <tt/reload/ which causes the configuration to be reloaded. The <tt/init.d/ scripts should ensure that they will behave sensibly if invoked with <tt/start/ when the service is already running, or with <tt/stop/ when it isn't, and that they don't kill unfortunately-named user processes. The best way to achieve this is usually to use <prgn/start-stop-daemon/. These scripts should not fail obscurely when the configuration files remain but the package has been removed, as the default in <prgn/dpkg/ is to leave configuration files on the system after the package has been removed. Only when it is executed with the <tt/--purge/ option will dpkg remove configuration files. Therefore, you should include a <tt/test/ statement at the top of the script, like this: <example> test -f <var/program-executed-later-in-script/ || exit 0 </example> <sect>Managing the <tt/rc<var/n/.d/ links - <prgn/update-rc.d/ A program is provided, <prgn/update-rc.d/, to make it easier for package maintainers to arrange for the proper creation and removal of <tt>/etc/rc<var/n/.d</> symbolic links from their postinst and postrm scripts. You should use this script to make changes to <tt>/etc/rc<var/n/.d</> and <em/never/ include any <tt>/etc/rc<var/n/.d</> symbolic links in the actual archive. By default <prgn/update-rc.d/ will start services in each of the multi-user state runlevels (2, 3, 4, and 5) and stop them in the halt runlevel (0), the single-user runlevel (1) and the reboot runlevel (6). The system administrator will have the opportunity to customize runlevels by simply adding, moving, or removing the symbolic links in <tt>/etc/rc<var/n/.d</>. To get the default behaviour for your package, put in your postinst script <example> update-rc.d <var/package/ default >/dev/null </example> and in your postrm <example> if [ purge = "$1" ]; then update-rc.d <var/package/ remove >/dev/null fi </example> This will use a default sequence number of 20. If it does not matter when or in which order the script is run, use this default. If it does, then you should talk to the maintainer of the <prgn/sysvinit/ package or post to <tt>debian-devel</>, and they will help you choose a number. For more information about using <tt/update-rc.d/, please consult its manpage <manref name=update-rc.d section=8>. <sect>Boot-time initialisation - <tt/rc.boot/ There is another directory, <tt>/etc/rc.boot</>, which contains scripts which are run once per machine boot. This facility is provided for initialisation of hardware devices, cleaning up of leftover files, and so forth. For example, the <prgn/kbd/ package provides a script here for initialising the keyboard layout and console font and mode. The files in <tt>/etc/rc.boot</> should <em/not/ be links into <tt>/etc/init.d</> - they should be the scripts themselves. <tt/rc.boot/ should <em/not/ be used for starting general-purpose daemons and similar activities. This should be done using the <tt/rc<var/n/.d/ scheme, above, so that the services can be started and stopped cleanly when the runlevel changes or the machine is to be shut down or rebooted. <sect>Notes <em/Do not/ include the <tt>/etc/rc<var/n/.d/*</> symbolic links in the <tt/.deb/ filesystem archive! <em/This will cause problems!/ You should create them with <prgn/update-rc.d/, as above. <em/Do not/ include the <tt>/etc/rc<var/n/.d/*</> symbolic links in <prgn/dpkg/'s conffiles list! <em/This will cause problems!/ <em/Do/, however, include the <tt>/etc/init.d</> scripts in conffiles. <sect>Example The <prgn/bind/ DNS (nameserver) package wants to make sure that the nameserver is running in multiuser runlevels, and is properly shut down with the system. It puts a script in <tt>/etc/init.d</>, naming the script appropriately <tt/bind/. As you can see, the script interprets the argument <tt/reload/ to send the nameserver a <tt/HUP/ signal (causing it to reload its configuration); this way the user can say <tt>/etc/init.d/bind reload</> to reload the nameserver. <example> #!/bin/sh # Original version by Robert Leslie <rob@mars.org>, edited by iwj test -x /usr/sbin/named || exit 0 case "$1" in start) test -f /etc/named.boot -a -f /var/named/boot.options || exit 0 start-stop-daemon --start --verbose --exec /usr/sbin/named ;; stop) start-stop-daemon --stop --verbose \ --pidfile /var/run/named.pid --exec /usr/sbin/named ;; reload) start-stop-daemon --stop --signal 1 --verbose \ --pidfile /var/run/named.pid --exec /usr/sbin/named ;; *) echo "Usage: /etc/init.d/bind {start|stop|reload}" >&2 exit 1 ;; esac exit 0 </example> Another example on which to base your <tt>/etc/init.d</> scripts is in <tt>/etc/init.d/skeleton</>. If this package is happy with the default setup from <prgn/update-rc.d/, namely an ordering number of 20 and having named running in all runlevels, it can say in its postinst: <example> update-rc.d bind default >/dev/null </example> And in its postrm, to remove the links when the package is purged: <example> if [ purge = "$1" ]; then update-rc.d acct remove >/dev/null fi </example> <chapt id="methif"><prgn/dselect/'s interface to its installation methods <prgn/dselect/ calls scripts from its installation methods when it needs to actually access data from the distribution. The core program <prgn/dselect/ itself just calls these scripts and provides the package and access method selection interfaces. The installation methods are responsible for invoking <prgn/dpkg/ as appropriate. Each installation method has three scripts: <list compact> <item>Setup installation parameters. <item>Update list of available packages. <item>Install. </list> <prgn/dselect/ searches for methods in <tt>/usr/lib/dpkg/methods</> and <tt>/usr/local/lib/dpkg/methods</>. <sect>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 <tt/.deb/ files can be found, or the tape or floppy device to install from. It should store the responses under <tt>/var/lib/dpkg/methods</> - see below. If no available packages list is available it should perhaps offer to scan the available packages. The update script should obtain a list of available packages if possible, and run <tt/dpkg --update-avail/, <tt/dpkg --merge-avail/ and/or <tt/dpkg --forget-old-unavail/ to load it into <prgn/dpkg/ and <prgn/dselect/'s database of available packages. If no packages list was available and the user was offered and accepted the option of scanning the actual files available this scan should be done here, using <tt/dpkg --record-avail/. The install script should feed all the available <tt/.deb/ files to <tt/dpkg --iGOEB/ (this is equivalent to <tt/dpkg --install --refuse-downgrade --selected-only --skip-same-version --auto-deconfigure/). The <tt/-R/ (<tt/--recursive/) option for traversing subdirectories may also be useful here). 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) <prgn/dselect/ will return immediately to the main menu, with the `next' option highlighted ready for the user to select it. If it fails <prgn/dselect/ will display a message and wait for the user to hit return. <sect>Location and arguments of the method scripts 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 <tt>/usr/lib/dpkg/methods/<var/group/</> or <tt>/usr/local/lib/dpkg/methods/<var/group/</>, containing: <taglist compact> <tag><tt/names/ <item>a list of user-visible methods provided by these scripts. <tag><tt/setup/ <tag><tt/update/ <tag><tt/install/ <item>executable programs, the scripts themselves. <tag><tt/desc.<var/option// <item>description file. </taglist> <tt/names/ will be formatted as a list of lines, each containing: <example> <var/sequence/ <var/method/ <var/summary/ </example> <var/sequence/ is a two-digit number that will be used much like <tt/rc.d/ prefixes to control the order in the main menu. If in doubt use 50. <var/method/ is a name which is displayed by <prgn/dselect/ as the name of the method, and which will be passed to <tt/setup/, <tt/update/ and <tt/unpack/ as their first argument. <var/summary/ is the brief description string for <prgn/dselect/'s menu. Each of the three scripts gets the same three arguments: <var/vardir/, <var/group/ and <var/method/. <var/vardir/ is the base directory for storing <prgn/dpkg/ and <prgn/dselect/'s state, usually <tt>/var/lib/dpkg</>; this is passed in so that the <tt/--admindir/ option to <prgn/dselect/ is honoured). Each option may have an extended description in <tt/desc.<var/option//. This should be formatted like the extended description part of a <tt/Description/ field entry <em/shifted one character to the left/. <tt><var/vardir//methods</> will exist, and a method group may use a <tt><var/vardir//methods/<var/group/</> directory to store its state. The group name and method name must follow the rules for C identifiers. </book>