Ubuntu Policy Manual -------------------- The Debian Policy Mailing List The Ubuntu Developers Mailing List version 3.8.2.0ubuntu1, 2009-06-19 ------------------------------------------------------------------------------- Abstract -------- This manual describes the policy requirements for the Ubuntu distribution. This includes the structure and contents of the Ubuntu 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. It is derived from the Debian Policy Manual. Copyright Notice ---------------- Copyright (C) 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., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA. ------------------------------------------------------------------------------- Contents -------- 1. About this manual 1.1. Scope 1.2. New versions of this document 1.3. Authors and Maintainers 1.4. Related documents 1.5. Definitions 2. The Ubuntu Archive 2.1. The Ubuntu Licensing Policy 2.2. Archive areas 2.2.1. The main archive area 2.2.2. The restricted archive area 2.2.3. The universe archive area 2.2.4. The multiverse archive area 2.3. Copyright considerations 2.4. Sections 2.5. Priorities 3. Binary packages 3.1. The package name 3.2. The version of a package 3.2.1. Version numbers based on dates 3.3. The maintainer of a package 3.4. The description of a package 3.4.1. The single line synopsis 3.4.2. The extended description 3.5. Dependencies 3.6. Virtual packages 3.7. Base system 3.8. Essential packages 3.9. Maintainer Scripts 3.9.1. Prompting in maintainer scripts 4. Source packages 4.1. Standards conformance 4.2. Package relationships 4.3. Changes to the upstream sources 4.4. Ubuntu changelog: `debian/changelog' 4.5. Copyright: `debian/copyright' 4.6. Error trapping in makefiles 4.7. Time Stamps 4.8. Restrictions on objects in source packages 4.9. Main building script: `debian/rules' 4.9.1. `debian/rules' and `DEB_BUILD_OPTIONS' 4.10. Variable substitutions: `debian/substvars' 4.11. Optional upstream source location: `debian/watch' 4.12. Generated files list: `debian/files' 4.13. Convenience copies of code 4.14. Source package handling: `debian/README.source' 5. Control files and their fields 5.1. Syntax of control files 5.2. Source package control files -- `debian/control' 5.3. Binary package control files -- `DEBIAN/control' 5.4. Debian source control files -- `.dsc' 5.5. Debian changes files -- `.changes' 5.6. List of fields 5.6.1. `Source' 5.6.2. `Maintainer' 5.6.3. `Uploaders' 5.6.4. `Changed-By' 5.6.5. `Section' 5.6.6. `Priority' 5.6.7. `Package' 5.6.8. `Architecture' 5.6.9. `Essential' 5.6.10. Package interrelationship fields: `Depends', `Pre-Depends', `Recommends', `Suggests', `Breaks', `Conflicts', `Provides', `Replaces', `Enhances' 5.6.11. `Standards-Version' 5.6.12. `Version' 5.6.13. `Description' 5.6.14. `Distribution' 5.6.15. `Date' 5.6.16. `Format' 5.6.17. `Urgency' 5.6.18. `Changes' 5.6.19. `Binary' 5.6.20. `Installed-Size' 5.6.21. `Files' 5.6.22. `Closes' 5.6.23. `Launchpad-Bugs-Fixed' 5.6.24. `Homepage' 5.7. User-defined fields 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. Exit status 6.5. Summary of ways maintainer scripts are called 6.6. Details of unpack phase of installation or upgrade 6.7. Details of configuration 6.8. 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. Packages which break other packages - `Breaks' 7.4. Conflicting binary packages - `Conflicts' 7.5. Virtual packages - `Provides' 7.6. Overwriting files and replacing packages - `Replaces' 7.6.1. Overwriting files in other packages 7.6.2. Replacing whole packages, forcing their removal 7.7. Relationships between source and binary packages - `Build-Depends', `Build-Depends-Indep', `Build-Conflicts', `Build-Conflicts-Indep' 8. Shared libraries 8.1. Run-time shared libraries 8.1.1. `ldconfig' 8.2. Shared library support files 8.3. Static libraries 8.4. Development files 8.5. Dependencies between the packages of the same library 8.6. Dependencies between the library and other packages - the `shlibs' system 8.6.1. The `shlibs' files present on the system 8.6.2. How to use `dpkg-shlibdeps' and the `shlibs' files 8.6.3. The `shlibs' File Format 8.6.4. Providing a `shlibs' file 8.6.5. Writing the `debian/shlibs.local' file 9. The Operating System 9.1. File system hierarchy 9.1.1. File System Structure 9.1.2. Site-specific programs 9.1.3. The system-wide mail directory 9.2. Users and groups 9.2.1. Introduction 9.2.2. UID and GID classes 9.3. System run levels and `init.d' scripts 9.3.1. Introduction 9.3.2. Writing the scripts 9.3.3. Interfacing with the initscript system 9.3.4. Boot-time initialization 9.3.5. Example 9.4. Console messages from `init.d' scripts 9.5. Cron jobs 9.6. Menus 9.7. Multimedia handlers 9.8. Keyboard configuration 9.9. Environment variables 9.10. Registering Documents using doc-base 10. Files 10.1. Binaries 10.2. Libraries 10.3. Shared libraries 10.4. Scripts 10.5. Symbolic links 10.6. Device files 10.7. Configuration files 10.7.1. Definitions 10.7.2. Location 10.7.3. Behavior 10.7.4. Sharing configuration files 10.7.5. User configuration files ("dotfiles") 10.8. Log files 10.9. Permissions and owners 10.9.1. The use of `dpkg-statoverride' 11. Customized programs 11.1. Architecture specification strings 11.2. Daemons 11.3. Using pseudo-ttys and modifying wtmp, utmp and lastlog 11.4. Editors and pagers 11.5. Web servers and applications 11.6. Mail transport, delivery and user agents 11.7. News system configuration 11.8. Programs for the X Window System 11.8.1. Providing X support and package priorities 11.8.2. Packages providing an X server 11.8.3. Packages providing a terminal emulator 11.8.4. Packages providing a window manager 11.8.5. Packages providing fonts 11.8.6. Application defaults files 11.8.7. Installation directory issues 11.8.8. The OSF/Motif and OpenMotif libraries 11.8.9. Icon caching 11.9. Perl programs and modules 11.10. Emacs lisp programs 11.11. Games 12. Documentation 12.1. Manual pages 12.2. Info documents 12.3. Additional documentation 12.4. Preferred documentation formats 12.5. Copyright information 12.6. Examples 12.7. 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.1.1. `dpkg-source' - packs and unpacks Debian source packages C.1.2. `dpkg-buildpackage' - overall package-building control script C.1.3. `dpkg-gencontrol' - generates binary package control files C.1.4. `dpkg-shlibdeps' - calculates shared library dependencies C.1.5. `dpkg-distaddfile' - adds a file to `debian/files' C.1.6. `dpkg-genchanges' - generates a `.changes' upload control file C.1.7. `dpkg-parsechangelog' - produces parsed representation of a changelog C.1.8. `dpkg-architecture' - information about the build and host system C.2. The Debianised source tree C.2.1. `debian/rules' - the main building script C.2.2. `debian/changelog' C.2.3. `debian/substvars' and variable substitutions C.2.4. `debian/files' C.2.5. `debian/tmp' C.3. Source packages as archives C.4. Unpacking a Debian source package without `dpkg-source' C.4.1. Restrictions on objects in source packages D. Control files and their fields (from old Packaging Manual) D.1. Syntax of control files D.2. List of fields D.2.1. `Filename' and `MSDOS-Filename' D.2.2. `Size' and `MD5sum' D.2.3. `Status' D.2.4. `Config-Version' D.2.5. `Conffiles' D.2.6. Obsolete 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 Ubuntu distribution. This includes the structure and contents of the Ubuntu 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 Ubuntu policy as it relates to creating Ubuntu 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 Ubuntu policy itself. The appendices to this manual are not necessarily normative, either. Please see Appendix A, `Introduction and scope of these appendices' for more information. In the normative part of 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 Ubuntu 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. The Ubuntu distribution differs from its parent Debian distribution in a number of significant ways. In this document, these are marked with the tag _Ubuntu:_. [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 ---------------------------------- This manual is distributed via the Ubuntu package `ubuntu-policy (http://packages.ubuntu.com/ubuntu-policy)' (packages.ubuntu.com /ubuntu-policy). The `ubuntu-policy' package also includes the file `upgrading-checklist.txt.gz' which indicates policy changes between versions of this document. 1.3. Authors and Maintainers ---------------------------- Originally called "Debian GNU/Linux Policy Manual", this manual was initially written in 1996 by Ian Jackson. It was revised on November 27th, 1996 by David A. Morris. Christian Schwarz added new sections on March 15th, 1997, and reworked/restructured it in April-July 1997. Christoph Lameter contributed the "Web Standard". Julian Gilbey largely restructured it in 2001. Since September 1998, the responsibility for the contents of the Debian version of this document lies on the debian-policy mailing list (mailto:debian-policy@lists.debian.org). Proposals are discussed there and inserted into policy after a certain consensus is established. The actual editing is done by a group of maintainers that have no editorial powers. These are the current maintainers: 1. Julian Gilbey 2. Branden Robinson 3. Josip Rodin 4. Manoj Srivastava The Ubuntu branch of this manual is maintained by the ubuntu-devel mailing list (mailto:ubuntu-devel@lists.ubuntu.com). 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. Please do not try to reach the individual authors or maintainers of the Policy Manual regarding changes to the Policy. 1.4. Related documents ---------------------- There are several other documents other than this Policy Manual that are necessary to fully understand some Debian policies and procedures. The external "sub-policy" documents are referred to in: * Section 9.1.1, `File System Structure' * Section 3.6, `Virtual packages' * Section 9.6, `Menus' * Section 9.7, `Multimedia handlers' * Section 11.9, `Perl programs and modules' * Section 3.9.1, `Prompting in maintainer scripts' * Section 11.10, `Emacs lisp programs' In addition to those, which carry the weight of policy, there is the Debian Developer's Reference. This document describes procedures and resources for Debian developers, but it is _not_ normative; rather, it includes things that don't belong in the Policy, such as best practices for developers. The Developer's Reference is available in the `developers-reference' package. It's also available from the Debian web mirrors at `/doc/developers-reference/ (http://www.debian.org/doc/developers-reference/)'. 1.5. Definitions ---------------- The following terms are used in this Policy Manual: ASCII The character encoding specified by ANSI X3.4-1986 and its predecessor standards, referred to in MIME as US-ASCII, and corresponding to an encoding in eight bits per character of the first 128 Unicode (http://www.unicode.org/) characters, with the eighth bit always zero. UTF-8 The transformation format (sometimes called encoding) of Unicode (http://www.unicode.org/) defined by RFC 3629 (http://www.rfc-editor.org/rfc/rfc3629.txt). UTF-8 has the useful property of having ASCII as a subset, so any text encoded in ASCII is trivially also valid UTF-8. ------------------------------------------------------------------------------- 2. The Ubuntu Archive --------------------- The Ubuntu system is maintained and distributed as a collection of _packages_. Since there are so many of them (currently well over 15000), they are split into _sections_ and given _priorities_ to simplify the handling of them. The effort of the Ubuntu project is to build a free operating system, but not every package we want to make accessible is _free_ in our sense (see the Ubuntu Licensing Policy, below), or may be imported/exported without restrictions. Thus, the archive is split into areas[1] based on their licenses and other restrictions. We also divide up packages based on whether they are supported or not. The aims of this 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. [1] The Ubuntu archive software uses the term "component" internally and in the Release file format to refer to the division of an archive. The Debian Social Contract simply refers to "areas." This document uses terminology similar to the Social Contract. 2.1. The Ubuntu Licensing Policy -------------------------------- The Ubuntu Licensing Policy forms our definition of "free software". The following guidelines apply to the _main_ and _universe_ categories of the archive: Must include source code. The _main_ and _universe_ categories have a strict and non-negotiable requirement that application software included in them must come with full source code. Must allow modification and distribution of modified copies under the same license. Just having the source code does not convey the same freedom as having the right to change it. Without the ability to modify software, the Ubuntu community cannot support software, fix bugs, translate it, or improve it. The following additional guidelines apply to the _main_, _restricted_ and _universe_ categories of the archive: Must allow these rights to be passed on along with the software. You should be able to have exactly the same rights to the software as we do. Must not discriminate against persons, groups or against fields of endeavour. The license of software included in Ubuntu can not discriminate against anyone or any group of users and cannot restrict users from using the software for a particular field of endeavour - a business for example. Thus we will not distribute software that is licensed "freely for non-commercial use". Must not be distributed under a license specific to Ubuntu. The rights attached to the software must not depend on the programme's being part of Ubuntu system. So we will not distribute software for which Ubuntu has a "special" exemption or right, and we will not put our own software into Ubuntu and then refuse you the right to pass it on. The following additional guidelines apply to the entire archive: Must allow redistribution. Your right to sell or give away the software alone, or as part of an aggregate software distribution, is important because: * You, the user, must be able to pass on any software you have received from Ubuntu in either source code or compiled form. * While Ubuntu will not charge license fees for this distribution, you might well want to charge to print Ubuntu CD's, or create your own customized versions of Ubuntu which you sell, and should have the freedom to do so. Must not require royalty payments or any other fee for redistribution or modification. It's important that you can exercise your rights to this software without having to pay for the privilege, and that you can pass these rights on to other people on exactly the same basis. Must not contaminate other software licenses. The license must not place restrictions on other software that is distributed along with it. For example, the license must not insist that all other programmes distributed on the same medium be free software. May require source modifications to be distributed as patches. In some cases, software authors are happy for us to distribute their software and modifications to their software, as long as the two are distributed separately, so that people always have a copy of their pristine code. We are happy to respect this preference. However, the license must explicitly permit distribution of software built from modified source code. The "GPL," "BSD," and "Artistic" licenses are examples of licenses that we consider _free_. Ubuntu contains licensed and copyrighted works that are not application software. For example, the default Ubuntu installation includes documentation, images, sounds, video clips and firmware. The Ubuntu community will make decisions on the inclusion of these works on a case-by-case basis, ensuring that these works do not restrict our ability to make Ubuntu available free of charge, and that Ubuntu remains re-distributable by you. 2.2. Archive areas ------------------ 2.2.1. The main archive area ---------------------------- Every package in _main_ must comply with the Ubuntu Licensing Policy. 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. 2.2.2. The restricted archive area ---------------------------------- Every package in _restricted_ must comply with the Ubuntu Licensing Policy, with the exceptions that source code may not be available and that modification may not be permitted. In addition, the packages in _restricted_ * 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] The Ubuntu team recognises that many users have vital hardware in their computer that requires drivers that are currently only available in binary format. We urge all hardware vendors to insist that their suppliers provide open source drivers for their components, but we recognise that in some cases binary drivers are the only way to make your hardware work. As a result, Ubuntu includes several of these drivers on the CD and in the repository, clearly separated from the rest of the software by being placed in the _restricted_ archive area. Binary drivers are a poor choice, if you have a choice. Without source code, Ubuntu cannot support this software, we only provide it for users who require it to be able to run the Free Software we provide in main. Also, we cannot make binary drivers available on other architectures (such as the Mac or IPAQ) if we don't have the ability to port the software source code ourselves. If your hardware is fully supported with open source drivers you can simply remove the _restricted_ archive area, and we would encourage you to do so. The _restricted_ archive area may not include application software, only hardware drivers. [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.2.3. The universe archive area -------------------------------- Every package in _universe_ must comply with the Ubuntu Licensing Policy. Packages in the _universe_ archive area are not supported by the core Ubuntu developers and Canonical Ltd. Packages may be moved between _main_ and _universe_ as their support status changes. In addition, the packages in _universe_ * must not require a package outside of _main_ and _universe_ for compilation or execution (thus, the package must not declare a "Depends", "Recommends", or "Build-Depends" relationship on a non-_main_ and non-_universe_ package), and * must meet all policy requirements presented in this manual. 2.2.4. The multiverse archive area ---------------------------------- Every package in _multiverse_ must comply with the Ubuntu Licensing Policy, with the exceptions that source code may not be available, that modification may not be permitted, that rights may not be passed on along with the software, that they may discriminate against persons, groups or fields of endeavour, and that their license may be specific to Ubuntu. (In other words, they must be redistributable without a fee and must not contaminate other software licenses.) Packages must be placed in _multiverse_ if they are not compliant with the parts of the Ubuntu Licensing Policy that cover other categories of the archive, or if they are encumbered by patents or other legal issues that make their distribution problematic. Packages in the _multiverse_ archive area are not supported by the core Ubuntu developers and Canonical Ltd. In addition, the packages in _multiverse_ * 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.3. 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 12.5, `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 _multiverse_. 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 Ubuntu 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 `ubuntu-archive' 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.4. Sections ------------- The packages in the archive areas _main_, _restricted_, _universe_ and _multiverse_ are grouped further into _sections_ to simplify handling. The archive area and section for each package should be specified in the package's `Section' control record (see Section 5.6.5, ``Section''). However, the maintainer of the Ubuntu archive may override this selection to ensure the consistency of the Ubuntu distribution. The `Section' field should be of the form: * _section_ if the package is in the _main_ archive area, * _area/section_ if the package is in the _restricted_, _universe_ or _multiverse_ archive areas.[1] The Ubuntu archive maintainers provide the authoritative list of sections. At present, they are: _admin_, _cli-mono_, _comm_, _database_, _devel_, _debug_, _doc_, _editors_, _electronics_, _embedded_, _fonts_, _games_, _gnome_, _graphics_, _gnu-r_, _gnustep_, _hamradio_, _haskell_, _httpd_, _interpreters_, _java_, _kde_, _kernel_, _libs_, _libdevel_, _lisp_, _localization_, _mail_, _math_, _metapackages_, _misc_, _net_, _news_, _ocaml_, _oldlibs_, _otherosfs_, _perl_, _php_, _python_, _ruby_, _science_, _shells_, _sound_, _tex_, _text_, _utils_, _vcs_, _video_, _web_, _x11_, _xfce_, _zope_. Ubuntu: The _metapackages_ section exists for the benefit of package management tools. When removing a package in that section, its dependencies will not be automatically considered for removal by tools which track the distinction between packages that were installed explicitly and packages that were only installed to satisfy dependencies. [1] Packages that originally came from the Debian archive will often not have `Section' fields matching the archive area selected for them in Ubuntu. There is no need to change the package just for this; the maintainers of the Ubuntu archive can and will override its placement. 2.5. Priorities --------------- Each package should have a _priority_ value, which is included in the package's _control record_ (see Section 5.6.6, ``Priority''). This information is used by the Ubuntu package management tools to separate high-priority packages from less-important packages. The following _priority levels_ are recognized by the Ubuntu package management tools. `required' Packages which are necessary for the proper functioning of the system (usually, this means that dpkg functionality depends on these packages). Removing a `required' package may cause your system to become totally broken and you may not even be able to use `dpkg' to put things back, so only do so if you know what you are doing. 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 specialized requirements (such as packages containing only detached debugging symbols). 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. ------------------------------------------------------------------------------- 3. Binary packages ------------------ The Ubuntu distribution is based on the Debian package management system, called `dpkg'. Thus, all packages in the Ubuntu distribution must be provided in the `.deb' file format. 3.1. The package name --------------------- Every package must have a name that's unique within the Ubuntu archive. The package name is included in the control field `Package', the format of which is described in Section 5.6.7, ``Package''. The package name is also included as a part of the file name of the `.deb' file. 3.2. The version of a package ----------------------------- Every package has a version number recorded in its `Version' control file field, described in Section 5.6.12, ``Version''. 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. If an upstream package has problematic version numbers they should be converted to a sane form for use in the `Version' field. 3.2.1. Version numbers based on dates ------------------------------------- In general, Ubuntu 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 date based portion of the version number should be changed to the following format in such cases: "19960501", "19961224". It is up to the maintainer whether they want 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 or Ubuntu packages (i.e., packages which have been written especially for Debian or Ubuntu) whose version numbers include dates should always use the "YYYYMMDD" format. 3.3. 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, they should try to avoid having different forms of their name and email address in the `Maintainer' fields of those packages. The format of the `Maintainer' control field is described in Section 5.6.2, ``Maintainer''. If the maintainer of a package quits from the Debian project, "Debian QA Group" takes over the maintainer-ship of the package until someone else volunteers for that task. These packages are called _orphaned packages_.[1] Ubuntu: Packages that are modified in Ubuntu should have an Ubuntu-specific `Maintainer' field.[2] All Ubuntu binary packages, and Ubuntu source packages that are modified relative to Debian (that is, its version number contains the string "ubuntu"), should have their `Maintainer' field adjusted as follows: * If the `Maintainer' field contains an `ubuntu.com' email address, or one associated with an Ubuntu developer, then no modifications should be made. * If the package is in `main' or `restricted', the `Maintainer' field should be set to Ubuntu Core Developers . * If the package is in `universe' or `multiverse', the `Maintainer' field should be set to Ubuntu MOTU Developers . If the `Maintainer' field is modified, then the old value must be saved in a field named `XSBC-Original-Maintainer'. Because it is mandated and very common, it is not necessary or appropriate to document this change in `debian/changelog', unless it is the only change involved in the upload. [1] The detailed procedure for doing this gracefully can be found in the Debian Developer's Reference, see Section 1.4, `Related documents'. [2] This is in response to a poll of Debian maintainers, documented in the DebianMaintainerField specification (http://wiki.ubuntu.com/DebianMaintainerField). 3.4. The description of a package --------------------------------- Every Ubuntu package must have an extended description stored in the appropriate field of the control record. The technical information about the format of the `Description' field is in Section 5.6.13, ``Description''. The description should describe the package (the program) to a user (system administrator) who has never met it before so that they have enough information to decide whether they want to install it. This description should not just be copied verbatim from the program's documentation. 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. The description 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. 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). 3.4.1. The single line synopsis ------------------------------- 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. 3.4.2. The extended description ------------------------------- 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] [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. 3.5. 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.[1] 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 `ubuntu-devel' mailing list and a consensus about doing that has been reached. The format of the package interrelationship control fields is described in Chapter 7, `Declaring relationships between packages'. [1] Essential is needed in part to avoid unresolvable dependency loops on upgrade. If packages add unnecessary dependencies on packages in this set, the chances that there _will_ be an unresolvable dependency loop caused by forcing these Essential packages to be configured first before they need to be is greatly increased. It also increases the chances that frontends will be unable to _calculate_ an upgrade path, even if one exists. Also, functionality is rarely ever removed from the Essential set, but _packages_ have been removed from the Essential set when the functionality moved to a different package. So depending on these packages _just in case_ they stop being essential does way more harm than good. 3.6. 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. (See also Section 7.5, `Virtual packages - `Provides'') The latest version of the authoritative list of virtual package names can be found in the `debian-policy' package. It is also available from the Debian web mirrors at `/doc/packaging-manuals/virtual-package-names-list.txt (http://www.debian.org/doc/packaging-manuals/virtual-package-names-list.txt)'. The procedure for updating the list is described in the preface to the list. 3.7. Base system ---------------- The `base system' is a minimum subset of the Ubuntu system that is installed before everything else on a new system. Only very few packages are allowed to form part of the base system, in order to keep the required disk usage very small. The base system consists of all those packages with priority `required' or `important'. Many of them will be tagged `essential' (see below). 3.8. Essential packages ----------------------- Essential is defined as the minimal set of functionality that must be available and usable on the system at all times, even when packages are in an unconfigured (but unpacked) state. Packages are tagged `essential' for a system using the `Essential' control file field. The format of the `Essential' control field is described in Section 5.6.9, ``Essential''. 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. Maintainers should take great care in adding any programs, interfaces, or functionality to `essential' packages. Packages may assume that functionality provided by `essential' packages is always available without declaring explicit dependencies, which means that removing functionality from the Essential set is very difficult and is almost never done. Any capability added to an `essential' package therefore creates an obligation to support that capability as part of the Essential set in perpetuity. You must not tag any packages `essential' before this has been discussed on the `ubuntu-devel' mailing list and a consensus about doing that has been reached. 3.9. Maintainer Scripts ----------------------- The package installation scripts should avoid producing output which 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 10.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.) 3.9.1. Prompting in maintainer scripts -------------------------------------- Package maintainer scripts may prompt the user if necessary. Prompting must be done by communicating through a program, such as `debconf', which conforms to the Debian Configuration Management Specification, version 2 or higher. Packages which are essential, or which are dependencies of essential packages, may fall back on another prompting method if no such interface is available when they are executed. The Debian Configuration Management Specification is included in the `debconf_specification' files in the `debian-policy' package. It is also available from the Debian web mirrors at `/doc/packaging-manuals/debconf_specification.html (http://www.debian.org/doc/packaging-manuals/debconf_specification.html)'. Packages which use the Debian Configuration Management Specification may contain an additional `config' script and a `templates' file in their control archive[1]. The `config' script might be run before the `preinst' script, and before the package is unpacked or any of its dependencies or pre-dependencies are satisfied. Therefore it must work using only the tools present in _essential_ packages.[2] Packages which use the Debian Configuration Management Specification must allow for translation of their user-visible messages by using a gettext-based system such as the one provided by the `po-debconf' package. 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] The control.tar.gz inside the .deb. See deb(5). [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. ------------------------------------------------------------------------------- 4. Source packages ------------------ 4.1. Standards conformance -------------------------- Source packages should specify the most recent version number of this policy document with which your package complied when it was last updated. This information may be used to file bug reports automatically if your package becomes too much out of date. The version is specified in the `Standards-Version' control field. The format of the `Standards-Version' field is described in Section 5.6.11, ``Standards-Version''. 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.[1] [1] See the file `upgrading-checklist' for information about policy which has changed between different versions of this document. 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 an Ubuntu 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. Chapter 7, `Declaring relationships between packages' explains the technical details. [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 tasks 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. 4.3. Changes to the upstream sources ------------------------------------ If changes to the source code are made that are not specific to the needs of the Ubuntu 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 Ubuntu 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 11.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 without losing the changes you made. 4.4. Ubuntu changelog: `debian/changelog' ----------------------------------------- Changes in the Ubuntu version of the package should be briefly explained in the Ubuntu changelog file `debian/changelog'.[1] This includes modifications made in the Ubuntu package compared to the upstream one or the Debian package as well as other changes and updates to the package. [2] The format of the `debian/changelog' 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= <[optional blank line(s), stripped]> * <[blank line(s), included in output of dpkg-parsechangelog]> * <[optional blank line(s), stripped]> -- <><[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 5.6.14, ``Distribution''. is the value for the `Urgency' field in the `.changes' file for the upload (see Section 5.6.17, ``Urgency''). 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'). 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 Debian 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] This information is conveyed via the `Closes' field in the `.changes' file (see Section 5.6.22, ``Closes''). Ubuntu: If this upload resolves bugs recorded in Launchpad, they may be automatically closed on the inclusion of this package into the Ubuntu archive by including the string: `LP: #' in the change details.[4] This information is conveyed via the `Launchpad-Bugs-Fixed' field in the `.changes' file (see Section 5.6.23, ``Launchpad-Bugs-Fixed''). 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 (see Section 5.6.4, ``Changed-By''), and then later used to send an acknowledgement when the upload has been installed. The must be in RFC822 format[5]; it must 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 must start at the left hand margin. The "trailer" line with the maintainer and date details must be preceded by exactly one space. The maintainer details and the date must be separated by exactly two spaces. The entire changelog must be encoded in UTF-8. For more information on placement of the changelog files within binary packages, please see Section 12.7, `Changelog files'. [1] Mistakes in changelogs are usually best rectified by making a new changelog entry rather than "rewriting history" by editing old changelog entries. [2] Although there is nothing stopping an author who is also the Ubuntu maintainer from using this changelog for all their changes, it will have to be renamed if the Ubuntu and upstream maintainers become different people. In such a case, however, it might be better to maintain the package as a non-native package. [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') using the of the changelog entry. [4] To be precise, the string should match the following Perl regular expression: /lp:\s+\#\d+(?:,\s*\#\d+)*/i Then all of the bug numbers listed will be closed by the archive maintenance software using the of the changelog entry. [5] This is generated by `date -R'. 4.5. Copyright: `debian/copyright' ---------------------------------- Every package must be accompanied by a verbatim copy of its copyright and distribution license in the file `/usr/share/doc//copyright' (see Section 12.5, `Copyright information' for further details). Also see Section 2.3, `Copyright considerations' for further considerations relayed to copyrights for packages. 4.6. 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. 4.7. 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. 4.8. 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. 4.9. Main building script: `debian/rules' ----------------------------------------- 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 targets are as follows (required unless stated otherwise): `build' The `build' target should perform all the 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] `build-arch' (optional), `build-indep' (optional) A package may also provide both of the targets `build-arch' and `build-indep'. The `build-arch' target, if provided, should perform all the configuration and compilation required for producing all architecture-dependant binary packages (those packages for which the body of the `Architecture' field in `debian/control' is not `all'). Similarly, the `build-indep' target, if provided, should perform all the configuration and compilation required for producing all architecture-independent binary packages (those packages for which the body of the `Architecture' field in `debian/control' is `all'). The `build' target should depend on those of the targets `build-arch' and `build-indep' that are provided in the rules file. If one or both of the targets `build-arch' and `build-indep' are not provided, then invoking `debian/rules' with one of the not-provided targets as arguments should produce a exit status code of 2. Usually this is provided automatically by make if the target is missing. The `build-arch' and `build-indep' targets must not do anything that might require root privilege. `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. 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. 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. `patch' (optional) This target performs whatever additional actions are required to make the source ready for editing (unpacking additional upstream archives, applying patches, etc.). It is recommended to be implemented for any package where `dpkg-source -x' does not result in source ready for additional modification. See Section 4.14, `Source package handling: `debian/README.source''. 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. 4.9.1. `debian/rules' and `DEB_BUILD_OPTIONS' --------------------------------------------- Supporting the standardized environment variable `DEB_BUILD_OPTIONS' is recommended. This variable can contain several flags to change how a package is compiled and built. Each flag must be in the form or =. If multiple flags are given, they must be separated by whitespace.[1] must start with a lowercase letter (`a-z') and consist only of lowercase letters, numbers (`0-9'), and the characters `-' and `_' (hyphen and underscore). must not contain whitespace. The same tag should not be given multiple times with conflicting values. Package maintainers may assume that `DEB_BUILD_OPTIONS' will not contain conflicting tags. The meaning of the following tags has been standardized: nocheck This tag says to not run any build-time test suite provided by the package. noopt The presence of this tag means that the package should be compiled with a minimum of optimization. For C programs, it is best to add `-O0' to `CFLAGS' (although this is usually the default). Some programs might fail to build or run at this level of optimization; it may be necessary to use `-O1', for example. nostrip This tag means that the debugging symbols should not be stripped from the binary during installation, so that debugging information may be included in the package. parallel=n This tag means that the package should be built using up to `n' parallel processes if the package build system supports this.[2] If the package build system does not support parallel builds, this string must be ignored. If the package build system only supports a lower level of concurrency than , the package should be built using as many parallel processes as the package build system supports. It is up to the package maintainer to decide whether the package build times are long enough and the package build system is robust enough to make supporting parallel builds worthwhile. Unknown flags must be ignored by `debian/rules'. The following makefile snippet is an example of how one may implement the build options; you will probably have to massage this example in order to make it work for your package. CFLAGS = -Wall -g INSTALL = install INSTALL_FILE = $(INSTALL) -p -o root -g root -m 644 INSTALL_PROGRAM = $(INSTALL) -p -o root -g root -m 755 INSTALL_SCRIPT = $(INSTALL) -p -o root -g root -m 755 INSTALL_DIR = $(INSTALL) -p -d -o root -g root -m 755 ifneq (,$(filter noopt,$(DEB_BUILD_OPTIONS))) CFLAGS += -O0 else CFLAGS += -O2 endif ifeq (,$(filter nostrip,$(DEB_BUILD_OPTIONS))) INSTALL_PROGRAM += -s endif ifneq (,$(filter parallel=%,$(DEB_BUILD_OPTIONS))) NUMJOBS = $(patsubst parallel=%,%,$(filter parallel=%,$(DEB_BUILD_OPTIONS))) MAKEFLAGS += -j$(NUMJOBS) endif build: # ... ifeq (,$(filter nocheck,$(DEB_BUILD_OPTIONS))) # Code to run the package test suite. endif [1] Some packages support any delimiter, but whitespace is the easiest to parse inside a makefile and avoids ambiguity with flag values that contain commas. [2] Packages built with `make' can often implement this by passing the `-j' option to `make'. 4.10. Variable substitutions: `debian/substvars' ------------------------------------------------ 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 which case it must be removed by the `clean' target. See deb-substvars(5) for full details about source variable substitutions, including the format of `debian/substvars'. 4.11. Optional upstream source location: `debian/watch' ------------------------------------------------------- This is an optional, recommended control file for the `uscan' utility which defines how to automatically scan ftp or http sites for newly available updates of the package. This is used by http://dehs.alioth.debian.org/ and other Debian QA tools to help with quality control and maintenance of the distribution as a whole. 4.12. Generated files list: `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. 4.13. Convenience copies of code -------------------------------- Some software packages include in their distribution convenience copies of code from other software packages, generally so that users compiling from source don't have to download multiple packages. Ubuntu packages should not make use of these convenience copies unless the included package is explicitly intended to be used in this way.[1] If the included code is already in the Ubuntu archive in the form of a library, the Ubuntu packaging should ensure that binary packages reference the libraries already in Ubuntu and the convenience copy is not used. If the included code is not already in Ubuntu, it should be packaged separately as a prerequisite if possible. [2] [1] For example, parts of the GNU build system work like this. [2] Having multiple copies of the same code in Ubuntu is inefficient, often creates either static linking or shared library conflicts, and, most importantly, increases the difficulty of handling security vulnerabilities in the duplicated code. 4.14. Source package handling: `debian/README.source' ----------------------------------------------------- If running `dpkg-source -x' on a source package doesn't produce the source of the package, ready for editing, and allow one to make changes and run `dpkg-buildpackage' to produce a modified package without taking any additional steps, creating a `debian/README.source' documentation file is recommended. This file should explain how to do all of the following: 1. Generate the fully patched source, in a form ready for editing, that would be built to create Ubuntu packages. Doing this with a `patch' target in `debian/rules' is recommended; see Section 4.9, `Main building script: `debian/rules''. 2. Modify the source and save those modifications so that they will be applied when building the package. 3. Remove source modifications that are currently being applied when building the package. 4. Optionally, document what steps are necessary to upgrade the Ubuntu source package to a new upstream version, if applicable. This explanation should include specific commands and mention any additional required Ubuntu packages. It should not assume familiarity with any specific Ubuntu packaging system or patch management tools. This explanation may refer to a documentation file installed by one of the package's build dependencies provided that the referenced documentation clearly explains these tasks and is not a general reference manual. `debian/README.source' may also include any other information that would be helpful to someone modifying the source package. Even if the package doesn't fit the above description, maintainers are encouraged to document in a `debian/README.source' file any source package with a particularly complex or unintuitive source layout or build system (for example, a package that builds the same source multiple times to generate different binary packages). ------------------------------------------------------------------------------- 5. Control files and their fields --------------------------------- The package management system manipulates data represented in a common format, known as _control data_, stored in _control files_. Control files are used for source packages, binary packages and the `.changes' files which control the installation of uploaded files[1]. [1] `dpkg''s internal databases are in a similar format. 5.1. Syntax of control files ---------------------------- A control file consists of one or more paragraphs of fields[1]. 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 (logical) 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'. Many fields' values may span several lines; in this case each continuation line must start with a space or a tab. Any trailing spaces or tabs at the end of individual lines of a field value are ignored. In fields where it is specified that lines may not wrap, 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. All control files must be encoded in UTF-8. [1] The paragraphs are also sometimes referred to as stanzas. 5.2. Source package control files -- `debian/control' ----------------------------------------------------- The `debian/control' file contains the most vital (and version-independent) information about the source package and about the binary packages it creates. The first paragraph of the control file contains information about the source package in general. The subsequent sets each describe a binary package that the source tree builds. The fields in the general paragraph (the first one, for the source package) are: * `Source' (mandatory) * `Maintainer' (mandatory) * `Uploaders' * `Section' (recommended) * `Priority' (recommended) * `Build-Depends' et al * `Standards-Version' (recommended) * `Homepage' The fields in the binary package paragraphs are: * `Package' (mandatory) * `Architecture' (mandatory) * `Section' (recommended) * `Priority' (recommended) * `Essential' * `Depends' et al * `Description' (mandatory) * `Homepage' The syntax and semantics of the fields are described below. These fields are used by `dpkg-gencontrol' to generate control files for binary packages (see below), by `dpkg-genchanges' to generate the `.changes' file to accompany the upload, and by `dpkg-source' when it creates the `.dsc' source control file as part of a source archive. Many fields are permitted to span multiple lines in `debian/control' but not in any other control file. These tools are responsible for removing the line breaks from such fields when using fields from `debian/control' to generate other control files. The fields here may contain variable references - their values will be substituted by `dpkg-gencontrol', `dpkg-genchanges' or `dpkg-source' when they generate output control files. See Section 4.10, `Variable substitutions: `debian/substvars'' for details. In addition to the control file syntax described above, this file may also contain comment lines starting with `#' without any preceding whitespace. All such lines are ignored, even in the middle of continuation lines for a multiline field, and do not end a multiline field. 5.3. Binary package control files -- `DEBIAN/control' ----------------------------------------------------- The `DEBIAN/control' file contains the most vital (and version-dependent) information about a binary package. The fields in this file are: * `Package' (mandatory) * `Source' * `Version' (mandatory) * `Section' (recommended) * `Priority' (recommended) * `Architecture' (mandatory) * `Essential' * `Depends' et al * `Installed-Size' * `Maintainer' (mandatory) * `Description' (mandatory) * `Homepage' 5.4. Debian source control files -- `.dsc' ------------------------------------------ This file contains a series of fields, identified and separated just like the fields in the control file of a binary package. The fields are listed below; their syntax is described above, in Appendix D, `Control files and their fields (from old Packaging Manual)'. * `Format' (mandatory) * `Source' (mandatory) * `Version' (mandatory) * `Maintainer' (mandatory) * `Uploaders' * `Binary' * `Architecture' * `Build-Depends' et al * `Standards-Version' (recommended) * `Files' (mandatory) * `Homepage' The source package control file is generated by `dpkg-source' when it builds the source archive, from other files in the source package, described above. When unpacking, it is checked against the files and directories in the other parts of the source package. 5.5. Debian changes files -- `.changes' --------------------------------------- The .changes files are used by the Ubuntu archive maintenance software to process updates to packages. They contain one paragraph which contains information from the `debian/control' file and other data about the source package gathered via `debian/changelog' and `debian/rules'. The fields in this file are: * `Format' (mandatory) * `Date' (mandatory) * `Source' (mandatory) * `Binary' (mandatory) * `Architecture' (mandatory) * `Version' (mandatory) * `Distribution' (mandatory) * `Urgency' (recommended) * `Maintainer' (mandatory) * `Changed-By' * `Description' (mandatory) * `Closes' * `Launchpad-Bugs-Fixed' * `Changes' (mandatory) * `Files' (mandatory) 5.6. List of fields ------------------- 5.6.1. `Source' --------------- This field identifies the source package name. In `debian/control' or a `.dsc' file, this field must contain only the name of the source package. In a binary package control file or a `.changes' file, the source package name may be followed by a version number in parentheses[1]. This version number may be omitted (and is, by `dpkg-gencontrol') if it has the same value as the `Version' field of the binary package in question. The field itself may be omitted from a binary package control file when the source package has the same name and version as the binary package. Package names must consist only 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 start with an alphanumeric character. [1] It is customary to leave a space after the package name if a version number is specified. 5.6.2. `Maintainer' ------------------- The package maintainer's name and email address. The name should come first, then the email address inside angle brackets `<>' (in RFC822 format). If the maintainer's name contains a full stop then the whole field will not work directly as an email address due to a misfeature in the syntax specified in RFC822; a program using this field as an address must check for this and correct the problem if necessary (for example by putting the name in round brackets and moving it to the end, and bringing the email address forward). 5.6.3. `Uploaders' ------------------ List of the names and email addresses of co-maintainers of the package, if any. If the package has other maintainers beside the one named in the Maintainer field, their names and email addresses should be listed here. The format is the same as that of the Maintainer tag, and multiple entries should be comma separated. Currently, this field is restricted to a single line of data. This is an optional field. Any parser that interprets the Uploaders field in `debian/control' must permit it to span multiple lines. Line breaks in an Uploaders field that spans multiple lines are not significant and the semantics of the field are the same as if the line breaks had not been present. 5.6.4. `Changed-By' ------------------- The name and email address of the person who changed the said package. Usually the name of the maintainer. All the rules for the Maintainer field apply here, too. 5.6.5. `Section' ---------------- This field specifies an application area into which the package has been classified. See Section 2.4, `Sections'. When it appears in the `debian/control' file, it gives the value for the subfield of the same name in the `Files' field of the `.changes' file. It also gives the default for the same field in the binary packages. 5.6.6. `Priority' ----------------- This field represents how important that it is that the user have the package installed. See Section 2.5, `Priorities'. When it appears in the `debian/control' file, it gives the value for the subfield of the same name in the `Files' field of the `.changes' file. It also gives the default for the same field in the binary packages. 5.6.7. `Package' ---------------- The name of the binary package. Package names must consist only 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 start with an alphanumeric character. 5.6.8. `Architecture' --------------------- Depending on context and the control file used, the `Architecture' field can include the following sets of values: * A unique single word identifying a Debian machine architecture, see Section 11.1, `Architecture specification strings'. * `all', which indicates an architecture-independent package. * `any', which indicates a package available for building on any architecture. * `source', which indicates a source package. In the main `debian/control' file in the source package, or in the source package control file `.dsc', one may specify a list of architectures separated by spaces, or the special values `any' or `all'. Specifying `any' indicates that the source package isn't dependent on any particular architecture and should compile fine on any one. The produced binary package(s) will be specific to whatever the current build architecture is.[1] Specifying a list of architectures indicates that the source will build an architecture-dependent package, and will only work correctly on the listed architectures.[2] In a `.changes' file, the `Architecture' field lists the architecture(s) of the package(s) currently being uploaded. This will be a list; if the source for the package is also being uploaded, the special entry `source' is also present. See Section 4.9, `Main building script: `debian/rules'' for information how to get the architecture for the build process. [1] This is the most often used setting, and is recommended for new packages that aren't `Architecture: all'. [2] This is a setting used for a minority of cases where the program is not portable. Generally, it should not be used for new packages. 5.6.9. `Essential' ------------------ This is a boolean field which may occur only in the control file of a binary package or in a per-package fields paragraph of a main source control data file. If set to `yes' then the package management system will refuse to remove the package (upgrading and replacing it is still possible). The other possible value is `no', which is the same as not having the field at all. 5.6.10. Package interrelationship fields: `Depends', `Pre-Depends', `Recommends', `Suggests', `Breaks', `Conflicts', `Provides', `Replaces', `Enhances' ---------------------------------------------------------------------------- These fields describe the package's relationships with other packages. Their syntax and semantics are described in Chapter 7, `Declaring relationships between packages'. 5.6.11. `Standards-Version' --------------------------- The most recent version of the standards (the policy manual and associated texts) with which the package complies. 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] Ubuntu: Packages should not include the Ubuntu revision of the policy manual (e.g. "ubuntu1" in "3.8.0.1ubuntu1") in their _Standards-Version_ field. This tends to create unnecessary diffs relative to Debian. For the same reason, Ubuntu developers should not generally change the _Standards-Version_ field in packages originating in Debian. [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. 5.6.12. `Version' ----------------- The version number of a package. The 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, tilde) 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 Ubuntu package based on the upstream version. It may contain only alphanumerics and the characters `+' `.' `~' (plus, full stop, tilde) 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 or Ubuntu package, and so there is only one "debianisation" 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 is equivalent to a of `0'. Ubuntu: The string "ubuntu" in a version number instructs the archive management software not to copy newer versions of the package from Debian automatically. It should therefore be used when modifying packages relative to Debian, taking care that the Ubuntu version number compares less than the next expected version in Debian. For example, the first Ubuntu modification of version `1.0-1' in Debian would be `1.0-1ubuntu1'. When comparing two version numbers, first the of each are compared, then the if is equal, and then if is also equal. is compared numerically. The and parts are compared by the package management system using the following 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 and so that a tilde sorts before anything, even the end of a part. For example, the following parts are in sorted order from earliest to latest: `~~', `~~a', `~', the empty part, `a'.[2] 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). [1] Alphanumerics are `A-Za-z0-9' only. [2] One common use of `~' is for upstream pre-releases. For example, `1.0~beta1~svn1245' sorts earlier than `1.0~beta1', which sorts earlier than `1.0'. 5.6.13. `Description' --------------------- In a source or binary control file, the `Description' field contains a description of the binary package, consisting of two parts, the synopsis or the short description, and the long description. The field's format is as follows: Description: The lines in the extended description can have these formats: * Those starting with a single space are part of a paragraph. Successive lines of this form will be word-wrapped when displayed. The leading space will usually be stripped off. * Those starting with two or more spaces. These will be displayed verbatim. If the display cannot be panned horizontally, the displaying program will line wrap them "hard" (i.e., without taking account of word breaks). If it can they will be allowed to trail off to the right. None, one or two initial spaces may be deleted, but the number of spaces deleted from each line will be the same (so that you can have indenting work correctly, for example). * Those containing a single space followed by a single full stop character. These are rendered as blank lines. This is the _only_ way to get a blank line[1]. * Those containing a space, a full stop and some more characters. These are for future expansion. Do not use them. Do not use tab characters. Their effect is not predictable. See Section 3.4, `The description of a package' for further information on this. In a `.changes' file, the `Description' field contains a summary of the descriptions for the packages being uploaded. The part of the field before the first newline is empty; thereafter each line has the name of a binary package and the summary description line from that binary package. Each line is indented by one space. [1] Completely empty lines will not be rendered as blank lines. Instead, they will cause the parser to think you're starting a whole new record in the control file, and will therefore likely abort with an error. 5.6.14. `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. More information is available in the Debian Developer's Reference, section "The Debian archive". 5.6.15. `Date' -------------- This field includes the date the package was built or last edited. The value of this field is usually extracted from the `debian/changelog' file - see Section 4.4, `Ubuntu changelog: `debian/changelog''). 5.6.16. `Format' ---------------- This field specifies a format revision for the file. The most current format described in the Policy Manual is version _1.5_. The syntax of the format value is the same as that of a package version number except that no epoch or Debian revision is allowed - see Section 5.6.12, ``Version''. 5.6.17. `Urgency' ----------------- This is a description of how important it is to upgrade to this version from previous ones. It consists of a single keyword taking one of the values `low', `medium', `high', `emergency', or `critical'[1] (not case-sensitive) followed by an optional commentary (separated by a space) which is usually in parentheses. For example: Urgency: low (HIGH for users of diversions) The value of this field is usually extracted from the `debian/changelog' file - see Section 4.4, `Ubuntu changelog: `debian/changelog''. [1] Other urgency values are supported with configuration changes in the archive software but are not used in Ubuntu. The urgency affects how quickly a package will be considered for inclusion into the `testing' distribution and gives an indication of the importance of any fixes included in the upload. `Emergency' and `critical' are treated as synonymous. 5.6.18. `Changes' ----------------- This field contains the human-readable changes data, describing the differences between the last version and the current one. There should be nothing in this field before the first newline; all the subsequent lines must be indented by at least one space; blank lines must be represented by a line consisting only of a space and a full stop. The value of this field is usually extracted from the `debian/changelog' file - see Section 4.4, `Ubuntu changelog: `debian/changelog''). Each version's change information should be preceded by a "title" line giving at least the version, distribution(s) and urgency, in a human-readable way. If data from several versions is being returned the entry for the most recent version should be returned first, and entries should be separated by the representation of a blank line (the "title" line may also be followed by the representation of blank line). 5.6.19. `Binary' ---------------- This field is a list of binary packages. When it appears in the `.dsc' file it is the list of binary packages which a source package can produce. It does not necessarily produce all of these binary packages for every architecture. The source control file doesn't contain details of which architectures are appropriate for which of the binary packages. When it appears in a `.changes' file it lists the names of the binary packages actually being uploaded. The syntax is a list of binary packages separated by commas[1]. Currently the packages must be separated using only spaces in the `.changes' file. [1] A space after each comma is conventional. 5.6.20. `Installed-Size' ------------------------ This field appears in the control files of binary packages, and in the `Packages' files. It gives the total amount of disk space required to install the named package. The disk space is represented in kilobytes as a simple decimal number. 5.6.21. `Files' --------------- This field contains a list of files with information about each one. The exact information and syntax varies with the context. In all cases the part of the field contents on the same line as the field name is empty. The remainder of the field is one line per file, each line being indented by one space and containing a number of sub-fields separated by spaces. In the `.dsc' file, each line contains the MD5 checksum, size and filename of the tar file and (if applicable) diff file which make up the remainder of the source package[1]. The exact forms of the filenames are described in Section C.3, `Source packages as archives'. In the `.changes' file this contains one line per file being uploaded. Each line contains the MD5 checksum, size, section and priority and the filename. The section and priority are the values of the corresponding fields in the main source control file. If no section or priority is specified then `-' should be used, though section and priority values must be specified for new packages to be installed properly. The special value `byhand' for the section in a `.changes' file indicates that the file in question is not an ordinary package file and must by installed by hand by the distribution maintainers. If the section is `byhand' the priority should be `-'. If a new Ubuntu revision of a package is being shipped and no new original source archive is being distributed the `.dsc' must still contain the `Files' field entry for the original source archive `-.orig.tar.gz', but the `.changes' file should leave it out. In this case the original source archive on the distribution site must match exactly, byte-for-byte, the original source archive which was used to generate the `.dsc' file and diff which are being uploaded. [1] That is, the parts which are not the `.dsc'. 5.6.22. `Closes' ---------------- A space-separated list of Debian bug report numbers that the upload governed by the .changes file closes. 5.6.23. `Launchpad-Bugs-Fixed' ------------------------------ A space-separated list of Launchpad bug report numbers that the upload governed by the .changes file closes. 5.6.24. `Homepage' ------------------ The URL of the web site for this package, preferably (when applicable) the site from which the original source can be obtained and any additional upstream documentation or information may be found. The content of this field is a simple URL without any surrounding characters such as `<>'. 5.7. User-defined fields ------------------------ Additional user-defined fields may be added to the source package control file. Such fields will be ignored, and not copied to (for example) binary or source package control files or upload control files. If you wish to add additional unsupported fields to these output files you should use the mechanism described here. Fields in the main source control information file with names starting `X', followed by one or more of the letters `BCS' and a hyphen `-', will be copied to the output files. Only the part of the field name after the hyphen will be used in the output file. Where the letter `B' is used the field will appear in binary package control files, where the letter `S' is used in source package control files and where `C' is used in upload control (`.changes') files. For example, if the main source information control file contains the field XBS-Comment: I stand between the candle and the star. then the binary and source package control files will contain the field Comment: I stand between the candle and the star. ------------------------------------------------------------------------------- 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 must not be 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 exit with a zero status if everything went well. Additionally, packages interacting with users using `debconf' in the `postinst' script should install a `config' script in the control area, see Section 3.9.1, `Prompting in maintainer scripts' for details. 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 in 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. 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. 6.4. Exit status ---------------- Each script must return a zero exit status for success, or a nonzero one for failure, since the package management system looks for the exit status of these scripts and determines what action to take next based on that datum. 6.5. Summary of ways maintainer scripts are called -------------------------------------------------- * `install' * `install' * `upgrade' * `abort-upgrade' * `configure' * `abort-upgrade' * `abort-remove' `in-favour' * `abort-remove' * `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.6. 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 If this works, the upgrade continues. If this does not work, the error unwind: abort-upgrade If this works, then the old-version is "Installed", if not, the old version is in a "Failed-Config" state. 2. If a "conflicting" package is being removed at the same time, or if any package will be broken (due to `Breaks'): 1. If `--auto-deconfigure' is specified, call, for each package to be deconfigured due to `Breaks': deconfigure \ in-favour Error unwind: abort-deconfigure \ in-favour The deconfigured packages are marked as requiring configuration, so that if `--install' is used they will be configured again if possible. 2. If any packages depended on a conflicting package being removed 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. 3. To prepare for removal of each conflicting package, call: remove \ in-favour Error unwind: abort-remove \ in-favour 3. 1. If the package is being upgraded, call: upgrade If this fails, we call: abort-upgrade 1. If that works, then abort-upgrade is called. If this works, then the old version is in an "Installed" state, or else it is left in an "Unpacked" state. 2. If it fails, then the old version is left in an "Half-Installed" state. 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 Error unwind: abort-install If this fails, the package is left in a "Half-Installed" state, which requires a reinstall. If it works, the packages is left in a "Config Files" state. 3. Otherwise (i.e., the package was completely purged): install Error unwind: abort-install If the error-unwind fails, the package is in a "Half Installed" phase, and requires a reinstall. If the error unwind works, the package is in a not installed state. 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 contain files which are on the system in another package, unless `Replaces' is used (see Section 7.6, `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 If this works, installation continues. If not, Error unwind: abort-upgrade If this fails, the old version is left in an "Half Installed" state. If it works, dpkg now calls: abort-upgrade If this fails, the old version is left in an "Half Installed" state. If it works, dpkg now calls: abort-upgrade If this fails, the old version is in an "Unpacked" state. 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.7. 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 the configuration fails, the package is in a "Failed Config" state, and an error message is generated. If there is no most recently configured version `dpkg' will pass a null argument. [1] [1] Historical note: Truly ancient (pre-1997) versions of `dpkg' passed `' (including the angle brackets) in this case. Even older ones did not pass a second argument at all, under any circumstance. Note that upgrades using such an old dpkg version are unlikely to work for other reasons, even if this old argument behavior is handled by your postinst script. 6.8. Details of removal and/or configuration purging ---------------------------------------------------- 1. remove If prerm fails during replacement due to conflict abort-remove \ in-favour Or else we call: abort-remove If this fails, the package is in a "Failed-Config" state, or else it remains "Installed". 2. The package's files are removed (except `conffile's). 3. remove If it fails, there's no error unwind, and the package is in an "Half-Installed" state. 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 If this fails, the package remains in a "Config-Files" state. 7. The package's file list is removed. ------------------------------------------------------------------------------- 7. Declaring relationships between packages ------------------------------------------- 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 Section 5.6.12, ``Version''. 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 5.1, `Syntax of control files', and must appear where it's necessary to disambiguate; it is not otherwise significant. All of the relationship fields may span multiple lines. 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. When wrapping a relationship field, it is conventional to do so after a comma and before the space following that comma. 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 while others aren't.) 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] requires `kernel-headers-2.2.10' on all architectures other than hurd-i386 and requires `hurd-dev' and `gnumach-dev' only on hurd-i386. If the architecture-restricted dependency is part of a set of alternatives using `|', that alternative is ignored completely on architectures that do not match the restriction. For example: Build-Depends: foo [!i386] | bar [!amd64] is equivalent to `bar' on the i386 architecture, to `foo' on the amd64 architecture, and to `foo | bar' on all other architectures. 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' ---------------------------------------------------------------------------- Packages can declare in their control file that they have certain relationships to other packages - for example, that they may not be installed at the same time as certain other packages, and/or that they depend on the presence of others. This is done using the `Depends', `Pre-Depends', `Recommends', `Suggests', `Enhances', `Breaks' and `Conflicts' control file fields. These seven fields are used to declare a dependency relationship by one package on another. Except for `Enhances' and `Breaks', they appear in the depending (binary) package's control file. (`Enhances' appears in the recommending package's control file, and `Breaks' appears in the version of depended-on package which causes the named package to break). 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 `apt-get', `aptitude', and `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. In case of circular dependencies, since installation or removal order honoring the dependency order can't be established, dependency loops are broken at some point (based on rules below), and some packages may not be able to rely on their dependencies being present when being installed or removed, depending on which side of the break of the circular dependency loop they happen to be on. If one of the packages in the loop has no postinst script, then the cycle will be broken at that package, so as to ensure that all postinst scripts run with the dependencies properly configured if this is possible. Otherwise the breaking point is arbitrary. 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. Packages which break other packages - `Breaks' --------------------------------------------------- Using `Breaks' may cause problems for upgrades from older versions of Debian and should not be used until the stable release of Debian supports `Breaks'. Ubuntu: `Breaks' may safely be used in Ubuntu packages, as all supported upgrade paths to current releases involve upgrading `dpkg' to a version that supports `Breaks'. When one binary package declares that it breaks another, `dpkg' will refuse to allow the package which declares `Breaks' be installed unless the broken package is deconfigured first, and it will refuse to allow the broken package to be reconfigured. A package will not be regarded as causing breakage merely because its configuration files are still installed; it must be at least half-installed. A special exception is made for packages which declare that they break their own package name or a virtual package which they provide (see below): this does not count as a real breakage. Normally a `Breaks' entry will have an "earlier than" version clause; such a `Breaks' is introduced in the version of an (implicit or explicit) dependency which violates an assumption or reveals a bug in earlier versions of the broken package. This use of `Breaks' will inform higher-level package management tools that broken package must be upgraded before the new one. If the breaking package also overwrites some files from the older package, it should use `Replaces' (not `Conflicts') to ensure this goes smoothly. 7.4. 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.6, `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. Instead, `Breaks' may be used. 7.5. Virtual packages - `Provides' ---------------------------------- As well as the names of actual ("concrete") packages, the package relationship fields `Depends', `Recommends', `Suggests', `Enhances', `Pre-Depends', `Breaks', `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. (See also Section 3.6, `Virtual packages') If there are both concrete and virtual packages of the same name, then the dependency may be satisfied (or the conflict caused) by either the concrete package with the name in question or any other concrete package which provides the virtual package with the name in question. This is so that, for example, supposing we have Package: foo Depends: bar and someone else releases an enhanced version of the `bar' package 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 relationship field 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 or breakage) - 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.6. Overwriting files and replacing packages - `Replaces' ---------------------------------------------------------- Packages can declare in their control file that they should overwrite files in certain other packages, or completely replace other packages. The `Replaces' control file field has these two distinct purposes. 7.6.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.5, `Summary of ways maintainer scripts are called'. [1] For this usage of `Replaces', virtual packages (see Section 7.5, `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. [1] Replaces is a one way relationship -- you have to install the replacing package after the replaced package. 7.6.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.4, `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.7. Relationships between source and binary packages - `Build-Depends', `Build-Depends-Indep', `Build-Conflicts', `Build-Conflicts-Indep' ---------------------------------------------------------------------------- Source packages that require certain binary packages to be installed or absent at the time of building the package can declare relationships to those binary packages. This is done using the `Build-Depends', `Build-Depends-Indep', `Build-Conflicts' and `Build-Conflicts-Indep' control file fields. Build-dependencies on "build-essential" binary packages can be omitted. Please see Section 4.2, `Package relationships' for more information. 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:[1] `Build-Depends', `Build-Conflicts' The `Build-Depends' and `Build-Conflicts' fields must be satisfied when any of the following targets is invoked: `build', `clean', `binary', `binary-arch', `build-arch', `build-indep' 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: `build', `build-indep', `binary' and `binary-indep'. [1] If you make "build-arch" or "binary-arch", you need Build-Depends. If you make "build-indep" or "binary-indep", you need Build-Depends and Build-Depends-Indep. If you make "build" or "binary", you need both. There is no Build-Depends-Arch; this role is essentially met with Build-Depends. Anyone building the `build-indep' and binary-indep targets is basically assumed to be building the whole package anyway and so installs all build dependencies. The autobuilders use `dpkg-buildpackage -B', which calls `build' (not `build-arch', since it does not yet know how to check for its existence) and `binary-arch'. The purpose of the original split, I recall, was so that the autobuilders wouldn't need to install extra packages needed only for the binary-indep targets. But without a build-arch/build-indep split, this didn't work, since most of the work is done in the build target, not in the binary target. ------------------------------------------------------------------------------- 8. 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'). Packages involving shared libraries should be split up into several binary packages. This section mostly deals with how this separation is to be accomplished; rules for files within the shared library packages are in Section 10.2, `Libraries' instead. 8.1. Run-time shared libraries ------------------------------ The run-time shared library needs to be placed in a package whose name changes whenever the shared object version changes.[1] The most common mechanism is to place it in a package called `', where `' is the version number in the soname of the shared library[2]. Alternatively, if it would be confusing to directly append to (e.g. because itself ends in a number), you may use `-' and `--dev' instead. If you have several shared libraries built from the same source tree you may lump them all together into a single shared library package, provided that you change all of their sonames at once (so that you don't get filename clashes if you try to install different versions of the combined shared libraries package). The package should install the shared libraries under their normal names. For example, the `libgdbm3' package should install `libgdbm.so.3.0.0' as `/usr/lib/libgdbm.so.3.0.0'. 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. Shared libraries should not be installed executable, since the dynamic linker does not require this and trying to execute a shared library usually results in a core dump. The run-time library package should include the symbolic link that `ldconfig' would create for the shared libraries. For example, the `libgdbm3' package should include a symbolic link from `/usr/lib/libgdbm.so.3' to `libgdbm.so.3.0.0'. 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.[3] [1] Since it is common place to install several versions of a package that just provides shared libraries, it is a good idea that the library package should not contain any extraneous non-versioned files, unless they happen to be in versioned directories. [2] The soname is the shared object name: it's the thing that has to match exactly between building an executable and running it for the dynamic linker to be able run the program. For example, if the soname of the library is `libfoo.so.6', the library package would be called `libfoo6'. [3] 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. Since version 1.7.0, `dpkg' reorders the files itself as necessary when building a package. Thus it is no longer important to concern oneself with the order of file creation. 8.1.1. `ldconfig' ----------------- 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'[1] must use `ldconfig' to update the shared library system. The package maintainer scripts must only call `ldconfig' under these circumstances: * When the `postinst' script is run with a first argument of `configure', the script must call `ldconfig', and may optionally invoke `ldconfig' at other times. * When the `postrm' script is run with a first argument of `remove', the script should call `ldconfig'. [2] [1] These are currently * /usr/local/lib * /usr/lib/libc5-compat * /lib/libc5-compat [2] During install or upgrade, the preinst is called before the new files are installed, so calling "ldconfig" is pointless. The preinst of an existing package can also be called if an upgrade fails. However, this happens during the critical time when a shared libs may exist on-disk under a temporary name. Thus, it is dangerous and forbidden by current policy to call "ldconfig" at this time. When a package is installed or upgraded, "postinst configure" runs after the new files are safely on-disk. Since it is perfectly safe to invoke ldconfig unconditionally in a postinst, it is OK for a package to simply put ldconfig in its postinst without checking the argument. The postinst can also be called to recover from a failed upgrade. This happens before any new files are unpacked, so there is no reason to call "ldconfig" at this point. For a package that is being removed, prerm is called with all the files intact, so calling ldconfig is useless. The other calls to "prerm" happen in the case of upgrade at a time when all the files of the old package are on-disk, so again calling "ldconfig" is pointless. postrm, on the other hand, is called with the "remove" argument just after the files are removed, so this is the proper time to call "ldconfig" to notify the system of the fact that the shared libraries from the package are removed. The postrm can be called at several other times. At the time of "postrm purge", "postrm abort-install", or "postrm abort-upgrade", calling "ldconfig" is useless because the shared lib files are not on-disk. However, when "postrm" is invoked with arguments "upgrade", "failed-upgrade", or "disappear", a shared lib may exist on-disk under a temporary filename. 8.2. Shared library support files --------------------------------- If your package contains files whose names do not change with each change in the library shared object version, you must not put them in the shared library package. Otherwise, several versions of the shared library cannot be installed at the same time without filename clashes, making upgrades and transitions unnecessarily difficult. It is recommended that supporting files and run-time support programs that do not need to be invoked manually by users, but are nevertheless required for the package to function, be placed (if they are binary) in a subdirectory of `/usr/lib', preferably under `/usr/lib/'. If the program or file is architecture independent, the recommendation is for it to be placed in a subdirectory of `/usr/share' instead, preferably under `/usr/share/'. Following the naming convention ensures that the file names change when the shared object version changes. Run-time support programs that use the shared library but are not required for the library to function or files used by the shared library that can be used by any version of the shared library package should instead be put in a separate package. This package might typically be named `-tools'; note the absence of the in the package name. Files and support programs only useful when compiling software against the library should be included in the development package for the library.[1] [1] For example, a `-config' script or `pkg-config' configuration files. 8.3. Static libraries --------------------- The static library (`') is usually provided in addition to the shared version. It is placed into the development package (see below). In some cases, it is acceptable for a library to be available in static form only; these cases include: * libraries for languages whose shared library support is immature or unstable * libraries whose interfaces are in flux or under development (commonly the case when the library's major version number is zero, or where the ABI breaks across patchlevels) * libraries which are explicitly intended to be available only in static form by their upstream author(s) 8.4. Development files ---------------------- The development files associated to a shared library need to be placed in a package called `-dev', or if you prefer only to support one development version at a time, `-dev'. In case several development versions of a library exist, you may need to use `dpkg''s Conflicts mechanism (see Section 7.4, `Conflicting binary packages - `Conflicts'') to ensure that the user only installs one development version at a time (as different development versions are likely to have the same header files in them, which would cause a filename clash if both were installed). The development package should contain a symlink for the associated shared library without a version number. For example, the `libgdbm-dev' package should include a symlink from `/usr/lib/libgdbm.so' to `libgdbm.so.3.0.0'. This symlink is needed by the linker (`ld') when compiling packages, as it will only look for `libgdbm.so' when compiling dynamically. 8.5. Dependencies between the packages of the same library ---------------------------------------------------------- Typically the development version should have an exact version dependency on the runtime library, to make sure that compilation and linking happens correctly. The `${binary:Version}' substitution variable can be useful for this purpose. [1] [1] Previously, `${Source-Version}' was used, but its name was confusing and it has been deprecated since dpkg 1.13.19. 8.6. Dependencies between the library and other packages - 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. 8.6.1. 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 8.6.5, `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. 8.6.2. 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 `${shlibs: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 8.6.5, `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. If you are creating a udeb for use in the Debian Installer, you will need to specify that `dpkg-shlibdeps' should use the dependency line of type `udeb' by adding `-tudeb' as option[2]. If there is no dependency line of type `udeb' in the `shlibs' file, `dpkg-shlibdeps' will fall back to the regular dependency line. For more details on dpkg-shlibdeps, please see Section C.1.4, ``dpkg-shlibdeps' - calculates shared library dependencies' and 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. [2] `dh_shlibdeps' from the `debhelper' suite will automatically add this option if it knows it is processing a udeb. 8.6.3. 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 an optional element that indicates the type of package for which the line is valid. The only type currently in use is `udeb'. The colon and space after the type are required. 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. As zlib1g also provides a udeb containing the shared library, there would also be a second line: udeb: libz 1 zlib1g-udeb (>= 1:1.1.3) [1] This can be determined using the command objdump -p /usr/lib/libz.so.1.1.3 | grep SONAME 8.6.4. Providing a `shlibs' file -------------------------------- If your package provides a shared library, you need to 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. If your package also has a udeb that provides a shared library, `dh_makeshlibs' can automatically generate the `udeb:' lines if you specify the name of the udeb with the `--add-udeb' option. 8.6.5. 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.) ------------------------------------------------------------------------------- 9. The Operating System ----------------------- 9.1. File system hierarchy -------------------------- 9.1.1. File System Structure ---------------------------- The location of all installed files and directories must comply with the Filesystem Hierarchy Standard (FHS), version 2.3, with the exceptions noted below, and except where doing so would violate other terms of Ubuntu Policy. The following exceptions to the FHS apply: 1. The optional rules related to user specific configuration files for applications are stored in the user's home directory are relaxed. It is recommended that such files start with the '`.'' character (a "dot file"), and if an application needs to create more than one dot file then the preferred placement is in a subdirectory with a name starting with a '.' character, (a "dot directory"). In this case it is recommended the configuration files not start with the '.' character. 2. The requirement for amd64 to use `/lib64' for 64 bit binaries is removed. 3. The requirement that `/usr/local/share/man' be "synonymous" with `/usr/local/man' is relaxed to a recommendation 4. The requirement that windowmanagers with a single configuration file call it `system.*wmrc' is removed, as is the restriction that the window manager subdirectory be named identically to the window manager name itself. 5. The requirement that boot manager configuration files live in `/etc', or at least are symlinked there, is relaxed to a recommendation. The version of this document referred here can be found in the `ubuntu-policy' package or on FHS (Debian copy) (http://www.debian.org/doc/packaging-manuals/fhs/) alongside this manual (or, if you have the `ubuntu-policy' installed, you can try FHS (local copy) (file:///usr/share/doc/ubuntu-policy/fhs/)). 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 `ubuntu-devel' mailing list, or referred to the FHS mailing list (see the FHS web site (http://www.pathname.com/fhs/) for more information). 9.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 are not directories _in_ `/usr/local', but are children of directories in `/usr/local'. These directories (`/usr/local/*/dir/') 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'. 9.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. 9.2. Users and groups --------------------- 9.2.1. Introduction ------------------- The Ubuntu 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 Ubuntu 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'. 9.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 and Ubuntu system. These ids will appear in the `passwd' and `group' files of all Debian and Ubuntu 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. 9.3. System run levels and `init.d' scripts ------------------------------------------- 9.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 behaviors 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