<tt/dpkg/ Programmers' manual <author>Ian Jackson, <tt/ijackson@gnu.ai.mit.edu/ <date>1st June 1996 <abstract> This manual describes the technical aspects of creating Debian binary packages. It describes how to use utilities like <tt/install-info/. It also documents the interface between <tt/dselect/ and its access method scripts. It does not deal with the Debian Project policy requirements, and it assumes familiarity with <tt/dpkg/'s functions from the system administrator's perspective. </abstract> <toc>  <sect>Scope of this manual This manual describes the technical aspects of creating Debian binary packages (<tt/.deb/ files.). It documents the behaviour of the package management programs <tt/dpkg/, <tt/dselect/ et al and and the way they interact with packages. It documents the utility programs which are provided with <tt/dpkg/ for managing various system configuration and similar issues (such as <tt/update-rc.d/ and <tt/install-info/. It also documents the interaction between <tt/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. 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 <tt/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 not yet complete ! <sect>Binary package format <tt/dpkg/ is a suite of programs for creating binary package files and installing and removing them on Unix systems.<footnote><tt/dpkg/ is targetted primarily at Debian Linux, but may work or be ported to other systems.</footnote> The binary package files' contents may be architecture-independent, but they usually aren't. They aren't designed for the management of program source code (though examples of this are provided as part of some packages by way of documentation). The binary package has two main sections: the first part consists of various control information files and scripts used by <tt/dpkg/ when installing and removing. The second part is an archive (currently a <tt/tar/ archive) containing files and directories to be installed. See <ref id="controlarea">. In the future binary packages may also contain other components, such as checksums and digital signatures. <sect1>Creating package files -- <tt/dpkg-deb/ All manipulation of binary package files is done by <tt/dpkg-deb/; it's the only program that has knowledge of the format. (<tt/dpkg-deb/ may be invoked by calling <tt/dpkg/, as <tt/dpkg/ will spot that the options requested are appropriate to <tt/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. 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 <tt/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: <tt/DEBIAN/. It should contain the control information files, notably the main package control file (see <ref id="controlarea">). The <tt/DEBIAN/ directory will not appear in the filesystem archive of the package, and so won't be installed by <tt/dpkg/ when the package is installed. When you've prepared the package, you should invoke: <tscreen><verb> dpkg --build <it/directory/ </verb></tscreen> This will build the package in <var/directory/<tt/.deb/. (<tt/dpkg/ knows that <tt/--build/ is a <tt/dpkg-deb/ option, so it invokes <tt/dpkg-deb/ with the same arguments to build the package.) See the manpage for <tt/dpkg-deb/ for details of how to examine the contents of this newly-created file. You may find the output of following commands enlightening: <tscreen><verb> dpkg-deb --info <var/filename/<tt/.deb/ dpkg-deb --contents <var/filename/<tt/.deb/ </verb></tscreen> <sect1>Package control information files<label id="controlarea"> The control information portion of a binary package is a collection of files with names known to <tt/dpkg/. It will treat the contents of these files specially - some of them contain information used by <tt/dpkg/ when installing or removing the package; others are scripts which the package maintainer wants <tt/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 <tt/dpkg/ and a summary of what they're used for. <descrip> <tag/<tt/control// This is the key description file used by <tt/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/</tag> These are exectuable files (usually scripts) which <tt/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 <tt/dpkg/. Details of when and how they are called are in <ref id="maintainerscripts">. <tag/<tt/conffiles// This file contains a list of configuration files which are to be handled automatically by <tt/dpkg/ (see <ref id="conffiles">). Note that not necessarily every configuration file should be listed here. </descrip> <sect1>The main control information file: <tt/control/<label id="controlfile"> The most important control information file used by <tt/dpkg/ when it installs a package is <tt/control/. It contains all the package's `vital statistics'. It 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. Many of the fields have a syntax where whitespace is not significant. 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. Field names are not case-sensitive, but it is usual to capitalise the fields as shown below (usually using a form of mixed case). Blank lines, or lines consisting only of spaces and tabs, are not allowed. Here is a list of the fields which are permitted in packages, together with a description of the purposes and syntax of each and or a pointer to further information if appropriate. It is important to note that there are several fields which are optional as far as <tt/dpkg/ is concerned, but which must appear in every Debian package, or whose omission may cause problems. When writing the control file for a Debian package you <em/must/ read the Debian policy manual in conjuction with the list below. <sect2>List of package control file fields <descrip> <tag/<tt/Package// The name of the package. Package names consist of the alphanumerics, plus, minus and dot. They must be at least two characters and must start with an alphanumeric. In current versions of dpkg they are sort of case-sensitive; use lowercase package names unless the package you're building (or referring to, in other fields) is already using uppercase. This field is mandatory. <tag/<tt/Version// This lists the package's version number - see <ref id="versions">. This field is mandatory. <tag/<tt/Architecture// This is the architecture string; it is a single word for the CPU architecture, and <tt/dpkg/ will check it against its own compiled-in value before it installs a package. The special value <tt/all/ indicates that the package is architecture-independent. The value for this field can be obtained using <tscreen><verb> dpkg --print-architecture </verb></tscreen> This actually invokes <tscreen><verb> gcc --print-libgcc-file-name </verb></tscreen> and parses and decomposes the output and looks the CPU type from the GCC configuration in a table in <tt/dpkg/. This is so that it will work if you're cross-compiling. There is a separate option, <tt/--print-installation-architecture/, for finding out what architecture <tt/dpkg/ is willing to install. This information is also in the output of <tt/dpkg --version/. This field should appear in all packages, though <tt/dpkg/ doesn't require it yet so that old packages can still be installed. <tag/<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 for addresses; a program using this field as an address must check for this and reverse the components if necessary (for example by putting the name in round brackets or quotes, and perhaps moving it to the end). This feature is optional as far as <tt/dpkg/ is concerned, but <tt/dpkg-deb/ will warn if it is missing. <tag><tt/Depends/, <tt/Pre-Depends/, <tt/Recommends/, <tt/Suggests/ <tt/Conflicts/, <tt/Provides/, <tt/Replaces/</tag> These fields describe the package's relationships with other packages. Their syntax and semantics are described in <ref id="depconoverwr">. <tag/<tt/Source// This field identifies the source package name, primarily for the benefit of humans reading the control file rather than <tt/dpkg/. It consists solely of the source package name; it may be omitted when the source package has the same name as the binary package. This field is optional as far as <tt/dpkg/ is concerned. <tag/<tt/Description// This field contains a description of the package, in a special format. It is very important that you read <ref id="descriptions">. <tag/<tt/Essential// This is a boolean field. If set to <tt/yes/ then <tt/dpkg/ and <tt/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. This field is optional. <tag/<tt/Priority// This specifies the `priority' of the package; this represents how important that it is that the user have it installed. This value isn't used by <tt/dpkg/, but only by <tt/dselect/ when it sorts packages and selects defaults. See the <tt/dpkg/ System Administrator's Manual for details of the values it can take, and the Debian Policy Manual for the criteria for selecting the priority for a Debian package. <tt/dpkg/ and <tt/dselect/ will only use the value from a <tt/.deb/ file if they have no other information; a priority value listed in a <tt/Packages/ file will always take precedence. This field is optional as far as <tt/dpkg/ is concerned. <tag/<tt/Section// This specifies the `section' of the package, namely the application area or group of packages which contain it. The value is a simple string, usually from a set chosen by the distribution maintainers. The section isn't used at all except by <tt/dselect/, which only uses it for sorting packages in the selection display and not even for choosing defaults. Just as with <tt/Priority/, this field is optional as far as <tt/dpkg/ is concerned, and the value from a package file is used only as a last resort. </descrip> <sect2>List of other control fields There are several other fields which are used elsewhere by parts of the system. These should not appear in package control files. <sect3>Status fields These fields appear in <tt/dpkg/'s internal status file; they are also printed by <tt/dpkg --status/ and can be seen in <tt/dselect/ by selecting the installed control info display. <descrip> <tag/<tt/Status// This field in <tt/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. <tag/<tt/Config-Version// If a package is not installed or not configured, this field in <tt/dpkg/'s status file records the last version of the package which was successfully configured. <tag/<tt/Conffiles// This field in <tt/dpkg/'s status file contains information about the automatically-managed configuration files held by a package. Let me emphasise that this field should <em/not/ appear in a package ! </descrip> <sect4><tt/Packages/ file (available package) fields These fields are found in <tt/Packages/ files (lists of packages available for installation, which are generated by the distribution maintainers and used principally by <tt/dselect/) and in <tt/dpkg/'s database of available packages (which can be inspected using <tt/dpkg --print-avail/ or by selecting the `available control information' in <tt/dselect/. <descrip> <tag><tt/Filename/, <tt/MSDOS-Filename/</tag> 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. <tag><tt/Size/, <tt/MD5sum/</tag> 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. </descrip> <sect4>Obsolete fields These are still recognised by <tt/dpkg/ but should not appear anywhere any more. <descrip> <tag><tt/Revision/, <tt/Package-Revision/, <tt/Package_Revision/</tag> 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/Recommended/ Old name for <tt/Recommends/. <tag/Optional/ Old name for <tt/Suggests/. <tag/Class/ Old name for <tt/Priority/. </descrip> <sect1>Version numbering<label id="versions"> Every package has a version number, in its <tt/Version/ control file field. <tt/dpkg/ imposes an ordering on version numbers, so that it can tell whether packages are being up- or downgraded and so that <tt/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: <descrip> <tag/<var/epoch// This is a single unsigned integer, which should usually be small. It may be omitted, in which case it defaults to zero. 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. <tt/dpkg/ will not usually display the epoch unless it is essential (non-zero, or if the <var/upstream-version/ contains a colon); <tt/dselect/ does not display epochs at all in the main part of the package selection display. <tag/<var/upstream-version// 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 <tt/dpkg/'s format and comparison scheme. The comparison behaviour of <tt/dpkg/ with respect to the <var/upstream-version/ is described below. The <var/upstream-version/ portion of the version number is mandatory. <tag/<var/debian-revision// This part of the version represents the version of the modifications that were made to the package to make it a Debian binary package. It is in the same format as the <var/upstream-version/ and <tt/dpkg/ compares it in the same way. It is optional; if it isn't present then the <var/upstream-version/ should 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 version indication is require there. It is conventional to restart the <var/debian-revision/ at <tt/1/ each time the <var/upstream-version/ is increased. <tt/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). </descrip> The <var/upstream-version/ and <var/debian-revision/ parts are compared by <tt/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 <tt/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. <sect1>Package maintainer scripts run by <tt/dpkg/<label id="maintainerscripts"> It is possible supply scripts as part of a package which <tt/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 should be proper exectuable files, so that if they are scripts (which is to be recommended) they must start with the usual <tt/#!/ convention. They should be readable and executable to anyone, and not world-writeable. <tt/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 <tt/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 <tt/preinst/ is called before (a particular version of) a package is installed, and the <tt/postinst/ afterwards; the <tt/prerm/ before (a version of) a package is removed and the <tt/postrm/ afterwards. See <ref id="maintscripts-instact"> for details of exactly when and how these scripts are called and with what arguments. <sect>Declaring relationships between packages<label id="depconoverwr"> 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. 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, and so (while <tt/dpkg/ still supports them) they should not appear in new packages. 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 <tt/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. <sect1>Dependencies - <tt/Depends/, <tt/Recommends/, <tt/Suggests/, <tt/Pre-Depends/ These three 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. <descrip> <tag/<tt/Depends// This declares an absolute dependency. <tt/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 <tt/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. <tt/dselect/ makes it hard for the user to select packages for installation, removal or upgrade in a way that would mean that packages' <tt/Depends/ fields would be unsatisfied. The user can override this if they wish, for example if they know that <tt/dselect/ has an out-of-date view of the real package relationships. **** WHEN TO USE -- POLICY STATEMENT HERE ? <tag/<tt/Recommends// This declares a strong, but not absolute, dependency. <tt/Recommends/ is ignored by <tt/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 <tt/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. **** WHEN TO USE -- POLICY STATEMENT HERE ? <tt/<tt/Suggests// This declares a **** WRITE THIS </descrip> <sect1>Alternative packages - <tt/Conflicts/ **** WRITE THIS <sect1>Virtual packages - <tt/Provides/ **** WRITE THIS <sect1>Overwriting files - <tt/Replaces/<label id="replaces"> **** WRITE THIS <sect>Order of processing steps and maintainer script arguments<label id="maintscripts-instact"> <sect1>Summary of ways maintainer scripts are called <itemize> <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/ </itemize> <itemize> <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/ 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/ </itemize> <itemize> <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/ </itemize> <itemize> <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/ </itemize> <sect1>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. <enum> <item> <enum> <item> If a version the package is already installed, call <tscreen><verb> <var/old-prerm/ <tt/upgrade/ <var/new-version/ </verb></tscreen> <item> If this gives an error (ie, a non-zero exit status), dpkg will attempt instead: <tscreen><verb> <var/new-prerm/ <tt/failed-upgrade/ <var/old-version/ </verb></tscreen> Error unwind, for both the above cases: <tscreen><verb> <var/old-postinst/ <tt/abort-upgrade/ <var/new-version/ </verb></tscreen> </enum> <item> If a `conflicting' package is being removed at the same time: <enum> <item> If any packages depended on that conflicting package and <tt/--auto-deconfigure/ is specified, call, for each such package: <tscreen><verb> <var/deconfigured's-prerm/ <tt/deconfigure/ <tt/in-favour/ <var/package-being-installed/ <var/version/ <tt/removing/ <var/conflicting-package/ <var/version/ </verb></tscreen> Error unwind: <tscreen><verb> <var/deconfigured's-postinst/ <tt/abort-deconfigure/ <tt/in-favour/ <var/package-being-installed-but-failed/ <var/version/ <tt/removing/ <var/conflicting-package/ <var/version/ </verb></tscreen> 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: <tscreen><verb> <var/conflictor's-prerm/ <tt/remove/ <tt/in-favour/ <var/package/ <var/new-version/ </verb></tscreen> Error unwind: <tscreen><verb> <var/conflictor's-postinst/ <tt/abort-remove/ <tt/in-favour/ <var/package/ <var/new-version/ </verb></tscreen> </enum> <item> <enum> <item> If the package is being upgraded, call: <tscreen><verb> <var/new-preinst/ <tt/upgrade/ <var/old-version/ </verb></tscreen> <item> Otherwise, if the package had some configuration files from a previous version installed (ie, it is in the `configuration files only' state): <tscreen><verb> <var/new-preinst/ <tt/install/ <var/old-version/ </verb></tscreen> <item> Otherwise (ie, the package was completely purged): <tscreen><verb> <var/new-preinst/ <tt/install/ </verb></tscreen> Error unwind versions, respectively: <tscreen><verb> <var/new-postrm/ <tt/abort-upgrade/ <var/old-version/ <var/new-postrm/ <tt/abort-install/ <var/old-version/ <var/new-postrm/ <tt/abort-install/ </verb></tscreen> </enum> <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 will 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 and can easily lead to `missing' programs (for example, if a package is installed which overwrites a file from another package, and then it is removed again). <item> <enum> <item> If the package is being upgraded, call <tscreen><verb> <var/old-postrm/ <tt/upgrade/ <var/new-version/ </verb></tscreen> <item> If this fails, <tt/dpkg/ will attempt: <tscreen><verb> <var/new-postrm/ <tt/failed-upgrade/ <var/old-version/ </verb></tscreen> Error unwind, for both cases: <tscreen><verb> <var/old-preinst/ <tt/abort-upgrade/ <var/new-version/ </verb></tscreen> </enum> This is the point of no return - if <tt/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 <tt/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, <enum> <item> <tt/dpkg/ calls: <tscreen><verb> <var/disappearer's-postrm/ <tt/disappear/ <var/overwriter/ <var/overwriter-version/ </verb></tscreen> <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). Note that disappearing packages do not have their prerm called, because <tt/dpkg/ doesn't know in advance that the package is going to vanish. </enum> <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). </enum> <sect1>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: <tscreen><verb> <var/postinst/ <tt/configure/ <var/most-recently-configured-version/ </verb></tscreen> No attempt is made to unwind after errors during configuration. If there is no most recently configured version <tt/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. <sect1>Details of removal and/or configration purging <enum> <item> <tscreen><verb> <var/prerm/ <tt/remove/ </verb></tscreen> <item> The package's files are removed (except conffiles). <item> <tscreen><verb> <var/postrm/ <tt/remove/ </verb></tscreen> <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 <tt/dpkg/ status. <item> The conffiles and any backup files (<tt/~/-files, <tt/#*#/ files, <tt/%/-files, <tt/.dpkg-{old,new,tmp}/, etc.) are removed. <item> <tscreen><verb> <var/postrm/ <tt/purge/ </verb></tscreen> <item> The package's file list is removed. </enum> No attempt is made to unwind after errors during removal. <sect>Dangling references <sect1>Would dangle to conffiles<label id="conffiles"> There would be a dangling xref here. Instead I've just put this dummy text in. <sect1>Would dangle to descriptions<label id="descriptions"> There would be a dangling xref here. Instead I've just put this dummy text in. </article>