Debian Policy Manual -------------------- Ian Jackson Christian Schwarz revised: David A. Morris The Debian Policy mailing List version 3.5.6.1, 2002-03-14 ------------------------------------------------------------------------------- Abstract -------- This manual describes the policy requirements for the Debian GNU/Linux distribution. This includes the structure and contents of the Debian archive and several design issues of the operating system, as well as technical requirements that each package must satisfy to be included in the distribution. The policy package itself is maintained by a group of maintainers that have no editorial powers. The current list of maintainers is: 1. Julian Gilbey 2. Manoj Srivastava Copyright Notice ---------------- Copyright ©1996,1997,1998 Ian Jackson and Christian Schwarz. This manual is free software; you may redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. This is distributed in the hope that it will be useful, but _without any warranty_; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details. A copy of the GNU General Public License is available as `/usr/share/common-licenses/GPL' in the Debian GNU/Linux distribution or on the World Wide Web at The GNU General Public Licence (http://www.gnu.org/copyleft/gpl.html). You can also obtain it by writing to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. ------------------------------------------------------------------------------- Contents -------- 1. About this manual 1.1. Scope 1.2. New versions of this document 1.3. Feedback 2. The Debian Archive 2.1. Package copyright and sections 2.2. Priorities 2.3. Binary packages 2.4. Source packages 3. Control files and their fields 3.1. Syntax of control files 3.2. List of fields 4. Version numbering 4.1. Version numbers based on dates 5. Packaging Considerations 5.1. Time Stamps 5.2. `debian/rules' - the main building script 5.3. `debian/changelog' 5.4. `debian/substvars' and variable substitutions 5.5. `debian/files' 5.6. Restrictions on objects in source packages 5.7. Descriptions of packages - the `Description' field 6. Package maintainer scripts and installation procedure 6.1. Introduction to package maintainer scripts 6.2. Maintainer scripts Idempotency 6.3. Controlling terminal for maintainer scripts 6.4. Summary of ways maintainer scripts are called 6.5. Details of unpack phase of installation or upgrade 6.6. Details of configuration 6.7. Details of removal and/or configuration purging 7. Declaring relationships between packages 7.1. Syntax of relationship fields 7.2. Binary Dependencies - `Depends', `Recommends', `Suggests', `Enhances', `Pre-Depends' 7.3. Conflicting binary packages - `Conflicts' 7.4. Virtual packages - `Provides' 7.5. Overwriting files and replacing packages - `Replaces' 7.6. Relationships between source and binary packages - `Build-Depends', `Build-Depends-Indep', `Build-Conflicts', `Build-Conflicts-Indep' 8. Configuration file handling 9. Shared libraries 9.1. Handling shared library dependencies - the `shlibs' system 9.2. The `shlibs' files present on the system 9.3. How to use `dpkg-shlibdeps' and the `shlibs' files 9.4. The `shlibs' File Format 9.5. Providing a `shlibs' file 9.6. Writing the `debian/shlibs.local' file 10. The Operating System 10.1. Filesystem hierarchy 10.2. Users and groups 10.3. System run levels and `init.d' scripts 10.4. Console messages from `init.d' scripts 10.5. Cron jobs 10.6. Menus 10.7. Multimedia handlers 10.8. Keyboard configuration 10.9. Environment variables 11. Files 11.1. Binaries 11.2. Libraries 11.3. Shared libraries 11.4. Scripts 11.5. Symbolic links 11.6. Device files 11.7. Configuration files 11.8. Log files 11.9. Permissions and owners 12. Customized programs 12.1. Architecture specification strings 12.2. Daemons 12.3. Using pseudo-ttys and modifying wtmp, utmp and lastlog 12.4. Editors and pagers 12.5. Web servers and applications 12.6. Mail transport, delivery and user agents 12.7. News system configuration 12.8. Programs for the X Window System 12.9. Perl programs and modules 12.10. Emacs lisp programs 12.11. Games 13. Documentation 13.1. Manual pages 13.2. Info documents 13.3. Additional documentation 13.4. Accessing the documentation 13.5. Preferred documentation formats 13.6. Copyright information 13.7. Examples 13.8. Changelog files A. Introduction and scope of these appendices B. Binary packages (from old Packaging Manual) B.1. Creating package files - `dpkg-deb' B.2. Package control information files B.3. The main control information file: `control' B.4. Time Stamps C. Source packages (from old Packaging Manual) C.1. Tools for processing source packages C.2. The Debianised source tree C.3. Source packages as archives C.4. Unpacking a Debian source package without `dpkg-source' D. Control files and their fields (from old Packaging Manual) D.1. Syntax of control files D.2. List of fields E. Configuration file handling (from old Packaging Manual) E.1. Automatic handling of configuration files by `dpkg' E.2. Fully-featured maintainer script configuration handling F. Alternative versions of an interface - `update-alternatives' (from old Packaging Manual) G. Diversions - overriding a package's version of a file (from old Packaging Manual) ------------------------------------------------------------------------------- 1. About this manual -------------------- 1.1. Scope ---------- This manual describes the policy requirements for the Debian GNU/Linux distribution. This includes the structure and contents of the Debian archive and several design issues of the operating system, as well as technical requirements that each package must satisfy to be included in the distribution. This manual also describes Debian policy as it relates to creating Debian packages. It is not a tutorial on how to build packages, nor is it exhaustive where it comes to describing the behavior of the packaging system. Instead, this manual attempts to define the interface to the package management system that the developers have to be conversant with.[1] The footnotes present in this manual are merely informative, and are not part of Debian policy itself. In this manual, the words _must_, _should_ and _may_, and the adjectives _required_, _recommended_ and _optional_, are used to distinguish the significance of the various guidelines in this policy document. Packages that do not conform to the guidelines denoted by _must_ (or _required_) will generally not be considered acceptable for the Debian distribution. Non-conformance with guidelines denoted by _should_ (or _recommended_) will generally be considered a bug, but will not necessarily render a package unsuitable for distribution. Guidelines denoted by _may_ (or _optional_) are truly optional and adherence is left to the maintainer's discretion. These classifications are roughly equivalent to the bug severities _serious_ (for _must_ or _required_ directive violations), _minor_, _normal_ or _important_ (for _should_ or _recommended_ directive violations) and _wishlist_ (for _optional_ items).[2] Much of the information presented in this manual will be useful even when building a package which is to be distributed in some other way or is intended for local use only. [1] Informally, the criteria used for inclusion is that the material meet one of the following requirements: Standard interfaces The material presented represents an interface to the packaging system that is mandated for use, and is used by, a significant number of packages, and therefore should not be changed without peer review. Package maintainers can then rely on this interfaces not changing, and the package management software authors need to ensure compatibility with these interface definitions. (Control file and changelog file formats are examples.) Chosen Convention If there are a number of technically viable choices that can be made, but one needs to select one of these options for inter-operability. The version number format is one example. Please note that these are not mutually exclusive; selected conventions often become parts of standard interfaces. [2] Compare RFC 2119. Note, however, that these words are used in a different way in this document. 1.2. New versions of this document ---------------------------------- The current version of this document is always accessible from the Debian FTP server ftp.debian.org as /debian/doc/package-developer/policy.txt.gz (also available from the same directory are several other formats: `policy.html.tar.gz', `policy.pdf.gz' and `policy.ps.gz') or from the Debian Policy Manual (http://www.debian.org/doc/debian-policy/) webpage. In addition, this manual is distributed via the Debian package `debian-policy'. The `debian-policy' package also includes the file `upgrading-checklist.txt' which indicates policy changes between versions of this document. 1.3. Feedback ------------- As the Debian GNU/Linux system is continuously evolving this manual does so too. While the authors of this document have tried hard to avoid typos and other errors, these do still occur. If you discover an error in this manual or if you want to give any comments, suggestions, or criticisms please send an email to the Debian Policy List, , or submit a bug report against the `debian-policy' package. ------------------------------------------------------------------------------- 2. The Debian Archive --------------------- The Debian GNU/Linux system is maintained and distributed as a collection of _packages_. Since there are so many of them (currently well over 6000), they are split into _sections_ and given _priorities_ to simplify the handling of them. The effort of the Debian project is to build a free operating system, but not every package we want to make accessible is _free_ in our sense (see the Debian Free Software Guidelines, below), or may be imported/exported without restrictions. Thus, the archive is split into the sections _main_, _non-free_, _contrib_, _non-US/main_, _non-US/non-free_, and _non-US/contrib_. The sections are explained in detail below. The _main_ and the _non-US/main_ sections together form the _Debian GNU/Linux distribution_. Packages in the other sections are not considered to be part of the Debian distribution, although we support their use and provide infrastructure for them (such as our bug-tracking system and mailing lists). This Debian Policy Manual applies to these packages as well. 2.1. Package copyright and sections ----------------------------------- The aims of this section are: * to allow us to make as much software available as we can, * to allow us to encourage everyone to write free software, and * to allow us to make it easy for people to produce CD-ROMs of our system without violating any licenses, import/export restrictions, or any other laws. 2.1.1. The Debian Free Software Guidelines ------------------------------------------ The Debian Free Software Guidelines (DFSG) form our definition of `free software'. These are: Free Redistribution The license of a Debian component may not restrict any party from selling or giving away the software as a component of an aggregate software distribution containing programs from several different sources. The license may not require a royalty or other fee for such sale. Source Code The program must include source code, and must allow distribution in source code as well as compiled form. Derived Works The license must allow modifications and derived works, and must allow them to be distributed under the same terms as the license of the original software. Integrity of The Author's Source Code The license may restrict source-code from being distributed in modified form _only_ if the license allows the distribution of ``patch files'' with the source code for the purpose of modifying the program at build time. The license must explicitly permit distribution of software built from modified source code. The license may require derived works to carry a different name or version number from the original software. (This is a compromise. The Debian Project encourages all authors to not restrict any files, source or binary, from being modified.) No Discrimination Against Persons or Groups The license must not discriminate against any person or group of persons. No Discrimination Against Fields of Endeavor The license must not restrict anyone from making use of the program in a specific field of endeavor. For example, it may not restrict the program from being used in a business, or from being used for genetic research. Distribution of License The rights attached to the program must apply to all to whom the program is redistributed without the need for execution of an additional license by those parties. License Must Not Be Specific to Debian The rights attached to the program must not depend on the program's being part of a Debian system. If the program is extracted from Debian and used or distributed without Debian but otherwise within the terms of the program's license, all parties to whom the program is redistributed must have the same rights as those that are granted in conjunction with the Debian system. License Must Not Contaminate Other Software The license must not place restrictions on other software that is distributed along with the licensed software. For example, the license must not insist that all other programs distributed on the same medium must be free software. Example Licenses The ``GPL,'' ``BSD,'' and ``Artistic'' licenses are examples of licenses that we consider _free_. 2.1.2. The main section ----------------------- Every package in _main_ and _non-US/main_ must comply with the DFSG (Debian Free Software Guidelines). In addition, the packages in _main_ * must not require a package outside of _main_ for compilation or execution (thus, the package must not declare a "Depends", "Recommends", or "Build-Depends" relationship on a non-_main_ package), * must not be so buggy that we refuse to support them, and * must meet all policy requirements presented in this manual. Similarly, the packages in _non-US/main_ * must not require a package outside of _main_ or _non-US/main_ for compilation or execution, * must not be so buggy that we refuse to support them, * must meet all policy requirements presented in this manual. 2.1.3. The contrib section -------------------------- Every package in _contrib_ and _non-US/contrib_ must comply with the DFSG. In addition, the packages in _contrib_ and _non-US/contrib_ * must not be so buggy that we refuse to support them, and * must meet all policy requirements presented in this manual. Furthermore, packages in _contrib_ must not require a package in a _non-US_ section for compilation or execution. Examples of packages which would be included in _contrib_ or _non-US/contrib_ are: * free packages which require _contrib_, _non-free_ packages or packages which are not in our archive at all for compilation or execution, and * wrapper packages or other sorts of free accessories for non-free programs. 2.1.4. The non-free section --------------------------- Packages must be placed in _non-free_ or _non-US/non-free_ if they are not compliant with the DFSG or are encumbered by patents or other legal issues that make their distribution problematic. In addition, the packages in _non-free_ and _non-US/non-free_ * must not be so buggy that we refuse to support them, and must meet all policy requirements presented in this manual that it is possible for them to meet.[1] [1] * It is possible that there are policy requirements which the package is unable to meet, for example, if the source is unavailable. These situations will need to be handled on a case-by-case basis. 2.1.5. The non-US sections -------------------------- Some programs with cryptographic program code need to be stored on the _non-US_ server because of United States export restrictions. Such programs must be distributed in the appropriate _non-US_ section, either _non-US/main_, _non-US/contrib_ or _non-US/non-free_. This applies only to packages which contain cryptographic code. A package containing a program with an interface to a cryptographic program or a program that's dynamically linked against a cryptographic library should not be distributed via the _non-US_ server if it is capable of running without the cryptographic library or program. 2.1.6. Further copyright considerations --------------------------------------- Every package must be accompanied by a verbatim copy of its copyright and distribution license in the file `/usr/share/doc//copyright' (see Section 13.6, `Copyright information' for further details). We reserve the right to restrict files from being included anywhere in our archives if * their use or distribution would break a law, * there is an ethical conflict in their distribution or use, * we would have to sign a license for them, or * their distribution would conflict with other project policies. Programs whose authors encourage the user to make donations are fine for the main distribution, provided that the authors do not claim that not donating is immoral, unethical, illegal or something similar; in such a case they must go in _non-free_. Packages whose copyright permission notices (or patent problems) do not even allow redistribution of binaries only, and where no special permission has been obtained, must not be placed on the Debian FTP site and its mirrors at all. Note that under international copyright law (this applies in the United States, too), _no_ distribution or modification of a work is allowed without an explicit notice saying so. Therefore a program without a copyright notice _is_ copyrighted and you may not do anything to it without risking being sued! Likewise if a program has a copyright notice but no statement saying what is permitted then nothing is permitted. Many authors are unaware of the problems that restrictive copyrights (or lack of copyright notices) can cause for the users of their supposedly-free software. It is often worthwhile contacting such authors diplomatically to ask them to modify their license terms. However, this can be a politically difficult thing to do and you should ask for advice on the `debian-legal' mailing list first, as explained below. When in doubt about a copyright, send mail to . Be prepared to provide us with the copyright statement. Software covered by the GPL, public domain software and BSD-like copyrights are safe; be wary of the phrases `commercial use prohibited' and `distribution restricted'. 2.1.7. Subsections ------------------ The packages in the sections _main_, _contrib_ and _non-free_ are grouped further into _subsections_ to simplify handling. The section and subsection for each package should be specified in the package's `Section' control record. However, the maintainer of the Debian archive may override this selection to ensure the consistency of the Debian distribution. The `Section' field should be of the form: * _subsection_ if the package is in the _main_ section, * _section/subsection_ if the package is in the _contrib_ or _non-free_ section, and * `non-US', `non-US/contrib' or `non-US/non-free' if the package is in _non-US/main_, _non-US/contrib_ or _non-US/non-free_ respectively. The Debian archive maintainers provide the authoritative list of subsections. At present, they are: _admin_, _base_, _comm_, _contrib_, _devel_, _doc_, _editors_, _electronics_, _games_, _graphics_, _hamradio_, _interpreters_, _libs_, _mail_, _math_, _misc_, _net_, _news_, _non-US_, _non-free_, _oldlibs_, _otherosfs_, _science_, _shells_, _sound_, _tex_, _text_, _utils_, _web_, _x11_. 2.2. Priorities --------------- Each package should have a _priority_ value, which is included in the package's _control record_. This information is used by the Debian package management tools to separate high-priority packages from less-important packages. The following _priority levels_ are recognised by the Debian package management tools. `required' Packages which are necessary for the proper functioning of the system. You must not remove these packages or your system may become totally broken and you may not even be able to use `dpkg' to put things back. Systems with only the `required' packages are probably unusable, but they do have enough functionality to allow the sysadmin to boot and install more software. `important' Important programs, including those which one would expect to find on any Unix-like system. If the expectation is that an experienced Unix person who found it missing would say `What on earth is going on, where is `foo'?', it must be an `important' package.[1] Other packages without which the system will not run well or be usable must also have priority `important'. This does _not_ include Emacs, the X Window System, TeX or any other large applications. The `important' packages are just a bare minimum of commonly-expected and necessary tools. `standard' These packages provide a reasonably small but not too limited character-mode system. This is what will be installed by default if the user doesn't select anything else. It doesn't include many large applications. `optional' (In a sense everything that isn't required is optional, but that's not what is meant here.) This is all the software that you might reasonably want to install if you didn't know what it was and don't have specialized requirements. This is a much larger system and includes the X Window System, a full TeX distribution, and many applications. Note that optional packages should not conflict with each other. `extra' This contains all packages that conflict with others with required, important, standard or optional priorities, or are only likely to be useful if you already know what they are or have specialised requirements. Packages must not depend on packages with lower priority values (excluding build-time dependencies). In order to ensure this, the priorities of one or more packages may need to be adjusted. [1] This is an important criterion because we are trying to produce, amongst other things, a free Unix. 2.3. Binary packages -------------------- The Debian GNU/Linux distribution is based on the Debian package management system, called `dpkg'. Thus, all packages in the Debian distribution must be provided in the `.deb' file format. 2.3.1. The package name ----------------------- Every package must have a name that's unique within the Debian archive. Package names must consist of lower case letters (`a-z'), digits (`0-9'), plus (`+') and minus (`-') signs, and periods (`.'). They must be at least two characters long and must contain at least one letter. The package name is part of the file name of the `.deb' file and is included in the control field information. 2.3.2. The maintainer of a package ---------------------------------- Every package must have a Debian maintainer (the maintainer may be one person or a group of people reachable from a common email address, such as a mailing list). The maintainer is responsible for ensuring that the package is placed in the appropriate distributions. The maintainer must be specified in the `Maintainer' control field with their correct name and a working email address. If one person maintains several packages, he/she should try to avoid having different forms of their name and email address in the `Maintainer' fields of those packages. If the maintainer of a package quits from the Debian project, "Debian QA Group" takes over the maintainership of the package until someone else volunteers for that task. These packages are called _orphaned packages_.[1] [1] The detailed procedure for doing this gracefully can be found in the Debian Developer's Reference, either in the `developers-reference' package, or on the Debian FTP server ftp.debian.org as /debian/doc/package-developer/developers-reference.txt.gz or from the Debian Developer's Reference (http://www.debian.org/doc/packaging-manuals/developers-reference/) webpage. 2.3.3. The description of a package ----------------------------------- Every Debian package must have an extended description stored in the appropriate field of the control record. The description should be written so that it gives the system administrator enough information to decide whether to install the package. This description should not just be copied verbatim from the program's documentation. Instructions for configuring or using the package should not be included (that is what installation scripts, manual pages, info files, etc., are for). Copyright statements and other administrivia should not be included either (that is what the copyright file is for). 2.3.4. Dependencies ------------------- Every package must specify the dependency information about other packages that are required for the first to work correctly. For example, a dependency entry must be provided for any shared libraries required by a dynamically-linked executable binary in a package. Packages are not required to declare any dependencies they have on other packages which are marked `Essential' (see below), and should not do so unless they depend on a particular version of that package. Sometimes, a package requires another package to be installed _and_ configured before it can be installed. In this case, you must specify a `Pre-Depends' entry for the package. You should not specify a `Pre-Depends' entry for a package before this has been discussed on the `debian-devel' mailing list and a consensus about doing that has been reached. 2.3.5. Virtual packages ----------------------- Sometimes, there are several packages which offer more-or-less the same functionality. In this case, it's useful to define a _virtual package_ whose name describes that common functionality. (The virtual packages only exist logically, not physically; that's why they are called _virtual_.) The packages with this particular function will then _provide_ the virtual package. Thus, any other package requiring that function can simply depend on the virtual package without having to specify all possible packages individually. All packages should use virtual package names where appropriate, and arrange to create new ones if necessary. They should not use virtual package names (except privately, amongst a cooperating group of packages) unless they have been agreed upon and appear in the list of virtual package names. The latest version of the authoritative list of virtual package names can be found on ftp.debian.org in /debian/doc/package-developer/virtual-package-names-list.txt or your local mirror. In addition, it is included in the `debian-policy' package. The procedure for updating the list is described at the top of the file. 2.3.6. Base packages -------------------- The packages included in the `base' section have a special function. They form a minimum subset of the Debian GNU/Linux system that is installed before everything else on a new system. Thus, only very few packages are allowed to go into the `base' section to keep the required disk usage very small. Most of these packages will have the priority value `required' or at least `important', and many of them will be tagged `essential' (see below). You must not place any packages into the `base' section before this has been discussed on the `debian-devel' mailing list and a consensus about doing that has been reached. 2.3.7. Essential packages ------------------------- Some packages are tagged `essential'. (They have `Essential: yes' in their package control record.) This flag is used for packages that are _essential_ for a system. Since these packages cannot be easily removed (one has to specify an extra _force option_ to `dpkg' to do so), this flag must not be used unless absolutely necessary. A shared library package must not be tagged `essential'; dependencies will prevent its premature removal, and we need to be able to remove it when it has been superseded. Since dpkg will not prevent upgrading of other packages while an `essential' package is in an unconfigured state, all `essential' packages must supply all of their core functionality even when unconfigured. If the package cannot satisfy this requirement it must not be tagged as essential, and any packages depending on this package must instead have explicit dependency fields as appropriate. You must not tag any packages `essential' before this has been discussed on the `debian-devel' mailing list and a consensus about doing that has been reached. 2.3.8. Maintainer scripts ------------------------- The package installation scripts should avoid producing output which it is unnecessary for the user to see and should rely on `dpkg' to stave off boredom on the part of a user installing many packages. This means, amongst other things, using the `--quiet' option on `install-info'. Errors which occur during the execution of an installation script must be checked and the installation must not continue after an error. Note that in general Section 11.4, `Scripts' applies to package maintainer scripts, too. You should not use `dpkg-divert' on a file belonging to another package without consulting the maintainer of that package first. All packages which supply an instance of a common command name (or, in general, filename) should generally use `update-alternatives', so that they may be installed together. If `update-alternatives' is not used, then each package must use `Conflicts' to ensure that other packages are de-installed. (In this case, it may be appropriate to specify a conflict against earlier versions of something that previously did not use `update-alternatives'; this is an exception to the usual rule that versioned conflicts should be avoided.) 2.3.8.1. Prompting in maintainer scripts ---------------------------------------- Package maintainer scripts may prompt the user if necessary. Prompting may be accomplished by hand, or by communicating with a program, such as `debconf', which conforms to the Debian Configuration management specification, version 2 or higher. These are included in the `debconf_specification' files in the `debian-policy' package. You may also find this file on the FTP site ftp.debian.org in /debian/doc/package-developer/debconf_specification.txt.gz or on your local mirror.[1] Packages which use the Debian Configuration management specification may contain an additional `config' script and a `templates' file in their control archive. The `config' script might be run before the `preinst' script, and before the package is unpacked or any of its dependencies or pre-dependancies are satisfied. Therefore it must work using only the tools present in _essential_ packages.[2] Packages should try to minimize the amount of prompting they need to do, and they should ensure that the user will only ever be asked each question once. This means that packages should try to use appropriate shared configuration files (such as `/etc/papersize' and `/etc/news/server'), and shared `debconf' variables rather than each prompting for their own list of required pieces of information. It also means that an upgrade should not ask the same questions again, unless the user has used `dpkg --purge' to remove the package's configuration. The answers to configuration questions should be stored in an appropriate place in `/etc' so that the user can modify them, and how this has been done should be documented. If a package has a vitally important piece of information to pass to the user (such as "don't run me as I am, you must edit the following configuration files first or you risk your system emitting badly-formatted messages"), it should display this in the `config' or `postinst' script and prompt the user to hit return to acknowledge the message. Copyright messages do not count as vitally important (they belong in `/usr/share/doc//copyright'); neither do instructions on how to use a program (these should be in on-line documentation, where all the users can see them). Any necessary prompting should almost always be confined to the `config' or `postinst' script. If it is done in the `postinst', it should be protected with a conditional so that unnecessary prompting doesn't happen if a package's installation fails and the `postinst' is called with `abort-upgrade', `abort-remove' or `abort-deconfigure'. [1] 4% of Debian packages [see Debconf stats (http://kitenet.net/programs/debconf/stats/)] currently use `debconf' to prompt the user at install time, and this number is growing daily. The benefits of using debconf are briefly explained at Debconf introduction (http://kitenet.net/doc/debconf-doc/introduction.html); they include preconfiguration, (mostly) noninteractive installation, elimination of redundant prompting, consistency of user interface, etc. With this increasing number of packages using `debconf', plus the existance of a nascent second implementation of the Debian configuration management system (`cdebconf'), and the stabalization of the protocol these things use, the time has finally come to reflect the use of these things in policy. [2] `Debconf' or another tool that implements the Debian Configuration management specification will also be installed, and any versioned dependencies on it will be satisfied before preconfiguration begins. 2.4. Source packages -------------------- 2.4.1. Standards conformance ---------------------------- In the source package's `Standards-Version' control field, you should specify the most recent version number of this policy document with which your package complied when it was last updated. The current version number is 3.5.6.1. This information may be used to file bug reports automatically if your package becomes too much out of date. The version number has four components: major and minor version number and major and minor patch level. When the standards change in a way that requires every package to change the major number will be changed. Significant changes that will require work in many packages will be signaled by a change to the minor number. The major patch level will be changed for any change to the meaning of the standards, however small; the minor patch level will be changed when only cosmetic, typographical or other edits are made which neither change the meaning of the document nor affect the contents of packages. Thus only the first three components of the policy version are significant in the _Standards-Version_ control field, and so either these three components or the all four components may be specified.[1] You should regularly, and especially if your package has become out of date, check for the newest Policy Manual available and update your package, if necessary. When your package complies with the new standards you should update the `Standards-Version' source package field and release it.[2] [1] In the past, people specified the full version number in the Standards-Version field, for example `2.3.0.0'. Since minor patch-level changes don't introduce new policy, it was thought it would be better to relax policy and only require the first 3 components to be specified, in this example `2.3.0'. All four components may still be used if someone wishes to do so. [2] See the file `upgrading-checklist' for information about policy which has changed between different versions of this document. 2.4.2. Package relationships ---------------------------- Source packages should specify which binary packages they require to be installed or not to be installed in order to build correctly. For example, if building a package requires a certain compiler, then the compiler should be specified as a build-time dependency. It is not necessary to explicitly specify build-time relationships on a minimal set of packages that are always needed to compile, link and put in a Debian package a standard "Hello World!" program written in C or C++. The required packages are called _build-essential_, and an informational list can be found in `/usr/share/doc/build-essential/list' (which is contained in the `build-essential' package).[1] When specifying the set of build-time dependencies, one should list only those packages explicitly required by the build. It is not necessary to list packages which are required merely because some other package in the list of build-time dependencies depends on them.[2] If build-time dependencies are specified, it must be possible to build the package and produce working binaries on a system with only essential and build-essential packages installed and also those required to satisfy the build-time relationships (including any implied relationships). In particular, this means that version clauses should be used rigorously in build-time relationships so that one cannot produce bad or inconsistently configured packages when the relationships are properly satisfied. [1] Rationale: * This allows maintaining the list separately from the policy documents (the list does not need the kind of control that the policy documents do). * Having a separate package allows one to install the build-essential packages on a machine, as well as allowing other packages such as task packages to require installation of the build-essential packages using the depends relation. * The separate package allows bug reports against the list to be categorized separately from the policy management process in the BTS. [2] The reason for this is that dependencies change, and you should list all those packages, and _only_ those packages that _you_ need directly. What others need is their business. For example, if you only link against `libimlib', you will need to build-depend on `libimlib2-dev' but not against any `libjpeg*' packages, even though `libimlib2-dev' currently depends on them: installation of `libimlib2-dev' will automatically ensure that all of its run-time dependencies are satisfied. 2.4.3. Changes to the upstream sources -------------------------------------- If changes to the source code are made that are not specific to the needs of the Debian system, they should be sent to the upstream authors in whatever form they prefer so as to be included in the upstream version of the package. If you need to configure the package differently for Debian or for Linux, and the upstream source doesn't provide a way to do so, you should add such configuration facilities (for example, a new `autoconf' test or `#define') and send the patch to the upstream authors, with the default set to the way they originally had it. You can then easily override the default in your `debian/rules' or wherever is appropriate. You should make sure that the `configure' utility detects the correct architecture specification string (refer to Section 12.1, `Architecture specification strings' for details). If you need to edit a `Makefile' where GNU-style `configure' scripts are used, you should edit the `.in' files rather than editing the `Makefile' directly. This allows the user to reconfigure the package if necessary. You should _not_ configure the package and edit the generated `Makefile'! This makes it impossible for someone else to later reconfigure the package. 2.4.4. Documenting your changes ------------------------------- You should document your changes and updates to the source package properly in the `debian/changelog' file. (Note that mistakes in changelogs are usually best rectified by making a new changelog entry rather than "rewriting history" by editing old changelog entries.) In non-experimental packages you must use a format for `debian/changelog' which is supported by the most recent released version of `dpkg'.[1] [1] If you wish to use an alternative format, you may do so as long as you include a parser for it in your source package. The parser must have an API compatible with that expected by `dpkg-genchanges' and `dpkg-gencontrol'. If there is general interest in the new format, you should contact the `dpkg' maintainer to have the parser script for it included in the `dpkg' package. (You will need to agree that the parser and its manpage may be distributed under the GNU GPL, just as the rest of `dpkg' is.) 2.4.5. Error trapping in makefiles ---------------------------------- When `make' invokes a command in a makefile (including your package's upstream makefiles and `debian/rules'), it does so using `sh'. This means that `sh''s usual bad error handling properties apply: if you include a miniature script as one of the commands in your makefile you'll find that if you don't do anything about it then errors are not detected and `make' will blithely continue after problems. Every time you put more than one shell command (this includes using a loop) in a makefile command you must make sure that errors are trapped. For simple compound commands, such as changing directory and then running a program, using `&&' rather than semicolon as a command separator is sufficient. For more complex commands including most loops and conditionals you should include a separate `set -e' command at the start of every makefile command that's actually one of these miniature shell scripts. 2.4.6. Obsolete constructs and libraries ---------------------------------------- The include file `' is provided to support end-users compiling very old software; the library `libtermcap' is provided to support the execution of software which has been linked against it (either old programs or those such as Netscape which are only available in binary form). Debian packages should be patched to use `' and `ncurses' instead. ------------------------------------------------------------------------------- 3. Control files and their fields --------------------------------- Many of the tools in the package management suite manipulate data represented in a common format, known as _control data_. The data is often stored in _control files_. Binary and source packages have control files, and the `.changes' files which control the installation of uploaded files are also in control file format. `Dpkg''s internal databases are in a similar format. 3.1. Syntax of control files ---------------------------- A control file consists of one or more paragraphs of fields. The paragraphs are separated by blank lines. Some control files allow only one paragraph; others allow several, in which case each paragraph usually refers to a different package. (For example, in source packages, the first paragraph refers to the source package, and later paragraphs refer to binary packages generated from the source.) Each paragraph consists of a series of data fields; each field consists of the field name, followed by a colon and then the data/value associated with that field. It ends at the end of the line. Horizontal whitespace (spaces and tabs) may occur immediately before or after the value and is ignored there; it is conventional to put a single space after the colon. For example, a field might be: Package: libc6 the field name is `Package' and the field value `libc6'. Some fields' values may span several lines; in this case each continuation line _must_ start with a space or tab. Any trailing spaces or tabs at the end of individual lines of a field value are ignored. Except where otherwise stated only a single line of data is allowed and whitespace is not significant in a field body. Whitespace must not appear inside names (of packages, architectures, files or anything else) or version numbers, or between the characters of multi-character version relationships. Field names are not case-sensitive, but it is usual to capitalize the field names 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. 3.2. List of fields ------------------- This list here is not supposed to be exhaustive. Most fields are dealt with elsewhere in this document. 3.2.1. `Package' ---------------- The name of the binary package. Package names consist of the alphanumerics and `+' `-' `.' (plus, minus and full stop). They must be at least two characters long and must start with an alphanumeric character and not be all digits. The use of lowercase package names is strongly recommended unless the package you're building (or referring to, in other fields) is already using uppercase. 3.2.2. `Version' ---------------- This lists the source or binary package's version number - see Chapter 4, `Version numbering'. 3.2.3. `Standards-Version' -------------------------- The most recent version of the standards (the policy manual 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 described above; see Section 2.4.1, `Standards conformance'. 3.2.4. `Distribution' --------------------- In a `.changes' file or parsed changelog output this contains the (space-separated) name(s) of the distribution(s) where this version of the package should be installed. Valid distributions are determined by the archive maintainers.[1] [1] Current distribution names are: _stable_ This is the current `released' version of Debian GNU/Linux. Once the distribution is _stable_ only security fixes and other major bug fixes are allowed. When changes are made to this distribution, the release number is increased (for example: 2.2r1 becomes 2.2r2 then 2.2r3, etc). _unstable_ This distribution value refers to the _developmental_ part of the Debian distribution tree. New packages, new upstream versions of packages and bug fixes go into the _unstable_ directory tree. Download from this distribution at your own risk. _testing_ This distribution value refers to the _testing_ part of the Debian distribution tree. It receives its packages from the unstable distribution after a short time lag to ensure that there are no major issues with the unstable packages. It is less prone to breakage than unstable, but still risky. It is not possible to upload packages directly to _testing_. _frozen_ From time to time, the _testing_ distribution enters a state of `code-freeze' in anticipation of release as a _stable_ version. During this period of testing only fixes for existing or newly-discovered bugs will be allowed. The exact details of this stage are determined by the Release Manager. _experimental_ The packages with this distribution value are deemed by their maintainers to be high risk. Oftentimes they represent early beta or developmental packages from various sources that the maintainers want people to try, but are not ready to be a part of the other parts of the Debian distribution tree. Download at your own risk. You should list _all_ distributions that the package should be installed into. ------------------------------------------------------------------------------- 4. Version numbering -------------------- Every package has a version number recorded in its `Version' control file field. The package management system imposes an ordering on version numbers, so that it can tell whether packages are being up- or downgraded and so that package system front end applications 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: [`:'][`-'] The three components here are: This is a single (generally small) unsigned integer. It may be omitted, in which case zero is assumed. If it is omitted then the 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. This is the main part of the version number. It is usually the version number of the original (`upstream') package from which the `.deb' file has been made, if this is applicable. Usually this will be in the same format as that specified by the upstream author(s); however, it may need to be reformatted to fit into the package management system's format and comparison scheme. The comparison behavior of the package management system with respect to the is described below. The portion of the version number is mandatory. The may contain only alphanumerics[1] and the characters `.' `+' `-' `:' (full stop, plus, hyphen, colon) and should start with a digit. If there is no then hyphens are not allowed; if there is no then colons are not allowed. This part of the version number specifies the version of the Debian package based on the upstream version. It may contain only alphanumerics and the characters `+' and `.' (plus and full stop) and is compared in the same way as the is. It is optional; if it isn't present then the may not contain a hyphen. This format represents the case where a piece of software was written specifically to be turned into a Debian package, and so there is only one `debianization' of it and therefore no revision indication is required. It is conventional to restart the at `1' each time the is increased. The package management system will break the version number apart at the last hyphen in the string (if there is one) to determine the and . The absence of a compares earlier than the presence of one (but note that the is the least significant part of the version number). The and parts are compared by the package management system 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 (comparing and removing initial non-digit strings and initial digit strings) are repeated 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 scheme changes. It is _not_ intended to cope with version numbers containing strings of letters which the package management system cannot interpret (such as `ALPHA' or `pre-'), or with silly orderings (the author of this manual has heard of a package whose versions went `1.1', `1.2', `1.3', `1', `2.1', `2.2', `2' and so forth). If an upstream package has problematic version numbers they should be converted to a sane form for use in the `Version' field. [1] Alphanumerics are `A-Za-z0-9' only. 4.1. Version numbers based on dates ----------------------------------- In general, Debian packages should use the same version numbers as the upstream sources. However, in some cases where the upstream version number is based on a date (e.g., a development `snapshot' release) the package management system cannot handle these version numbers without epochs. For example, dpkg will consider `96May01' to be greater than `96Dec24'. To prevent having to use epochs for every new upstream version, the version number should be changed to the following format in such cases: `19960501', `19961224'. It is up to the maintainer whether he/she wants to bother the upstream maintainer to change the version numbers upstream, too. Note that other version formats based on dates which are parsed correctly by the package management system should _not_ be changed. Native Debian packages (i.e., packages which have been written especially for Debian) whose version numbers include dates should always use the `YYYYMMDD' format. ------------------------------------------------------------------------------- 5. Packaging Considerations --------------------------- 5.1. Time Stamps ---------------- Maintainers should preserve the modification times of the upstream source files in a package, as far as is reasonably possible.[1] [1] The rationale is that there is some information conveyed by knowing the age of the file, for example, you could recognize that some documentation is very old by looking at the modification time, so it would be nice if the modification time of the upstream source would be preserved. 5.2. `debian/rules' - the main building script ---------------------------------------------- This file must be an executable makefile, and contains the package-specific recipes for compiling the package and building binary package(s) from the source. It must start with the line `#!/usr/bin/make -f', so that it can be invoked by saying its name rather than invoking `make' explicitly. Since an interactive `debian/rules' script makes it impossible to auto-compile that package and also makes it hard for other people to reproduce the same binary package, all _required targets_ MUST be non-interactive. At a minimum, required targets are the ones called by `dpkg-buildpackage', namely, _clean_, _binary_, _binary-arch_, _binary-indep_, and _build_. It also follows that any target that these targets depend on must also be non-interactive. The required and optional targets are as follows: `build', `build-arch' (optional), `build-indep' (optional) The `build' target should perform all non-interactive configuration and compilation of the package. If a package has an interactive pre-build configuration routine, the Debianized source package must either be built after this has taken place (so that the binary package can be built without rerunning the configuration) or the configuration routine modified to become non-interactive. (The latter is preferable if there are architecture-specific features detected by the configuration routine.) For some packages, notably ones where the same source tree is compiled in different ways to produce two binary packages, the `build' target does not make much sense. For these packages it is good enough to provide two (or more) targets (`build-a' and `build-b' or whatever) for each of the ways of building the package, and a `build' target that does nothing. The `binary' target will have to build the package in each of the possible ways and make the binary package out of each. The `build' target must not do anything that might require root privilege. The `build' target may need to run the `clean' target first - see below. When a package has a configuration and build routine which takes a long time, or when the makefiles are poorly designed, or when `build' needs to run `clean' first, it is a good idea to `touch build' when the build process is complete. This will ensure that if `debian/rules build' is run again it will not rebuild the whole program.[1] `binary', `binary-arch', `binary-indep' The `binary' target must be all that is necessary for the user to build the binary package(s) produced from this source package. All of these targets are required to be non-interactive. It is split into two parts: `binary-arch' builds the binary packages which are specific to a particular architecture, and `binary-indep' builds those which are not. `binary' may be (and commonly is) a target with no commands which simply depends on `binary-arch' and `binary-indep'. Both `binary-*' targets should depend on the `build' target, or on the appropriate `build-arch' or `build-indep' target, if provided, so that the package is built if it has not been already. It should then create the relevant binary package(s), using `dpkg-gencontrol' to make their control files and `dpkg-deb' to build them and place them in the parent of the top level directory. Both the `binary-arch' and `binary-indep' targets _must_ exist. If one of them has nothing to do (which will always be the case if the source generates only a single binary package, whether architecture-dependent or not), it must still exist and must always succeed. The `binary' targets must be invoked as root.[2] `clean' This must undo any effects that the `build' and `binary' targets may have had, except that it should leave alone any output files created in the parent directory by a run of a `binary' target. This target must be non-interactive. If a `build' file is touched at the end of the `build' target, as suggested above, it should be removed as the first action that `clean' performs, so that running `build' again after an interrupted `clean' doesn't think that everything is already done. The `clean' target may need to be invoked as root if `binary' has been invoked since the last `clean', or if `build' has been invoked as root (since `build' may create directories, for example). `get-orig-source' (optional) This target fetches the most recent version of the original source package from a canonical archive site (via FTP or WWW, for example), does any necessary rearrangement to turn it into the original source tar file format described below, and leaves it in the current directory. This target may be invoked in any directory, and should take care to clean up any temporary files it may have left. This target is optional, but providing it if possible is a good idea. The `build', `binary' and `clean' targets must be invoked with the current directory being the package's top-level directory. Additional targets may exist in `debian/rules', either as published or undocumented interfaces or for the package's internal use. The architectures we build on and build for are determined by `make' variables using the utility `dpkg-architecture'. You can determine the Debian architecture and the GNU style architecture specification string for the build machine (the machine type we are building on) as well as for the host machine (the machine type we are building for). Here is a list of supported `make' variables: * `DEB_*_ARCH' (the Debian architecture) * `DEB_*_GNU_TYPE' (the GNU style architecture specification string) * `DEB_*_GNU_CPU' (the CPU part of `DEB_*_GNU_TYPE') * `DEB_*_GNU_SYSTEM' (the System part of `DEB_*_GNU_TYPE') where `*' is either `BUILD' for specification of the build machine or `HOST' for specification of the host machine. Backward compatibility can be provided in the rules file by setting the needed variables to suitable default values; please refer to the documentation of `dpkg-architecture' for details. It is important to understand that the `DEB_*_ARCH' string only determines which Debian architecture we are building on or for. It should not be used to get the CPU or system information; the GNU style variables should be used for that. [1] Another common way to do this is for `build' to depend on `build-stamp' and to do nothing else, and for the `build-stamp' target to do the building and to `touch build-stamp' on completion. This is especially useful if the build routine creates a file or directory called `build'; in such a case, `build' will need to be listed as a phony target (i.e., as a dependency of the `.PHONY' target). See the documentation of `make' for more information on phony targets. [2] The `fakeroot' package often allows one to build a package correctly even without being root. 5.3. `debian/changelog' ----------------------- This file records the changes to the Debian-specific parts of the package[1]. 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: () ; urgency= * * -- <><[two spaces]> and are the source package name and version number. lists the distributions where this version should be installed when it is uploaded - it is copied to the `Distribution' field in the `.changes' file. See Section 3.2.4, ``Distribution''. is the value for the `Urgency' field in the `.changes' file for the upload. It is not possible to specify an urgency containing commas; commas are used to separate `=' settings in the `dpkg' changelog format (though there is currently only one useful , `urgency').[2] 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. If this upload resolves bugs recorded in the Bug Tracking System (BTS), they may be automatically closed on the inclusion of this package into the Debian archive by including the string: `closes: Bug#' in the change details.[3] The maintainer name and email address used in the changelog should be the details of the person uploading _this_ version. They are _not_ necessarily those of the usual package maintainer. The information here will be copied to the `Changed-By' field in the `.changes' file, and then later used to send an acknowledgement when the upload has been installed. The should be in RFC822 format[4]; it should include the time zone specified numerically, with the time zone name or abbreviation optionally present as a comment in parentheses. 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. [1] 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. In such a case, however, it might be better to maintain the package as a non-native package. [2] Recognised urgency values are `low', `medium', `high' and `emergency'. They have an effect on how quickly a package will be considered for inclusion into the `testing' distribution, and give an indication of the importance of any fixes included in this upload. [3] To be precise, the string should match the following Perl regular expression: /closes:\s*(?:bug)?\#?\s?\d+(?:,\s*(?:bug)?\#?\s?\d+)*/i Then all of the bug numbers listed will be closed by the archive maintenance script (`katie'), or in the case of an NMU, marked as fixed. [4] This is generated by the `822-date' program. 5.3.1. 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. A changelog parser must not interact with the user at all. 5.4. `debian/substvars' and variable substitutions -------------------------------------------------- When `dpkg-gencontrol', `dpkg-genchanges' and `dpkg-source' generate control files they perform variable substitutions on their output just before writing it. Variable substitutions have the form `${}'. The optional file `debian/substvars' contains variable substitutions to be used; variables can also be set directly from `debian/rules' using the `-V' option to the source packaging commands, and certain predefined variables are also available. The `debian/substvars' file is usually generated and modified dynamically by `debian/rules' targets; in this case it must be removed by the `clean' target. See dpkg-source(1) for full details about source variable substitutions, including the format of `debian/substvars'. 5.5. `debian/files' ------------------- This file is not a permanent part of the source tree; it is used while building packages to record which files are being generated. `dpkg-genchanges' uses it when it generates a `.changes' file. It should not exist in a shipped source package, and so it (and any backup files or temporary files such as `files.new'[1]) should be removed by the `clean' target. It may also be wise to ensure a fresh start by emptying or removing it at the start of the `binary' target. When `dpkg-gencontrol' is run for a binary package, it adds an entry to `debian/files' for the `.deb' file that will be created when `dpkg-deb --build' is run for that binary package. So for most packages all that needs to be done with this file is to delete it in the `clean' target. If a package upload includes files besides the source package and any binary packages whose control files were made with `dpkg-gencontrol' then they should be placed in the parent of the package's top-level directory and `dpkg-distaddfile' should be called to add the file to the list in `debian/files'. [1] `files.new' is used as a temporary file by `dpkg-gencontrol' and `dpkg-distaddfile' - they write a new version of `files' here before renaming it, to avoid leaving a corrupted copy if an error occurs 5.6. Restrictions on objects in source packages ----------------------------------------------- The source package may not contain any hard links[1], device special files, sockets or setuid or setgid files.[2] [1] This is not currently detected when building source packages, but only when extracting them. Hard links may be permitted at some point in the future, but would require a fair amount of work. [2] Setgid directories are allowed. 5.7. Descriptions of packages - the `Description' field ------------------------------------------------------- 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. 5.7.1. Notes about writing descriptions --------------------------------------- The single line synopsis should be kept brief - certainly under 80 characters. Do not include the package name in the synopsis line. The display software knows how to display this already, and you do not need to state it. Remember that in many situations the user may only see the synopsis line - make it as informative as you can. Do not try to continue the single line synopsis into the extended description. This will not work correctly when the full description is displayed, and makes no sense where only the summary (the single line synopsis) is available. 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 description field needs to make sense to anyone, even people who have no idea about any of the things the package deals with.[1] Put important information first, both in the synopsis 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. [1] The blurb that comes with a program in its announcements and/or `README' files is rarely suitable for use in a description. It is usually aimed at people who are already in the community where the package is used. ------------------------------------------------------------------------------- 6. Package maintainer scripts and installation procedure -------------------------------------------------------- 6.1. Introduction to package maintainer scripts ----------------------------------------------- It is possible to supply scripts as part of a package which the package management system will run for you when your package is installed, upgraded or removed. These scripts are the files `preinst', `postinst', `prerm' and `postrm' in the control area of the package. They must be proper executable files; if they are scripts (which is recommended), they must start with the usual `#!' convention. They should be readable and executable by anyone, and not world-writable. The package management system 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 the package management system can stop its processing. For shell scripts this means that you _almost always_ need to use `set -e' (this is usually true when writing shell scripts, in fact). It is also important, of course, that they don't exit with a non-zero status if everything went well. When a package is upgraded a combination of the scripts from the old and new packages is called during the upgrade procedure. If your scripts are going to be at all complicated you need to be aware of this, and may need to check the arguments to your scripts. Broadly speaking the `preinst' is called before (a particular version of) a package is installed, and the `postinst' afterwards; the `prerm' before (a version of) a package is removed and the `postrm' afterwards. Programs called from maintainer scripts should not normally have a path prepended to them. Before installation is started, the package management system checks to see if the programs `ldconfig', `start-stop-daemon', `install-info', and `update-rc.d' can be found via the `PATH' environment variable. Those programs, and any other program that one would expect to be on the `PATH', should thus be invoked without an absolute pathname. Maintainer scripts should also not reset the `PATH', though they might choose to modify it by prepending or appending package-specific directories. These considerations really apply to all shell scripts. 6.2. Maintainer scripts Idempotency ----------------------------------- It is necessary for the error recovery procedures that the scripts be idempotent. This means that if it is run successfully, and then it is called again, it doesn't bomb out or cause any harm, but just ensures that everything is the way it ought to be. 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 if everything is OK.[1] [1] This is so that if an error occurs, the user interrupts `dpkg' or some other unforeseen circumstance happens you don't leave the user with a badly-broken package when `dpkg' attempts to repeat the action. 6.3. Controlling terminal for maintainer scripts ------------------------------------------------ The maintainer scripts are guaranteed to run with a controlling terminal and can interact with the user. If they need to prompt for passwords, do full-screen interaction or something similar you should do these things to and from `/dev/tty', since `dpkg' will at some point redirect scripts' standard input and output so that it can log the installation process. Likewise, because these scripts may be executed with standard output redirected into a pipe for logging purposes, Perl scripts should set unbuffered output by setting `$|=1' so that the output is printed immediately rather than being buffered. Each script should return a zero exit status for success, or a nonzero one for failure. 6.4. Summary of ways maintainer scripts are called -------------------------------------------------- * `install' * `install' * `upgrade' * `abort-upgrade' * `configure' * `abort-upgrade' * `abort-remove' `in-favour' * `abort-deconfigure' `in-favour' `removing' * `remove' * `upgrade' * `failed-upgrade' * `remove' `in-favour' * `deconfigure' `in-favour' `removing' * `remove' * `purge' * `upgrade' * `failed-upgrade' * `abort-install' * `abort-install' * `abort-upgrade' * `disappear' 6.5. Details of unpack phase of installation or upgrade ------------------------------------------------------- The procedure on installation/upgrade/overwrite/disappear (i.e., when running `dpkg --unpack', or the unpack stage of `dpkg --install') is as follows. In each case, if a major error occurs (unless listed below) the actions are, in 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. 1. 1. If a version of the package is already installed, call upgrade 2. If the script runs but exits with a non-zero exit status, `dpkg' will attempt: failed-upgrade Error unwind, for both the above cases: abort-upgrade 2. If a `conflicting' package is being removed at the same time: 1. If any packages depended on that conflicting package and `--auto-deconfigure' is specified, call, for each such package: deconfigure \ in-favour \ removing Error unwind: abort-deconfigure \ in-favour \ removing The deconfigured packages are marked as requiring configuration, so that if `--install' is used they will be configured again if possible. 2. To prepare for removal of the conflicting package, call: remove \ in-favour Error unwind: abort-remove \ in-favour 3. 1. If the package is being upgraded, call: upgrade 2. Otherwise, if the package had some configuration files from a previous version installed (i.e., it is in the `configuration files only' state): install 3. Otherwise (i.e., the package was completely purged): install Error unwind actions, respectively: abort-upgrade abort-install abort-install 4. 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 kept temporarily, and if anything goes wrong the package management system will attempt to put them back as part of the error unwind. It is an error for a package to contains files which are on the system in another package, unless `Replaces' is used (see Section 7.5, `Overwriting files and replacing packages - `Replaces''). It is a more serious error for a package to contain a plain file or other kind of non-directory where another package has a directory (again, unless `Replaces' is used). This error can be overridden if desired using `--force-overwrite-dir', but this is not advisable. Packages which overwrite each other's files produce behavior 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.[1] A directory will never be replaced by a symbolic link to a directory or vice versa; instead, the existing state (symlink or not) will be left alone and `dpkg' will follow the symlink if there is one. 5. 1. If the package is being upgraded, call upgrade 2. If this fails, `dpkg' will attempt: failed-upgrade Error unwind, for both cases: abort-upgrade This is the point of no return - if `dpkg' gets this far, it won't back off past this point if an error occurs. This will leave the package in a fairly bad state, which will require a successful re-installation to clear up, but it's when `dpkg' starts doing things that are irreversible. 6. Any files which were in the old version of the package but not in the new are removed. 7. The new file list replaces the old. 8. The new maintainer scripts replace the old. 9. 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 1. `dpkg' calls: disappear \ 2. The package's maintainer scripts are removed. 3. It is noted in the status database as being in a sane state, namely not installed (any conffiles it may have are ignored, rather than being removed by `dpkg'). Note that disappearing packages do not have their prerm called, because `dpkg' doesn't know in advance that the package is going to vanish. 10. 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 lobotomize the file list of the `conflicting' package if there is one.) 11. The backup files made during installation, above, are deleted. 12. 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. 13. 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). [1] Part of the problem is due to what is arguably a bug in `dpkg'. 6.6. Details of configuration ----------------------------- When we configure a package (this happens with `dpkg --install' and `dpkg --configure'), we first update any `conffile's and then call: configure No attempt is made to unwind after errors during configuration. If there is no most recently configured version `dpkg' will pass a null argument; older versions of dpkg may pass `' (including the angle brackets) in this case. Even older ones do not pass a second argument at all, under any circumstances. 6.7. Details of removal and/or configuration purging ---------------------------------------------------- 1. remove 2. The package's files are removed (except `conffile's). 3. remove 4. 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 `conffile's are automatically purged when removed, as there is no difference except for the `dpkg' status. 5. The `conffile's and any backup files (`~'-files, `#*#' files, `%'-files, `.dpkg-{old,new,tmp}', etc.) are removed. 6. purge 7. The package's file list is removed. No attempt is made to unwind after errors during removal. ------------------------------------------------------------------------------- 7. Declaring relationships between packages ------------------------------------------- Packages can declare in their control file that they have certain relationships to other packages - for example, that they may not be installed at the same time as certain other packages, and/or that they depend on the presence of others, or that they should overwrite files in certain other packages if present. This is done using the `Depends', `Pre-Depends', `Recommends', `Suggests', `Enhances', `Conflicts', `Provides' and `Replaces' control file fields. Source packages may declare relationships to binary packages, saying that they require certain binary packages to be installed or absent at the time of building the package. This is done using the `Build-Depends', `Build-Depends-Indep', `Build-Conflicts' and `Build-Conflicts-Indep' control file fields. 7.1. Syntax of relationship fields ---------------------------------- These fields all have a uniform syntax. They are a list of package names separated by commas. In the `Depends', `Recommends', `Suggests', `Pre-Depends', `Build-Depends' and `Build-Depends-Indep' control file fields of the package, which declare dependencies on other packages, the package names listed may also include lists of alternative package names, separated by vertical bar (pipe) symbols `|'. In such a case, if any one of the alternative packages is installed, that part of the dependency is considered to be satisfied. All of the fields except for `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 Chapter 4, `Version numbering'. The relations allowed are `<<', `<=', `=', `>=' and `>>' for strictly earlier, earlier or equal, exactly equal, later or equal and strictly later, respectively. The deprecated forms `<' and `>' were used to mean earlier/later or equal, rather than strictly earlier/later, so they should not appear in new packages (though `dpkg' still supports them). Whitespace may appear at any point in the version specification subject to the rules in Section 3.1, `Syntax of control files', and must appear where it's necessary to disambiguate; it is not otherwise significant. For consistency and in case of future changes to `dpkg' it is recommended that a single space be used after a version relationship and before a version number; it is also conventional to put a single space after each comma, on either side of each vertical bar, and before each open parenthesis. For example, a list of dependencies might appear as: Package: mutt Version: 1.3.17-1 Depends: libc6 (>= 2.2.1), exim | mail-transport-agent All fields that specify build-time relationships (`Build-Depends', `Build-Depends-Indep', `Build-Conflicts' and `Build-Conflicts-Indep') may be restricted to a certain set of architectures. This is indicated in brackets after each individual package name and the optional version specification. The brackets enclose a list of Debian architecture names separated by whitespace. Exclamation marks may be prepended to each of the names. (It is not permitted for some names to be prepended with exclamation marks and others not.) If the current Debian host architecture is not in this list and there are no exclamation marks in the list, or it is in the list with a prepended exclamation mark, the package name and the associated version specification are ignored completely for the purposes of defining the relationships. For example: Source: glibc Build-Depends-Indep: texinfo Build-Depends: kernel-headers-2.2.10 [!hurd-i386], hurd-dev [hurd-i386], gnumach-dev [hurd-i386] Note that the binary package relationship fields such as `Depends' appear in one of the binary package sections of the control file, whereas the build-time relationships such as `Build-Depends' appear in the source package section of the control file (which is the first section). 7.2. Binary Dependencies - `Depends', `Recommends', `Suggests', `Enhances', `Pre-Depends' ---------------------------------------------------------------------------- These five fields are used to declare a dependency relationship by one package on another. Except for `Enhances', they appear in the depending (binary) package's control file. (`Enhances' appears in the recommending package's control file.) A `Depends' field takes effect _only_ when a package is to be configured. It does 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. If it is necessary, a `Pre-Depends' field can be used, which has a partial effect even when a package is being unpacked, as explained in detail below. (The other three dependency fields, `Recommends', `Suggests' and `Enhances', are only used by the various front-ends to `dpkg' such as `dselect'.) 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. The `Depends' field thus allows package maintainers to impose an order in which packages should be configured. The meaning of the five dependency fields is as follows: `Depends' This declares an absolute dependency. A package will not be configured unless all of the packages listed in its `Depends' field have been correctly configured. The `Depends' field should be used if the depended-on package is required for the depending package to provide a significant amount of functionality. The `Depends' field should also be used if the `postinst', `prerm' or `postrm' scripts require the package to be present in order to run. Note, however, that the `postrm' cannot rely on any non-essential packages to be present during the `purge' phase. `Recommends' This declares a strong, but not absolute, dependency. The `Recommends' field should list packages that would be found together with this one in all but unusual installations. `Suggests' This is used to declare that one package may be more useful with one or more others. Using this field tells the packaging system and the user that the listed packages are related to this one and can perhaps enhance its usefulness, but that installing this one without them is perfectly reasonable. `Enhances' This field is similar to Suggests but works in the opposite direction. It is used to declare that a package can enhance the functionality of another package. `Pre-Depends' This field is like `Depends', except that it also forces `dpkg' to complete installation of the packages named before even starting the installation of the package which declares the pre-dependency, as follows: When a package declaring a pre-dependency is about to be _unpacked_ the pre-dependency can be satisfied if the depended-on package is either fully configured, _or even if_ the depended-on package(s) are only unpacked or half-configured, provided that they have been configured correctly at some point in the past (and not removed or partially removed since). In this case, both the previously-configured and currently unpacked or half-configured versions must satisfy any version clause in the `Pre-Depends' field. When the package declaring a pre-dependency is about to be _configured_, the pre-dependency will be treated as a normal `Depends', that is, it will be considered satisfied only if the depended-on package has been correctly configured. `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. `Pre-Depends' are also required if the `preinst' script depends on the named package. It is best to avoid this situation if possible. When selecting which level of dependency to use you should consider how important the depended-on package is to the functionality of the one declaring the dependency. Some packages are composed of components of varying degrees of importance. Such a package should list using `Depends' the package(s) which are required by the more important components. The other components' requirements may be mentioned as Suggestions or Recommendations, as appropriate to the components' relative importance. 7.3. Conflicting binary packages - `Conflicts' ---------------------------------------------- When one binary package declares a conflict with another using a `Conflicts' field, `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 (see Section 7.5, `Overwriting files and replacing packages - `Replaces'') the one on the system, or the one on the system is marked as deselected, or both packages are marked `Essential', then `dpkg' will automatically remove the package which is causing the conflict, otherwise it will halt the installation of the new package with an error. This mechanism is specifically designed to produce an error when the installed package is `Essential', but the new package is not. 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 some feature. A `Conflicts' entry should almost never have an `earlier than' version clause. This would prevent `dpkg' from upgrading or installing the package which declared such a conflict until the upgrade or removal of the conflicted-with package had been completed. 7.4. Virtual packages - `Provides' ---------------------------------- As well as the names of actual (`concrete') packages, the package relationship fields `Depends', `Recommends', `Suggests', `Enhances', `Pre-Depends', `Conflicts', `Build-Depends', `Build-Depends-Indep', `Build-Conflicts' and `Build-Conflicts-Indep' may mention `virtual packages'. A _virtual package_ is one which appears in the `Provides' control file field of another package. The effect is as if the package(s) which provide a particular virtual package name had been listed by name everywhere the virtual package name appears. If there are both a real and a virtual package of the same name then the dependency may be satisfied (or the conflict caused) by either the real package or any of the virtual packages which provide it. This is so that, for example, supposing we have Package: foo Depends: bar and someone else releases an enhanced version of the `bar' package (for example, a non-US variant), they can say: Package: bar-plus Provides: bar and the `bar-plus' package will now also satisfy the dependency for the `foo' package. 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 the virtual package is not of the `right' version. So, a `Provides' field may not contain version numbers, and the version number of the concrete package which provides a particular virtual package will not be looked at when considering a dependency on or conflict with the virtual package name. It is likely that the ability will be added in a future release of `dpkg' to specify a version number for each virtual package it provides. This feature is not yet present, however, and is expected to be used only infrequently. If you want to specify which of a set of real packages should be the default to satisfy a particular dependency on a virtual package, you should list the real package as an alternative before the virtual one. 7.5. Overwriting files and replacing packages - `Replaces' ---------------------------------------------------------- The `Replaces' control file field has two distinct purposes, which come into play in different situations. 7.5.1. Overwriting files in other packages ------------------------------------------ Firstly, as mentioned before, it is usually an error for a package to contain files which are on the system in another package. However, if the overwriting package declares that it `Replaces' the one containing the file being overwritten, then `dpkg' will replace the file from the old package with that from the new. The file will no longer be listed as `owned' by the old package. If a package is completely replaced in this way, so that `dpkg' does not know of any files it still contains, it is considered to have `disappeared'. It will be marked as not wanted on the system (selected for removal) and not installed. Any `conffile's details noted for the package will be ignored, as they will have been taken over by the overwriting package. The package's `postrm' script will be run with a special argument to allow the package to do any final cleanup required. See Section 6.4, `Summary of ways maintainer scripts are called'. If an installed package, `foo' say, declares that it replaces another, `bar', and an attempt is made to install `bar', `dpkg' will discard files in the `bar' package which would overwrite those already present in `foo'. This is so that you can install an older version of a package without problems. For this usage of `Replaces', virtual packages (see Section 7.4, `Virtual packages - `Provides'') are not considered when looking at a `Replaces' field - the packages declared as being replaced must be mentioned by their real names. Furthermore, this usage of `Replaces' only takes effect when both packages are at least partially on the system at once, so that it can only happen if they do not conflict or if the conflict has been overridden. 7.5.2. Replacing whole packages, forcing their removal ------------------------------------------------------ Secondly, `Replaces' allows the packaging system to resolve which package should be removed when there is a conflict - see Section 7.3, `Conflicting binary packages - `Conflicts''. This usage only takes effect when the two packages _do_ conflict, so that the two usages of this field do not interfere with each other. In this situation, the package declared as being replaced can be a virtual package, so for example, all mail transport agents (MTAs) would have the following fields in their control files: Provides: mail-transport-agent Conflicts: mail-transport-agent Replaces: mail-transport-agent ensuring that only one MTA can be installed at any one time. 7.6. Relationships between source and binary packages - `Build-Depends', `Build-Depends-Indep', `Build-Conflicts', `Build-Conflicts-Indep' ---------------------------------------------------------------------------- A source package may declare a dependency or a conflict on a binary package, indicating which packages are required to be present on the system in order to build the binary packages from the source package. This is done with the control file fields `Build-Depends', `Build-Depends-Indep', `Build-Conflicts' and `Build-Conflicts-Indep'. The dependencies and conflicts they define must be satisfied (as defined earlier for binary packages) in order to invoke the targets in `debian/rules', as follows: `Build-Depends', `Build-Conflicts' The `Build-Depends' and `Build-Conflicts' fields must be satisfied when any of the following targets is invoked: `build', `binary', `binary-arch' and `binary-indep'. `Build-Depends-Indep', `Build-Conflicts-Indep' The `Build-Depends-Indep' and `Build-Conflicts-Indep' fields must be satisfied when any of the following targets is invoked: `binary' and `binary-indep'. ------------------------------------------------------------------------------- 8. Configuration file handling ------------------------------ This chapter has been superseded by Section 11.7, `Configuration files'. ------------------------------------------------------------------------------- 9. 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 C library (currently `libc6'). Firstly, the package should install the shared libraries under their normal names. For example, the `libgdbmg1' package should install `libgdbm.so.1.7.3' as `/usr/lib/libgdbm.so.1.7.3'. The files should not be renamed or re-linked by any `prerm' or `postrm' scripts; `dpkg' will take care of renaming things safely without affecting running programs, and attempts to interfere with this are likely to lead to problems. Secondly, the package should include the symbolic link that `ldconfig' would create for the shared libraries. For example, the `libgdbmg1' package should include a symbolic link from `/usr/lib/libgdbm.so.1' to `libgdbm.so.1.7.3'. This is needed so that the dynamic linker (for example `ld.so' or `ld-linux.so.*') can find the library between the time that `dpkg' installs it and the time that `ldconfig' is run in the `postinst' script.[1] Thirdly, the associated development package should contain a symlink for the shared library without a version number. For example, the `libgdbmg1-dev' package should include a symlink from `/usr/lib/libgdbm.so' to `libgdbm.so.1.7.3'. This symlink is needed by the linker (`ld') when compiling packages, as it will only look for `libgdbm.so' when compiling dynamically. Any package installing shared libraries in one of the default library directories of the dynamic linker (which are currently `/usr/lib' and `/lib') or a directory that is listed in `/etc/ld.so.conf'[2] must call `ldconfig' in its `postinst' script if the first argument is `configure' and should call it in the `postrm' script if the first argument is `remove'. However, `postrm' and `preinst' scripts _must not_ call `ldconfig' in the case where the package is being upgraded (see Section 6.5, `Details of unpack phase of installation or upgrade' for details), as `ldconfig' will see the temporary names that `dpkg' uses for the files while it is installing them and will make the shared library links point to them, just before `dpkg' continues the installation and renames the temporary files! [1] The package management system requires the library to be placed before the symbolic link pointing to it in the `.deb' file. This is so that when `dpkg' comes to install the symlink (overwriting the previous symlink pointing at an older version of the library), the new shared library is already in place. In the past, this was achieved by creating the library in the temporary packaging directory before creating the symlink. Unfortunately, this was not always effective, since the building of the tar file in the `.deb' depended on the behavior of the underlying file system. Some file systems (such as reiserfs) reorder the files so that the order of creation is forgotten. Starting with release `1.7.0', `dpkg' will reorder the files itself as necessary when building a package. Thus it is no longer important to concern oneself with the order of file creation. [2] These are currently * /usr/X11R6/lib/Xaw3d * /usr/local/lib * /usr/lib/libc5-compat * /lib/libc5-compat * /usr/X11R6/lib 9.1. Handling shared library dependencies - the `shlibs' system --------------------------------------------------------------- If a package contains a binary or library which links to a shared library, we must ensure that when the package is installed on the system, all of the libraries needed are also installed. This requirement led to the creation of the `shlibs' system, which is very simple in its design: any package which _provides_ a shared library also provides information on the package dependencies required to ensure the presence of this library, and any package which _uses_ a shared library uses this information to determine the dependencies it requires. The files which contain the mapping from shared libraries to the necessary dependency information are called `shlibs' files. Thus, when a package is built which contains any shared libraries, it must provide a `shlibs' file for other packages to use, and when a package is built which contains any shared libraries or compiled binaries, it must run `dpkg-shlibdeps' on these to determine the libraries used and hence the dependencies needed by this package.[1] In the following sections, we will first describe where the various `shlibs' files are to be found, then how to use `dpkg-shlibdeps', and finally the `shlibs' file format and how to create them if your package contains a shared library. [1] In the past, the shared libraries linked to were determined by calling `ldd', but now `objdump' is used to do this. The only change this makes to package building is that `dpkg-shlibdeps' must also be run on shared libraries, whereas in the past this was unnecessary. The rest of this footnote explains the advantage that this method gives. We say that a binary `foo' _directly_ uses a library `libbar' if it is explicitly linked with that library (that is, it uses the flag `-lbar' during the linking stage). Other libraries that are needed by `libbar' are linked _indirectly_ to `foo', and the dynamic linker will load them automatically when it loads `libbar'. A package should depend on the libraries it directly uses, and the dependencies for those libraries should automatically pull in the other libraries. Unfortunately, the `ldd' program shows both the directly and indirectly used libraries, meaning that the dependencies determined included both direct and indirect dependencies. The use of `objdump' avoids this problem by determining only the directly used libraries. A good example of where this helps is the following. We could update `libimlib' with a new version that supports a new graphics format called dgf (but retaining the same major version number). If we used the old `ldd' method, every package that uses `libimlib' would need to be recompiled so it would also depend on `libdgf' or it wouldn't run due to missing symbols. However with the new system, packages using `libimlib' can rely on `libimlib' itself having the dependency on `libdgf' and so they would not need rebuilding. 9.2. The `shlibs' files present on the system --------------------------------------------- There are several places where `shlibs' files are found. The following list gives them in the order in which they are read by `dpkg-shlibdeps'. (The first one which gives the required information is used.) * `debian/shlibs.local' This lists overrides for this package. Its use is described below (see Section 9.6, `Writing the `debian/shlibs.local' file'). * `/etc/dpkg/shlibs.override' This lists global overrides. This list is normally empty. It is maintained by the local system administrator. * `DEBIAN/shlibs' files in the `build directory' When packages are being built, any `debian/shlibs' files are copied into the control file area of the temporary build directory and given the name `shlibs'. These files give details of any shared libraries included in the package.[1] * `/var/lib/dpkg/info/*.shlibs' These are the `shlibs' files corresponding to all of the packages installed on the system, and are maintained by the relevant package maintainers. * `/etc/dpkg/shlibs.default' This file lists any shared libraries whose packages have failed to provide correct `shlibs' files. It was used when the `shlibs' setup was first introduced, but it is now normally empty. It is maintained by the `dpkg' maintainer. [1] An example may help here. Let us say that the source package `foo' generates two binary packages, `libfoo2' and `foo-runtime'. When building the binary packages, the two packages are created in the directories `debian/libfoo2' and `debian/foo-runtime' respectively. (`debian/tmp' could be used instead of one of these.) Since `libfoo2' provides the `libfoo' shared library, it will require a `shlibs' file, which will be installed in `debian/libfoo2/DEBIAN/shlibs', eventually to become `/var/lib/dpkg/info/libfoo2.shlibs'. Then when `dpkg-shlibdeps' is run on the executable `debian/foo-runtime/usr/bin/foo-prog', it will examine the `debian/libfoo2/DEBIAN/shlibs' file to determine whether `foo-prog''s library dependencies are satisfied by any of the libraries provided by `libfoo2'. For this reason, `dpkg-shlibdeps' must only be run once all of the individual binary packages' `shlibs' files have been installed into the build directory. 9.3. How to use `dpkg-shlibdeps' and the `shlibs' files ------------------------------------------------------- Put a call to `dpkg-shlibdeps' into your `debian/rules' file. If your package contains only compiled binaries and libraries (but no scripts), you can use a command such as: dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* \ debian/tmp/usr/lib/* Otherwise, you will need to explicitly list the compiled binaries and libraries.[1] This command puts the dependency information into the `debian/substvars' file, which is then used by `dpkg-gencontrol'. You will need to place a `${shlib:Depends}' variable in the `Depends' field in the control file for this to work. If `dpkg-shlibdeps' doesn't complain, you're done. If it does complain you might need to create your own `debian/shlibs.local' file, as explained below (see Section 9.6, `Writing the `debian/shlibs.local' file'). If you have multiple binary packages, you will need to call `dpkg-shlibdeps' on each one which contains compiled libraries or binaries. In such a case, you will need to use the `-T' option to the `dpkg' utilities to specify a different `substvars' file. For more details on this and other options, see dpkg-shlibdeps(1). [1] If you are using `debhelper', the `dh_shlibdeps' program will do this work for you. It will also correctly handle multi-binary packages. 9.4. The `shlibs' File Format ----------------------------- Each `shlibs' file has the same format. Lines beginning with `#' are considered to be comments and are ignored. Each line is of the form: We will explain this by reference to the example of the `zlib1g' package, which (at the time of writing) installs the shared library `/usr/lib/libz.so.1.1.3'. is the name of the shared library, in this case `libz'. (This must match the name part of the soname, see below.) is the version part of the soname of the library. The soname is the thing that must exactly match for the library to be recognized by the dynamic linker, and is usually of the form `.so.', in our example, `libz.so.1'.[1] The version part is the part which comes after `.so.', so in our case, it is `1'. has the same syntax as a dependency field in a binary package control file. It should give details of which packages are required to satisfy a binary built against the version of the library contained in the package. See Section 7.1, `Syntax of relationship fields' for details. In our example, if the first version of the `zlib1g' package which contained a minor number of at least `1.3' was <1:1.1.3-1>, then the `shlibs' entry for this library could say: libz 1 zlib1g (>= 1:1.1.3) The version-specific dependency is to avoid warnings from the dynamic linker about using older shared libraries with newer binaries. [1] This can be determined using the command objdump -p /usr/lib/libz.so.1.1.3 | grep SONAME 9.5. Providing a `shlibs' file ------------------------------ If your package provides a shared library, you should create a `shlibs' file following the format described above. It is usual to call this file `debian/shlibs' (but if you have multiple binary packages, you might want to call it `debian/shlibs.' instead). Then let `debian/rules' install it in the control area: install -m644 debian/shlibs debian/tmp/DEBIAN or, in the case of a multi-binary package: install -m644 debian/shlibs. debian//DEBIAN/shlibs An alternative way of doing this is to create the `shlibs' file in the control area directly from `debian/rules' without using a `debian/shlibs' file at all,[1] since the `debian/shlibs' file itself is ignored by `dpkg-shlibdeps'. As `dpkg-shlibdeps' reads the `DEBIAN/shlibs' files in all of the binary packages being built from this source package, all of the `DEBIAN/shlibs' files should be installed before `dpkg-shlibdeps' is called on any of the binary packages. [1] This is what `dh_makeshlibs' in the `debhelper' suite does. 9.6. Writing the `debian/shlibs.local' file ------------------------------------------- This file is intended only as a _temporary_ fix if your binaries or libraries depend on a library whose package does not yet provide a correct `shlibs' file. We will assume that you are trying to package a binary `foo'. When you try running `dpkg-shlibdeps' you get the following error message (`-O' displays the dependency information on `stdout' instead of writing it to `debian/substvars', and the lines have been wrapped for ease of reading): $ dpkg-shlibdeps -O debian/tmp/usr/bin/foo dpkg-shlibdeps: warning: unable to find dependency information for shared library libbar (soname 1, path /usr/lib/libbar.so.1, dependency field Depends) shlibs:Depends=libc6 (>= 2.2.2-2) You can then run `ldd' on the binary to find the full location of the library concerned: $ ldd foo libbar.so.1 => /usr/lib/libbar.so.1 (0x4001e000) libc.so.6 => /lib/libc.so.6 (0x40032000) /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000) So the `foo' binary depends on the `libbar' shared library, but no package seems to provide a `*.shlibs' file handling `libbar.so.1' in `/var/lib/dpkg/info/'. Let's determine the package responsible: $ dpkg -S /usr/lib/libbar.so.1 bar1: /usr/lib/libbar.so.1 $ dpkg -s bar1 | grep Version Version: 1.0-1 This tells us that the `bar1' package, version 1.0-1, is the one we are using. Now we can file a bug against the `bar1' package and create our own `debian/shlibs.local' to locally fix the problem. Including the following line into your `debian/shlibs.local' file: libbar 1 bar1 (>= 1.0-1) should allow the package build to work. As soon as the maintainer of `bar1' provides a correct `shlibs' file, you should remove this line from your `debian/shlibs.local' file. (You should probably also then have a versioned `Build-Depends' on `bar1' to help ensure that others do not have the same problem building your package.) ------------------------------------------------------------------------------- 10. The Operating System ------------------------ 10.1. Filesystem hierarchy -------------------------- 10.1.1. Filesystem Structure ---------------------------- The location of all installed files and directories must comply with the Filesystem Hierarchy Standard (FHS), version 2.1, except where doing so would violate other terms of Debian Policy. The version of this document referred here can be found in the `debian-policy' package or on FHS (Debian copy) (http://www.debian.org/doc/packaging-manuals/fhs) alongside this manual. The latest version, which may be a more recent version, may be found on FHS (upstream) (http://www.pathname.com/fhs/). Specific questions about following the standard may be asked on the `debian-devel' mailing list, or referred to the FHS mailing list (see the FHS web site (http://www.pathname.com/fhs/) for more information). 10.1.2. Site-specific programs ------------------------------ As mandated by the FHS, packages must not place any files in `/usr/local', either by putting them in the file system archive to be unpacked by `dpkg' or by manipulating them in their maintainer scripts. However, the package may create empty directories below `/usr/local' so that the system administrator knows where to place site-specific files. These directories should be removed on package removal if they are empty. Note, that this applies only to directories _below_ `/usr/local', not _in_ `/usr/local'. Packages must not create sub-directories in the directory `/usr/local' itself, except those listed in FHS, section 4.5. However, you may create directories below them as you wish. You must not remove any of the directories listed in 4.5, even if you created them. Since `/usr/local' can be mounted read-only from a remote server, these directories must be created and removed by the `postinst' and `prerm' maintainer scripts and not be included in the `.deb' archive. These scripts must not fail if either of these operations fail. For example, the `emacsen-common' package could contain something like if [ ! -e /usr/local/share/emacs ] then if mkdir /usr/local/share/emacs 2>/dev/null then chown root:staff /usr/local/share/emacs chmod 2775 /usr/local/share/emacs fi fi in its `postinst' script, and rmdir /usr/local/share/emacs/site-lisp 2>/dev/null || true rmdir /usr/local/share/emacs 2>/dev/null || true in the `prerm' script. (Note that this form is used to ensure that if the script is interrupted, the directory `/usr/local/share/emacs' will still be removed.) If you do create a directory in `/usr/local' for local additions to a package, you should ensure that settings in `/usr/local' take precedence over the equivalents in `/usr'. However, because `/usr/local' and its contents are for exclusive use of the local administrator, a package must not rely on the presence or absence of files or directories in `/usr/local' for normal operation. The `/usr/local' directory itself and all the subdirectories created by the package should (by default) have permissions 2775 (group-writable and set-group-id) and be owned by `root.staff'. 10.1.3. The system-wide mail directory -------------------------------------- The system-wide mail directory is `/var/mail'. This directory is part of the base system and should not owned by any particular mail agents. The use of the old location `/var/spool/mail' is deprecated, even though the spool may still be physically located there. To maintain partial upgrade compatibility for systems which have `/var/spool/mail' as their physical mail spool, packages using `/var/mail' must depend on either `libc6' (>= 2.1.3-13), or on `base-files' (>= 2.2.0), or on later versions of either one of these packages. 10.2. Users and groups ---------------------- 10.2.1. Introduction -------------------- The Debian system can be configured to use either plain or shadow passwords. Some user ids (UIDs) and group ids (GIDs) are reserved globally for use by certain packages. Because some packages need to include files which are owned by these users or groups, or need the ids compiled into binaries, these ids must be used on any Debian system only for the purpose for which they are allocated. This is a serious restriction, and we should avoid getting in the way of local administration policies. In particular, many sites allocate users and/or local system groups starting at 100. Apart from this we should have dynamically allocated ids, which should by default be arranged in some sensible order, but the behavior should be configurable. Packages other than `base-passwd' must not modify `/etc/passwd', `/etc/shadow', `/etc/group' or `/etc/gshadow'. 10.2.2. UID and GID classes --------------------------- The UID and GID numbers are divided into classes as follows: 0-99: Globally allocated by the Debian project, the same on every Debian system. These ids will appear in the `passwd' and `group' files of all Debian systems, new ids in this range being added automatically as the `base-passwd' package is updated. Packages which need a single statically allocated uid or gid should use one of these; their maintainers should ask the `base-passwd' maintainer for ids. 100-999: Dynamically allocated system users and groups. Packages which need a user or group, but can have this user or group allocated dynamically and differently on each system, should use `adduser --system' to create the group and/or user. `adduser' will check for the existence of the user or group, and if necessary choose an unused id based on the ranges specified in `adduser.conf'. 1000-29999: Dynamically allocated user accounts. By default `adduser' will choose UIDs and GIDs for user accounts in this range, though `adduser.conf' may be used to modify this behavior. 30000-59999: Reserved. 60000-64999: Globally allocated by the Debian project, but only created on demand. The ids are allocated centrally and statically, but the actual accounts are only created on users' systems on demand. These ids are for packages which are obscure or which require many statically-allocated ids. These packages should check for and create the accounts in `/etc/passwd' or `/etc/group' (using `adduser' if it has this facility) if necessary. Packages which are likely to require further allocations should have a `hole' left after them in the allocation, to give them room to grow. 65000-65533: Reserved. 65534: User `nobody'. The corresponding gid refers to the group `nogroup'. 65535: `(uid_t)(-1) == (gid_t)(-1)' _must not_ be used, because it is the error return sentinel value. 10.3. System run levels and `init.d' scripts -------------------------------------------- 10.3.1. Introduction -------------------- The `/etc/init.d' directory contains the scripts executed by `init' at boot time and when the init state (or `runlevel') is changed (see init(8)). There are at least two different, yet functionally equivalent, ways of handling these scripts. For the sake of simplicity, this document describes only the symbolic link method. However, it must not be assumed by maintainer scripts that this method is being used, and any automated manipulation of the various runlevel behaviours by maintainer scripts must be performed using `update-rc.d' as described below and not by manually installing or removing symlinks. For information on the implementation details of the other method, implemented in the `file-rc' package, please refer to the documentation of that package. These scripts are referenced by symbolic links in the `/etc/rc.d' directories. When changing runlevels, `init' looks in the directory `/etc/rc.d' for the scripts it should execute, where `' is the runlevel that is being changed to, or `S' for the boot-up scripts. The names of the links all have the form `S