X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=policy.sgml;h=827cbb570d5f853927c0d4dd32751815716f6d7a;hb=e98245e94cd784ba0b372affbf2a04e1a0bc157f;hp=0150cd1b1de576d013db1abb4720cfdffe453894;hpb=bb5aded03385ddde526aa81e7f7ac0b2cf13f9bb;p=debian%2Fdebian-policy.git diff --git a/policy.sgml b/policy.sgml index 0150cd1..827cbb5 100644 --- a/policy.sgml +++ b/policy.sgml @@ -44,7 +44,7 @@ This manual describes the policy requirements for the Debian GNU/Linux distribution. This includes the structure and - contents of the Debian archive, several design issues of the + contents of the Debian archive and several design issues of the operating system, as well as technical requirements that each package must satisfy to be included in the distribution. The policy package itself is maintained by a group of maintainers @@ -52,13 +52,7 @@ maintainers is: -

Michael Alan Dorman mdorman@debian.org

- - -

Philip Hands phil@hands.com

- - -

Julian Gilbey J.D.Gilbey@qmw.ac.uk

+

Julian Gilbey jdg@debian.org

Manoj Srivastava srivasta@debian.org

@@ -89,12 +83,12 @@

A copy of the GNU General Public License is available as - /usr/share/common-licences/GPL in the Debian GNU/Linux + /usr/share/common-licenses/GPL in the Debian GNU/Linux distribution or on the World Wide Web at . You can also obtain it by writing to the - Free Software Foundation, Inc., 59 Temple Place - Suite 330, - Boston, MA 02111-1307, USA. + name="The GNU General Public Licence">. You can also + obtain it by writing to the Free Software Foundation, Inc., + 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

@@ -108,7 +102,7 @@

This manual describes the policy requirements for the Debian GNU/Linux distribution. This includes the structure and - contents of the Debian archive, several design issues of the + contents of the Debian archive and several design issues of the operating system, as well as technical requirements that each package must satisfy to be included in the distribution. @@ -126,19 +120,20 @@

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 - 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 and - changelog file formats are one example) + 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 @@ -159,7 +154,7 @@

- Please note that the footnotes present in this manual are + The footnotes present in this manual are merely informative, and are not part of Debian policy itself.

@@ -169,7 +164,7 @@ 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 the the + this policy document. Packages that do not conform to the guidelines denoted by must (or required) will generally not be considered acceptable for the Debian distribution. Non-conformance with guidelines denoted by @@ -181,79 +176,95 @@

These classifications are roughly equivalent to the bug - severities important (for must or - required directive violations), normal + severities serious (for must or + required directive violations), minor, + normal or important (for should or recommended directive violations) and wishlist (for optional items). -

Also see RFC 2119.

+

Compare RFC 2119. Note, however, that these words are + used in a different way in this document.

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 for local use. + distributed in some other way or is intended for local use + only.

New versions of this document

- The current version of this document is always accessible from the - Debian FTP server ftp.debian.org at - /debian/doc/package-developer/debian-policy.html.tar.gz - or from the Debian WWW server at - .

+ The current version of this document is always accessible + from the Debian FTP server ftp.debian.org + as + /debian/doc/package-developer/policy.txt.gz + (also available from the same directory are several other + formats: policy.html.tar.gz, policy.pdf.gz + and policy.ps.gz) or from the webpage.

In addition, this manual is distributed via the Debian package debian-policy.

+ +

+ The debian-policy package also includes the file + upgrading-checklist.txt which indicates policy + changes between versions of this document. +

Feedback

As the Debian GNU/Linux system is continuously evolving this - manual is changed from time to time. + manual does so too.

- While the authors of this document tried hard not to include - any typos or other errors these still occur. If you discover - an error in this manual or if you want to tell us any - comments, suggestions, or critics please send an email to + 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, debian-policy@lists.debian.org, or submit a bug report against the debian-policy package.

+ The Debian Archive

The Debian GNU/Linux system is maintained and distributed as a - collection of packages. Since there are so many of them (over - 5000) they are split into sections and priorities to - simplify handling of them. + collection of packages. Since there are so many of + them (currently well over 6000), they are split into + sections and given priorities to simplify + the handling of them.

The effort of the Debian project is to build a free operating system, but not every package we want to make accessible is - free in our sense (see Debian Free Software + free in our sense (see the Debian Free Software Guidelines, below), or may be imported/exported without restrictions. Thus, the archive is split into the sections main, non-free, contrib, non-US/main, non-US/non-free, and - non-US/contrib.

+ non-US/contrib. The sections are explained in detail + below. +

- The main and the non-US/main sections form - the Debian GNU/Linux distribution. + The main and the non-US/main sections + together form the Debian GNU/Linux distribution.

- Packages in the other sections are not considered as part of - the Debian distribution, though we support their use, and we + Packages in the other sections are not considered to be part + of the Debian distribution, although we support their use and provide infrastructure for them (such as our bug-tracking system and mailing lists). This Debian Policy Manual applies to these packages as well.

@@ -261,18 +272,19 @@ Package copyright and sections

- The aims of this policy are: + The aims of this section are: -

We want to make as much software available as we - can.

+

to allow us to make as much software available as we + can,

-

We want to encourage everyone to write free software.

+

to allow us to encourage everyone to write free + software, and

 -

We want to make it easy for people to produce +

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.

 @@ -281,8 +293,8 @@ The Debian Free Software Guidelines

- The Debian Free Software Guidelines (DFSG) is our - definition of `free' software. + The Debian Free Software Guidelines (DFSG) form our + definition of `free software'. These are: Free Redistribution @@ -326,7 +338,7 @@ source code. The license may require derived works to carry a different name or version number from the original software. (This is a compromise. The Debian - group encourages all authors to not restrict any + Project encourages all authors to not restrict any files, source or binary, from being modified.)

@@ -398,23 +410,26 @@ The main section

- Every package in "main" and "non-US/main" must comply with - the DFSG (Debian Free Software Guidelines).

+ Every package in main and non-US/main + must comply with the DFSG (Debian Free Software + Guidelines).

- In addition, the packages in "main" + 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 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

@@ -426,12 +441,13 @@

- Similarly, the packages in "non-US/main" + Similarly, the packages in non-US/main

- must not require a package outside of "main" or - "non-US/main" for compilation or execution, + must not require a package outside of main + or non-US/main for compilation or + execution,

@@ -451,63 +467,121 @@ The contrib section

- Every package in "contrib" and "non-US/contrib" must - comply with the DFSG. + Every package in contrib and + non-US/contrib must comply with the DFSG.

- Examples of packages which would be included in "contrib" - or "non-US/contrib" are + In addition, the packages in contrib and + non-US/contrib

- free packages which require "contrib", "non-free" - packages or packages which are not in our - archive at all for compilation or execution, + must not be so buggy that we refuse to support them, + and +

+ + +

+ must meet all policy requirements presented in this + manual. +

+ + +

+ +

+ Furthermore, packages in contrib must not require + a package in a non-US section for compilation or + execution. +

+ +

+ Examples of packages which would be included in + contrib or non-US/contrib are: + + +

+ free packages which require contrib, + non-free packages or packages which are not + in our archive at all for compilation or execution, + and

wrapper packages or other sorts of free accessories for - non-free programs, + non-free programs.

- The non-free section and non-US/non-free + The non-free section

- Packages must be placed in "non-free" or "non-US/non-free" - if they are not compliant with the DFSG or are encumbered - by patents or other legal issues that make their - distribution problematic. + Packages must be placed in non-free or + non-US/non-free if they are not compliant with + the DFSG or are encumbered by patents or other legal + issues that make their distribution problematic. +

+

+ In addition, the packages in non-free and + non-US/non-free + + +

+ must not be so buggy that we refuse to support them, + and +

+ + +

+ must meet all policy requirements presented in this + manual that it is possible for them to meet. + +

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

+ +

+ +

+ The non-US sections

- Some programs with cryptographic program code need to be stored - on the "non-US" server because of export restrictions of the - U.S. Such programs must be distributed in the appropriate - non-US section, either non-US/main, non-US/contrib or - non-US/non-free.

+ Some programs with cryptographic program code need to be + stored on the non-US server because of United + States export restrictions. Such programs must be + distributed in the appropriate non-US section, + either non-US/main, non-US/contrib or + non-US/non-free. +

This applies only to packages which contain cryptographic - code. A package containing a program with an interface to a - cryptographic program or a program that's dynamically linked - against a cryptographic library should not be distributed - via the non-us server if it is capable of running without the - cryptography library or program. + code. A package containing a program with an interface to + a cryptographic program or a program that's dynamically + linked against a cryptographic library should not be + distributed via the non-US server if it is + capable of running without the cryptographic library or + program.

Further copyright considerations

- Every package must be accompanied by a verbatim copy of its - copyright and distribution license in the file - /usr/share/doc/<package-name>/copyright (see - for details).

+ Every package must be accompanied by a verbatim copy of + its copyright and distribution license in the file + /usr/share/doc/<package>/copyright + (see for further details). +

We reserve the right to restrict files from being included anywhere in our archives if @@ -538,91 +612,130 @@

- 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; otherwise they must - go in non-free.

+ Programs whose authors encourage the user to make + donations are fine for the main distribution, provided + that the authors do not claim that not donating is + immoral, unethical, illegal or something similar; in such + a case they must go in non-free.

Packages whose copyright permission notices (or patent - problems) do not allow redistribution even of only binaries, - and where no special permission has been obtained, must not be - placed on the Debian FTP site and its mirrors at all.

+ problems) do not even allow redistribution of binaries + only, and where no special permission has been obtained, + must not be placed on the Debian FTP site and its mirrors + at all.

- Note, that under international copyright law (this applies - in the United States, too) no distribution or - modification of a work is allowed without an explicit notice - saying so. Therefore a program without a copyright notice - is copyrighted and you may not do anything to it - without risking being sued! Likewise if a program has a - copyright notice but no statement saying what is permitted - then nothing is permitted.

+ 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 + 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 is a + them to modify their license terms. However, this can be a politically difficult thing to do and you should ask for - advice on debian-legal first.

+ advice on the debian-legal mailing list first, as + explained below. +

- When in doubt, send mail to + When in doubt about a copyright, send mail to debian-legal@lists.debian.org. 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'.

+ copyrights are safe; be wary of the phrases `commercial + use prohibited' and `distribution restricted'. +

Subsections

- The packages in all the sections (main, - contrib, non-US/main, non-free, - non-US/contrib, and non-US/non-free) are - grouped further into subsections to simplify - handling.

+ The packages in the sections main, + contrib and non-free are grouped further + into subsections to simplify handling. +

- The section for each package should be specified in the - package's control record. However, the maintainer of - the Debian archive may override this selection to assure the - consistency of the Debian distribution.

+ The section and subsection for each package should be + specified in the package's Section control + record. However, the maintainer of the Debian archive + may override this selection to ensure the consistency of + the Debian distribution. The Section field + should be of the form: + + +

+ subsection if the package is in the + main section, +

+ + +

+ section/subsection if the package is in + the contrib or non-free section, + and +

+ + +

+ non-US, non-US/contrib or + non-US/non-free if the package is in + non-US/main, non-US/contrib or + non-US/non-free respectively. +

+ + +

- Please check the current Debian distribution to see which - sections are available.

+ The Debian archive maintainers provide the authoritative + list of subsections. At present, they are: + admin, base, comm, + contrib, devel, doc, + editors, electronics, games, + graphics, hamradio, + interpreters, libs, mail, + math, misc, net, news, + non-US, non-free, oldlibs, + otherosfs, science, shells, + sound, tex, text, + utils, web, x11. +

Priorities

- Each package should have a priority value, - which is included in the package's control - record. This information is used in the Debian package - management tool to separate high-priority packages from - less-important packages.

+ Each package should have a priority value, which is + included in the package's control record. This + information is used by the Debian package management tools + to separate high-priority packages from less-important + packages.

- The following priority levels are supported by the - Debian package management system, dpkg. + The following priority levels are recognised by the + Debian package management tools. required

- required packages are necessary for the - proper functioning of the system. You must not remove - these packages or your system may become totally - broken and you may not even be able to use - dpkg to put things back. Systems with - only the required packages are probably - unusable, but they do have enough functionality to - allow the sysadmin to boot and install more - software.

+ Packages which are necessary for the proper + functioning of the system. You must not remove these + packages or your system may become totally broken and + you may not even be able to use dpkg to + put things back. Systems with only the + required packages are probably unusable, but + they do have enough functionality to allow the + sysadmin to boot and install more software.

important @@ -630,40 +743,46 @@ 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 the F*!@<+ is - going on, where is foo', it must be in - important. This is an important criterion - because we are trying to produce, amongst other - things, a free Unix. Other packages without which the - system will not run well or be usable must also be - here. 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.

+ found it missing would say `What on earth is going on, + where is foo?', it must be an + important package. + +

+ This is an important criterion because we are + trying to produce, amongst other things, a free + Unix. +

+ + 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 - install by default if the user doesn't select anything + 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, but it does include Emacs (this is more of a piece of infrastructure than an application) and a reasonable - subset of TeX and LaTeX (if this is possible without - X).

+ subset of TeX and LaTeX.

 optional

- (In a sense everything is optional that isn't - required, but that's not what is meant here.) This is + (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 or don't have + 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. + and includes the X Window System, a full TeX + distribution, and many applications. Note that + optional packages should not conflict with each other.

extra @@ -681,8 +800,8 @@

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 must - be adjusted. + ensure this, the priorities of one or more packages may need + to be adjusted.

@@ -704,8 +823,12 @@ archive.

- Package names must only consist of lower case letters, digits (0-9), - plus (+) or minus (-) signs, and periods (.).

+ Package names must consist of lower case letters + (a-z), digits (0-9), plus (+) + and minus (-) signs, and periods (.). + They must be at least two characters long and must contain + at least one letter. +

The package name is part of the file name of the @@ -717,29 +840,42 @@ The maintainer of a package

- Every package must have a 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 distribution + 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 the correct name - and a working email address for the Debian maintainer of - the package. If one person maintains several packages - he/she should try to avoid having different forms of their - name and email address in different Maintainer - fields.

+ Maintainer control field with their correct name + and a working email address. If one person maintains + several packages, he/she should try to avoid having + different forms of their name and email address in + the Maintainer fields of those packages. +

If the maintainer of a package quits from the Debian - project the Debian QA Group - debian-qa@lists.debian.org takes over the + project, "Debian QA Group" + packages@qa.debian.org takes over the maintainership of the package until someone else volunteers for that task. These packages are called orphaned packages. + +

+ The detailed procedure for doing this gracefully can + be found in the Debian Developer's Reference, either + in the developers-reference package, or on + the Debian FTP server + ftp.debian.org as + /debian/doc/package-developer/developers-reference.txt.gz + or from the webpage. +

+

@@ -752,15 +888,16 @@ stored in the appropriate field of the control record.

- The description should be written so that it tells the user - what they need to know to decide whether to install the - package. This description should not just be copied from - the blurb for the program. 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 -- that is what the copyright file is - for.

+ The description should be written so that it gives the + system administrator enough information to decide whether + to install the package. This description should not just + be copied verbatim from the program's documentation. + Instructions for configuring or using the package should + not be included (that is what installation scripts, + manual pages, info files, etc., are for). Copyright + statements and other administrivia should not be included + either (that is what the copyright file is for). +

@@ -800,13 +937,13 @@ Virtual packages

- Sometimes, there are several packages doing more-or-less - the same job. In this case, it's useful to define a - virtual package whose name describes the function - the packages have. (The virtual packages just exist - logically, not physically--that's why they are called - virtual.) The packages with this particular - function will then provide the virtual + 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.

@@ -823,7 +960,7 @@ The latest version of the authoritative list of virtual package names can be found on ftp.debian.org in - /debian/doc/package-developer/virtual-package-names-list.text + /debian/doc/package-developer/virtual-package-names-list.txt or your local mirror. In addition, it is included in the debian-policy package. The procedure for updating the list is described at the top of the file.

@@ -862,11 +999,11 @@ for a system.

- Since these packages can not easily be removed (you'll - have to specify an extra force option to - dpkg) this flag must not be used unless - absolutely necessary. A shared library package must not - be tagged essential--the dependencies will + 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.

@@ -874,7 +1011,7 @@

Since dpkg will not prevent upgrading of other packages while an essential package is in an unconfigured - state, all essential packages must supply all + 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 @@ -885,9 +1022,10 @@

You must not tag any packages essential before this has been discussed on the debian-devel - mailing and a consensus about doing that has been - reached.

- + mailing list and a consensus about doing that has been + reached. +

+ Maintainer scripts @@ -907,7 +1045,7 @@

- Note, that , in general applies to package + Note that in general applies to package maintainer scripts, too.

@@ -926,8 +1064,9 @@ 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 this not allowed). + update-alternatives; this is an exception to + the usual rule that versioned conflicts should be + avoided).

@@ -939,21 +1078,22 @@ communicating with a program, such as debconf, which conforms to the Debian Configuration management specification, version 2 or - higher. (Included in the + higher. These are included in the debconf_specification files in the - debian-policy package.) + debian-policy package. You may also find this file on the FTP site ftp.debian.org in /debian/doc/package-developer/debconf_specification.txt.gz - or your local mirror. + or on your local mirror.

- 2.5% of Debian packages - [] - use debconf to prompt the user at install time, and - this number is growing daily. The benefits of using - debconf are briefly explained at - ; + 2.5% of Debian packages [see ] + currently use debconf to prompt + the user at install time, and this number is growing + daily. The benefits of using debconf are briefly + explained at ; they include preconfiguration, (mostly) noninteractive installation, elimination of redundant prompting, consistency of user interface, @@ -961,12 +1101,13 @@

With this increasing number of packages using - debconf, plus the existance of a nascent second - implementation of the Debian configuration - management system (cdebconf), and - the stabalization of the protocol these things use, - the time has finally come to reflect the use of - these things in policy. + debconf, plus the existance of a + nascent second implementation of the Debian + configuration management system + (cdebconf), and the stabalization + of the protocol these things use, the time has + finally come to reflect the use of these things in + policy.

@@ -976,17 +1117,18 @@ specification may contain an additional config script and a templates file in their control archive. The config - script can be run before the preinst, and before the - package is unpacked or any of its dependancies or - pre-dependancies are satisfied, so it must work using - only the tools present in the Essential - packages. + script might be run before the preinst + script, and before the package is unpacked or any of its + dependancies or pre-dependancies are satisfied. + Therefore it must work using only the tools present in + essential packages.

- Debconf or another tool that implements the Debian - Configuration management specification will also be - installed, and any versioned dependancies on it will - be satisfied before preconfiguration begins. + 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.

@@ -997,9 +1139,10 @@ 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. + /etc/news/server), and shared + debconf variables rather than each + prompting for their own list of required pieces of + information.

@@ -1023,7 +1166,7 @@ important (they belong in /usr/share/doc/package/copyright); neither do instructions on how to use a program (these - should be in on line documentation, where all the users + should be in on-line documentation, where all the users can see them).

@@ -1041,26 +1184,25 @@ Source packages - + Standards conformance

- You should specify the most recent version of the - packaging standards with which your package complies in - the source package's Standards-Version field.

- -

- This value will be used to file bug reports automatically - if your package becomes too much out of date.

+ In the source package's Standards-Version control + field, you must specify the most recent version number of + this policy document with which your package complies. + The current version number is &version;. +

- The value corresponds to a version of the Debian manuals, - as can be found on the title page or page headers and - footers (depending on the format).

+ This information may be used to file bug reports + automatically if your package becomes too much out of + date. +

- The version number has four components--major and minor - number and major and minor patch level. When the + 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 @@ -1068,22 +1210,24 @@ 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 - which do not change the meaning are made, or changes which - do not affect the contents of packages.

+ are made which neither change the meaning of the document + nor affect the contents of packages.

- For package maintainers, only the first 3 digits of the - manual version are significant in representing the - Standards-Version, and either these 3 digits or - the complete 4 digits may be specified. + 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.

- In the past, people specified 4 digits in the - Standards-Version field, like `2.3.0.0'. Since any - `patch-level changes' don't introduce new policy, it - was thought it would be better to relax policy and - only require that the first 3 digits are specified. (4 - digits may still be used if someone wants to do so.) + 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.

@@ -1094,7 +1238,16 @@ 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.

 + release it. + +

+ See the file upgrading-checklist for + information about policy which has changed between + different versions of this document. +

+ +

+ @@ -1120,28 +1273,29 @@ package).

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

Having a separate package allows one to install - the build essential packages on a machine, as - well as allowing other packages (think task - packages) to bring in the build-essential - packages using the depends relation + the build-essential packages on a machine, as + well as allowing other packages such as task + packages to require installation of the + build-essential packages using the depends + relation.

The separate package allows bug reports against - the package to be categorized separately from - the policy management process that uses the BTS + the list to be categorized separately from + the policy management process in the BTS.

@@ -1155,42 +1309,56 @@ 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. The reason is - that dependencies change, and you should list only those - you need. What others need is their business. + build-time dependencies depends on them. + +

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

+

If build-time dependencies are specified, it must be possible to build the package and produce working binaries - on a system with the build-essential packages installed - and satisfying the build-time relationships (including any - implied relationships). This - means in particular 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. + 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.

Changes to the upstream sources

- If changes to the source code are made that are generally - applicable, 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 changes to the source code are made that are not + specific to the needs of the Debian system, they should be + sent to the upstream authors in whatever form they prefer + so as to be included in the upstream version of the + package.

If you need to configure the package differently for Debian or for Linux, and the upstream source doesn't - provide a way to configure it the way you need to, 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.

+ 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 @@ -1215,20 +1383,31 @@ You should document your changes and updates to the source package properly in the debian/changelog file. (Note that mistakes in changelogs are usually best rectified by - making a new changelog entry rather than "rewriting history" - by editing old changelog entries)

+ making a new changelog entry rather than "rewriting history" + by editing old changelog entries.)

- In non-experimental packages you must only use a format for + In non-experimental packages you must use a format for debian/changelog which is supported by the most - recent released version of dpkg. If your - format is not supported and there is general support for - it you should contact the dpkg maintainer to - have the parser script for your format included in the - dpkg package. (You will need to agree that - the parser and its manpage may be distributed under the - GNU GPL, just as the rest of dpkg - is.)

 + recent released version of dpkg. + +

+ If you wish to use an alternative format, you may do + so as long as you include a parser for it in your + source package. The parser must have an API + compatible with that expected by + dpkg-genchanges and + dpkg-gencontrol. If there is general + interest in the new format, you should contact the + dpkg maintainer to have the parser + script for it included in the dpkg + package. (You will need to agree that the parser and + its manpage may be distributed under the GNU GPL, just + as the rest of `dpkg' is.) +

+ +

+ @@ -1236,8 +1415,8 @@

When make invokes a command in a makefile - (including your package's upstream makefiles and the - debian/rules) it does so using sh. This + (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 @@ -1270,9 +1449,10 @@ only available in binary form).

- Debian packages should be ported to include - <stdarg.h> and ncurses when - they are built.

+ Debian packages should be patched to use + <stdarg.h> and ncurses + instead. +

@@ -1281,29 +1461,40 @@

Many of the tools in the package management suite manipulate - data in a common format, known as control files. Binary and - source packages have control data as do the .changes - files which control the installation of uploaded files, and - dpkg's internal databases are in a similar + data represented in a common format, known as control + data. The data is often stored in control + files. Binary and source packages have control files, + and the .changes files which control the installation + of uploaded files are also in control file format. + Dpkg's internal databases are in a similar format.

- Syntax of control files + Syntax of control files

- A file consists of one or more paragraphs of fields. The - paragraphs are separated by blank lines. Some control files - only allow one paragraph; others allow several, in which - case each paragraph often refers to a different package. + A control file consists of one or more paragraphs of fields. + The paragraphs are separated by blank lines. Some control + files allow only one paragraph; others allow several, in + which case each paragraph usually refers to a different + package. (For example, in source packages, the first + paragraph refers to the source package, and later paragraphs + refer to binary packages generated from the source.)

- Each paragraph is a series of fields and values; each field - consists of a name, followed by a colon and the value. It - ends at the end of the line. Horizontal whitespace (spaces - and tabs) may occur immediately before or after the value - and is ignored there; it is conventional to put a single - space after the colon. + Each paragraph consists of a series of data fields; each + field consists of the field name, followed by a colon and + then the data/value associated with that field. It ends at + the end of the line. Horizontal whitespace (spaces and + tabs) may occur immediately before or after the value and is + ignored there; it is conventional to put a single space + after the colon. For example, a field might be: + +Package: libc6 + + the field name is Package and the field value + libc6.

@@ -1316,9 +1507,9 @@

Except where otherwise stated only a single line of data is allowed and whitespace is not significant in a field body. - Whitespace may never appear inside names (of packages, - architectures, files or anything else), version numbers or - in between the characters of multi-character version + 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.

@@ -1333,21 +1524,12 @@ would mean a new paragraph.

-

- It is important to note that there are several fields which - are optional as far as dpkg and the related - tools are concerned, but which must appear in every Debian - package, or whose omission may cause problems. When writing - the control files for Debian packages you must read - the Debian policy manual in conjunction with the details - below and the list of fields for the particular file.

 List of fields

This list here is not supposed to be exhaustive. Most fields - are dealt with elsewhere in this document and in the - packaging manual. + are dealt with elsewhere in this document.

Package @@ -1360,10 +1542,10 @@

They must be at least two characters long and must start - with an alphanumeric character. The use of lowercase - package names is strongly recommended unless the package - you're building (or referring to, in other fields) is - already using uppercase.

+ with an alphanumeric character and not be all digits. The + use of lowercase package names is strongly recommended + unless the package you're building (or referring to, in + other fields) is already using uppercase.

 Version @@ -1386,12 +1568,9 @@ complies. This is updated manually when editing the source package to conform to newer standards; it can sometimes be used to tell when a package needs attention. + Its format is described above; see + .

- -

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

 @@ -1402,23 +1581,21 @@ In a .changes file or parsed changelog output this contains the (space-separated) name(s) of the distribution(s) where this version of the package should - be or was installed. Distribution names follow the rules - for package names. (See ). -

- -

+ be installed. Valid distributions are determined by the + archive maintainers. - Current distribution values are: - + Current distribution names are: + stable

This is the current `released' version of Debian - GNU/Linux. Once the - distribution is stable only major bug fixes - are allowed. When changes are made to this - distribution, the release number is increased - (for example: 1.2r1 becomes 1.2r2 then 1.2r3, etc). + 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).

@@ -1434,71 +1611,51 @@

+ 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 unstable + From time to time, the frozen 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. + 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 + 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.

- There are several sections in each - distribution. Currently, these sections are: - - main - -

- The packages in this section are those in the - main Debian distribution. They are all free - (according to the Debian free software - guidelines) and meet any other criteria for - inclusion described in this manual.

- - - contrib - -

- The packages in this section do not meet the - criteria for inclusion in the main Debian - distribution as defined by this manual, but are - otherwise free, as defined by the Debian free - software guidelines.

- - - non-free - -

- Packages in non-free do not meet the - criteria of free software, as defined by the - Debian free software guidelines. Again, use your - best judgment in downloading from this - Distribution.

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

@@ -1507,11 +1664,11 @@ - Version numbering + Version numbering

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

@@ -1526,7 +1683,7 @@

The version number format is: - &lsqbepoch:]upstream-version[-debian-revision] + &lsqbepoch:]upstream_version[-debian_revision]

@@ -1538,7 +1695,7 @@

This is a single (generally small) unsigned integer. It may be omitted, in which case zero is assumed. If it is - omitted then the upstream-version may not + omitted then the upstream_version may not contain any colons.

@@ -1550,81 +1707,84 @@ - upstream-version + upstream_version

- This is the main part of the version. 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. + 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 upstream-version is - described below. The upstream-version + with respect to the upstream_version is + described below. The upstream_version portion of the version number is mandatory.

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

Alphanumerics are A-Za-z0-9 only.

+ + and the characters . + - + : (full stop, plus, hyphen, colon) and should + start with a digit. If there is no + debian_revision then hyphens are not allowed; if there is no epoch then colons are not allowed.

 - debian-revision + debian_revision

- This part of the version represents the version of the - modifications that were made to the package to make it a - Debian binary package. It is in the same format as the - upstream-version and is compared in the same - way. + This part of the version number specifies the version of + the Debian package based on the upstream version. It + may contain only alphanumerics and the characters + + and . (plus and full stop) and is + compared in the same way as the + upstream_version is.

It is optional; if it isn't present then the - upstream-version may not contain a hyphen. + upstream_version may not contain a hyphen. This format represents the case where a piece of software was written specifically to be turned into a - Debian binary package, and so there is only one - `debianization' of it and therefore no revision - indication is required. + Debian package, and so there is only one `debianization' + of it and therefore no revision indication is required.

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

- -

- The package management system will break the - upstream-version and - debian-revision apart at the last hyphen in - the string. The absence of a debian-revision - compares earlier than the presence of one (but note that - the debian-revision is the least significant - part of the version number). + debian_revision at 1 each time the + upstream_version is increased.

- The debian-revision may contain only - alphanumerics and the characters + and - . (plus and full stop). + The package management system will break the version + number apart at the last hyphen in the string (if there + is one) to determine the upstream_version and + debian_revision. The absence of a + debian_revision compares earlier than the + presence of one (but note that the + debian_revision is the least significant part + of the version number).

- The upstream-version and debian-revision +

+ +

+ The upstream_version and debian_revision parts are compared by the package management system using the same algorithm:

@@ -1653,21 +1813,22 @@

- These two steps are repeated (chopping initial non-digit - strings and initial digit strings off from the start) until a + 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 changes. It is not there - 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). + 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).

@@ -1698,7 +1859,7 @@ too.

- Note, that other version formats based on dates which are + Note that other version formats based on dates which are parsed correctly by the package management system should not be changed.

@@ -1713,10 +1874,9 @@ Time Stamps

- Maintainers are encouraged to preserve the modification - times of the upstream source files in a package, as far as - is reasonably possible. Even though this is optional, this - is still a good idea. + Maintainers should preserve the modification times of the + upstream source files in a package, as far as is reasonably + possible.

The rationale is that there is some information conveyed @@ -1731,12 +1891,12 @@ debian/rules - the - main building script + main building script

This file must be an executable makefile, and contains the package-specific recipes for compiling the package and - building binary package(s) out of the source. + building binary package(s) from the source.

@@ -1749,7 +1909,7 @@ 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 + 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, @@ -1759,17 +1919,21 @@

- The targets which must be present are: + The required and optional targets are as follows: build

- This should perform all non-interactive - configuration and compilation of the package. If a - package has an interactive pre-build configuration - routine, the Debianised source package should be - built after this has taken place, so that it can be - built without rerunning the configuration. + This should perform all non-interactive configuration + and compilation of the package. If a package has an + interactive pre-build configuration routine, the + Debianized source package must either be built after + this has taken place (so that the binary package can + be built without rerunning the configuration) or the + configuration routine modified to become + non-interactive. (The latter is preferable if there + are architecture-specific features detected by the + configuration routine.)

@@ -1792,19 +1956,35 @@

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

- When a package has a configuration routine that - takes a long time, or when the makefiles are poorly - designed, or when build needs to run - clean first, it is a good idea to + 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. + build is run again it will not rebuild the whole + program. + +

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

+

@@ -1814,11 +1994,11 @@

The binary target must be all that is - necessary for the user to build the binary - package. All these targets are required to be - non-interactive. It is split into two parts: - binary-arch builds the packages' output - files which are specific to a particular + necessary for the user to build the binary package(s) + produced from this source package. All of these + targets are required to be non-interactive. It is + split into two parts: binary-arch builds + the binary packages which are specific to a particular architecture, and binary-indep builds those which are not.

@@ -1831,7 +2011,7 @@

- Both binary-* targets should depend on + Each binary-* target should depend on the build target, above, so that the package is built if it has not been already. It should then create the relevant binary package(s), @@ -1842,17 +2022,24 @@

- If one of the binary-* targets has - nothing to do (this will be always be the case if - the source generates only a single binary package, - whether architecture-dependent or not) it - must still exist, and must always - succeed. + 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. + +

+ The fakeroot package often allows one + to build a package correctly even without being + root. +

+

@@ -1860,19 +2047,18 @@

- 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 binary. This target must be - non-interactive. + This must undo any effects that the build + and binary targets may have had, except + that it should leave alone any output files created in + the parent directory by a run of a binary + target. This target must be non-interactive.

- If a build file is touched at the end - of the build target, as suggested - above, it should be removed as the first thing that - clean does, so that running + 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. @@ -1915,8 +2101,8 @@

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

@@ -1927,11 +2113,14 @@

- The architecture we build on and build for is determined by - make variables via dpkg-architecture. You can get the Debian - architecture and the GNU style architecture specification - string for the build machine as well as the host - machine. Here is a list of supported make variables: + 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)

@@ -1941,25 +2130,23 @@ specification string)

 -

DEB_*_GNU_CPU (the CPU part of DEB_*_GNU_TYPE)

+

DEB_*_GNU_CPU (the CPU part of + DEB_*_GNU_TYPE)

DEB_*_GNU_SYSTEM (the System part of - DEB_*_GNU_TYPE)

+ DEB_*_GNU_TYPE)

-

- -

where * is either BUILD for specification of - the build machine or HOST for specification of the machine - we build for. + 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. + values; please refer to the documentation of + dpkg-architecture for details.

@@ -1982,8 +2169,9 @@ Though there is nothing stopping an author who is also the Debian maintainer from using it for all their changes, it will have to be renamed if the Debian and - upstream maintainers become different - people. + upstream maintainers become different people. In such a + case, however, it might be better to maintain the + package as a non-native package.

.

@@ -1996,14 +2184,14 @@

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

@@ -2028,6 +2216,16 @@ dpkg changelog format (though there is currently only one useful keyword, urgency). + +

+ Usual urgency values are low, medium, + high and critical. They have an + effect on how quickly a package will be considered for + inclusion into the testing distribution, and + give an indication of the importance of any fixes + included in this upload. +

+

@@ -2040,13 +2238,33 @@

- The maintainer name and email address need not - necessarily be those of the usual package maintainer. - They should be the details of the person doing - this version. The information here will be - copied to the .changes file, and then later used - to send an acknowledgement when the upload has been - installed. + If this upload resolves bugs recorded in the Bug Tracking + System (BTS), they may be automatically closed on the + inclusion of this package into the Debian archive by + including the string: closes: Bug#nnnnn + in the change details. + +

+ To be precise, the string should match the following + Perl regular expression: + +/closes:\s*(?:bug)?\#?\s?\d+(?:,\s*(?:bug)?\#?\s?\d+)*/i + + Then all of the bug numbers listed will be closed by the + archive maintenance script (katie), or in + the case of an NMU, marked as fixed. +

+ +

+ +

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

@@ -2058,7 +2276,7 @@

; it should include the time zone specified numerically, with the time zone name or abbreviation - optionally present as a comment. + optionally present as a comment in parentheses.

@@ -2089,21 +2307,22 @@

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

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

@@ -2142,11 +2361,12 @@

- dpkg-gencontrol adds an entry to this file - for the .deb file that will be created by - dpkg-deb from the control file that it - generates, so for most packages all that needs to be done - with this file is to delete it in clean. + 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.

@@ -2169,8 +2389,6 @@ packages, but only when extracting them.

- -

Hard links may be permitted at some point in the future, but would require a fair amount of @@ -2278,10 +2496,10 @@

- These scripts should be the files preinst, + 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 + files; if they are scripts (which is recommended), they must start with the usual #! convention. They should be readable and executable by anyone, and not world-writable.

@@ -2298,22 +2516,12 @@ well.

-

- It is necessary for the error recovery procedures that the - scripts be idempotent: i.e., invoking the same script several - times in the same situation should do no harm. If the first - call failed, or aborted half way through for some reason, - the second call should merely do the things that were left - undone the first time, if any, and exit with a success - status. -

-

When a package is upgraded a combination of the scripts from - the old and new packages is called in amongst the other - steps of the upgrade procedure. If your scripts are going - to be at all complicated you need to be aware of this, and - may need to check the arguments to your scripts. + 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.

@@ -2324,39 +2532,47 @@ 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, +

+ 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 on the PATH, - should thus be invoked without an absolute + other program that one would expect to be on the + PATH, should thus be invoked without an absolute pathname. Maintainer scripts should also not reset the - PATH, though they might choose to modify it by pre- - or appending package-specific directories. These + PATH, though they might choose to modify it by + prepending or appending package-specific directories. These considerations really apply to all shell scripts.

 + Maintainer scripts Idempotency

- It is very important to make maintainer scripts - idempotent. - + 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. +

- That means that if it runs successfully or fails - and then you call it again it doesn't bomb out, - but just ensures that everything is the way it - ought to be. + This is so that if an error occurs, the user interrupts + dpkg or some other unforeseen circumstance + happens you don't leave the user with a badly-broken + package when dpkg attempts to repeat the + action.

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

+ Controlling terminal for maintainer scripts @@ -2414,7 +2630,7 @@

old-postinst abort-upgrade - new version

+ new-version

conflictor's-postinst abort-remove @@ -2506,10 +2722,11 @@ 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 an error occurs 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. + 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. @@ -2518,20 +2735,20 @@

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

If the script runs but exits with a non-zero exit status, dpkg will attempt: - - new-prerm failed-upgrade old-version + +new-prerm failed-upgrade old-version Error unwind, for both the above cases: - - old-postinst abort-upgrade new-version + +old-postinst abort-upgrade new-version

@@ -2546,16 +2763,16 @@ If any packages depended on that conflicting package and --auto-deconfigure is specified, call, for each such package: - - deconfigured's-prerm deconfigure \ - in-favour package-being-installed version \ - removing conflicting-package version + +deconfigured's-prerm deconfigure \ + in-favour package-being-installed version \ + removing conflicting-package version Error unwind: - - deconfigured's-postinst abort-deconfigure \ - in-favour package-being-installed-but-failed version \ - removing conflicting-package version + +deconfigured's-postinst abort-deconfigure \ + in-favour package-being-installed-but-failed version \ + removing conflicting-package version The deconfigured packages are marked as requiring configuration, so that if @@ -2564,13 +2781,14 @@

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

@@ -2582,8 +2800,8 @@

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

@@ -2591,20 +2809,20 @@ Otherwise, if the package had some configuration files from a previous version installed (i.e., it is in the `configuration files only' state): - - new-preinst install old-version + +new-preinst install old-version

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

@@ -2617,19 +2835,22 @@ The new package's files are unpacked, overwriting any that may be on the system already, for example any from the old version of the same package or from - another package (backups of the old files are left - around, and if anything goes wrong the package + 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). + part of the error unwind.

It is an error for a package to contains files which are on the system in another package, unless Replaces is used (see ). - Currently the --force-overwrite flag is +

@@ -2644,7 +2865,7 @@

Packages which overwrite each other's files produce - behavior which though deterministic is hard for the + 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 @@ -2658,7 +2879,7 @@

- A directory will never be replaced by a symbolic links + 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 @@ -2670,18 +2891,18 @@

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

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

@@ -2712,13 +2933,13 @@

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, + For each such package

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

@@ -2759,12 +2980,17 @@

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. + `unpacked'. +

+ +

+ Here is another point of no return - if the + conflicting package's removal fails we do not unwind + the rest of the installation; the conflicting package + is left in a half-removed limbo.

+

If there was a conflicting package we go and do the @@ -2784,9 +3010,9 @@

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

@@ -2811,31 +3037,35 @@

- - prerm remove + +prerm remove

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

-

- postrm remove -

+

+ +postrm remove + +

-

All the maintainer scripts except the postrm are removed. +

+ All the maintainer scripts except the postrm + are removed.

If we aren't purging the package we stop here. Note - that packages which have no postrm and no conffiles - are automatically purged when removed, as there is no - difference except for the dpkg - status.

+ that packages which have no postrm and no + conffiles are automatically purged when + removed, as there is no difference except for the + dpkg status.

@@ -2844,22 +3074,25 @@ .dpkg-{old,new,tmp}, etc.) are removed.

 -

- postrm purge -

+

+ +postrm purge + +

The package's file list is removed.

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

+ removal. +

Declaring relationships between - packages + packages

Packages can declare in their control file that they have @@ -2871,9 +3104,10 @@

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

@@ -2884,7 +3118,7 @@

This is done using the Build-Depends, - Build-Depends-Indep, Build-Conflicts, and + Build-Depends-Indep, Build-Conflicts and Build-Conflicts-Indep control file fields.

@@ -2903,18 +3137,17 @@ 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 symbols | (pipe symbols). In such - a case, the presence of any one of the alternative packages - is installed, that part of the dependency is considered to - be satisfied. + 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 the fields except Provides may restrict their - applicability to particular versions of each named package. - This is done in parentheses after each individual package - name; the parentheses should contain a relation from the - list below followed by a version number, in the format + 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 .

@@ -2922,8 +3155,8 @@ The relations allowed are <<, <=, =, >= and >> for strictly earlier, earlier or equal, exactly equal, later or - equal and strictly later, respectively. The forms - < and > were used to mean + 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). @@ -2931,22 +3164,23 @@

Whitespace may appear at any point in the version - specification, and must appear where it's necessary to + specification subject to the rules in , and must appear where it's necessary to disambiguate; it is not otherwise significant. For consistency and in case of future changes to dpkg it is recommended that a single space be used after a version relationship and before a version - number; it is usual also to put a single space after each - comma, on either side of each vertical bar, and before each - open parenthesis. + number; it is also conventional to put a single space after + each comma, on either side of each vertical bar, and before + each open parenthesis.

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

@@ -2955,24 +3189,26 @@ (Build-Depends, Build-Depends-Indep, Build-Conflicts and Build-Conflicts-Indep) may be restricted to a certain set of architectures. This - is done in brackets after each individual package name and + 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. - An exclamation mark may be prepended to each name. 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. + Exclamation marks may be prepended to each of the names. + (It is not permitted for some names to be prepended with + exclamation marks and others not.) If the current Debian + host architecture is not in this list and there are no + exclamation marks in the list, or it is in the list with a + prepended exclamation mark, the package name and the + associated version specification are ignored completely for + the purposes of defining the relationships.

For example: - - Source: glibc - Build-Depends-Indep: texinfo - Build-Depends: kernel-headers-2.2.10 [!hurd-i386], - hurd-dev [hurd-i386], gnumach-dev [hurd-i386] + +Source: glibc +Build-Depends-Indep: texinfo +Build-Depends: kernel-headers-2.2.10 [!hurd-i386], +hurd-dev [hurd-i386], gnumach-dev [hurd-i386]

@@ -2990,17 +3226,22 @@

- All but Pre-Depends and Conflicts - (discussed below) take effect only when a package - is to be configured. They do not prevent a package being on - the system in an unconfigured state while its dependencies - are unsatisfied, and it is possible to replace a package - whose dependencies are satisfied and which is properly - installed with a different version whose dependencies are - not and cannot be satisfied; when this is done the depending - package will be left unconfigured (since attempts to - configure it will give errors) and will not function - properly. + A Depends field takes effect only when a + package is to be configured. It does not prevent a package + being on the system in an unconfigured state while its + dependencies are unsatisfied, and it is possible to replace + a package whose dependencies are satisfied and which is + properly installed with a different version whose + dependencies are not and cannot be satisfied; when this is + done the depending package will be left unconfigured (since + attempts to configure it will give errors) and will not + function properly. If it is necessary, a + Pre-Depends field can be used, which has a partial + effect even when a package is being unpacked, as explained + in detail below. (The other three dependency fields, + Recommends, Suggests and + Enhances, are only used by the various front-ends + to dpkg such as dselect.)

@@ -3012,20 +3253,37 @@

- Thus Depends allows package maintainers to impose - an order in which packages should be configured. + 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. +

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

+ 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 @@ -3070,35 +3328,43 @@ also forces dpkg to complete installation of the packages named before even starting the installation of the package which declares the - Pre-dependency. + pre-dependency, as follows:

- Pre-Depends should be used sparingly, - preferably only by packages whose premature upgrade or - installation would hamper the ability of the system to - continue with any upgrade that might be in progress. + When 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 it is being configured, a - Pre-Dependency will be considered satisfied - only if the depending package has been correctly - configured, just as if an ordinary Depends - had been used. + 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.

- However, when a package declaring a Pre-dependency is - being unpacked the predependency can be satisfied even - if the depended-on package(s) are only unpacked or - half-configured, provided that they have been - configured correctly at some point in the past (and - not removed or partially removed since). In this case - both the previously-configured and currently unpacked - or half-configured versions must satisfy any version - clause in the Pre-Depends field. + 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.

@@ -3116,30 +3382,30 @@

- Alternative binary packages - - Conflicts and Replaces - + Conflicting binary packages - + Conflicts

When one binary package declares a conflict with another - dpkg will refuse to allow them to be installed - on the system at the same time. + 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 () the one on the system, or - the one on the system is marked as deselected, or both + replacing (see ) 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 specifically doesn't work when the installed - package is Essential, but the new package is not. + 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 @@ -3153,7 +3419,7 @@ prevent their installation, and allows a package to conflict with others providing a replacement for it. You use this feature when you want the package in question to be the only - package providing something. + package providing some feature.

@@ -3171,14 +3437,15 @@

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

- A virtual package is one which appears in the + 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 @@ -3191,17 +3458,19 @@ caused) by either the real package or any of the virtual packages which provide it. This is so that, for example, supposing we have - - Package: vm - Depends: emacs + +Package: foo +Depends: bar + + and someone else releases an enhanced version of the + bar package (for example, a non-US variant), they + can say: + +Package: bar-plus +Provides: bar - and someone else releases an xemacs package they can say - - Package: xemacs - Provides: emacs - and all will work in the interim (until a purely - virtual package name is decided on and the emacs - and vm packages are changed to use it). + and the bar-plus package will now also satisfy the + dependency for the foo package.

@@ -3226,87 +3495,101 @@

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

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

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

-

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

- - Overwriting files in other packages - + 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, though currently the - --force-overwrite flag is enabled by default, - downgrading the error to a warning, + another package.

- If the overwriting package declares that it replaces the - one containing the file being overwritten then - dpkg will proceed, and replace the file from - the old package with that from the new. The file will no - longer be listed as `owned' by the old package. + 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 + contains, it is considered to have `disappeared'. It will be marked as not wanted on the system (selected for - removal) and not installed. Any conffiles details noted - in the package will be ignored, as they will have been - taken over by the replacing package(s). The package's - postrm script will be run to allow the - package to do any final cleanup required. See . + removal) and not installed. Any conffiles + 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 .

- In the future dpkg will discard files which - would overwrite those from an already installed package - which declares that it replaces the package being - installed. This is so that you can install an older - version of a package without problems. + If an installed package, foo say, declares that + it replaces another, bar, and an attempt is made + to install bar, dpkg will discard + files in the bar package which would overwrite + those already present in foo. This is so that + you can install an older version of a package without + problems.

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

+ For this usage of Replaces, virtual packages (see + ) 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. +

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

Secondly, Replaces allows the packaging system to resolve which package should be removed when there is a conflict - see . This usage only takes effect when the two packages do conflict, - so that the two effects do not interfere with each other. + 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. @@ -3317,21 +3600,22 @@

A source package may declare a dependency or a conflict on a - binary package. This is done with the control file fields - Build-Depends, Build-Depends-Indep, - Build-Conflicts, and - Build-Conflicts-Indep. Their semantics are that - the dependencies and conflicts they define must be satisfied - (as defined earlier for binary packages), when one of the - targets in debian/rules that the particular field - applies to is invoked. + binary package, indicating which packages are required to be + present on the system in order to build the binary packages + from the source package. This is done with the control file + fields Build-Depends, Build-Depends-Indep, + Build-Conflicts and Build-Conflicts-Indep. + The dependencies and conflicts they define must be satisfied + (as defined earlier for binary packages) in order to invoke + the targets in debian/rules, as follows: Build-Depends, Build-Conflicts

The Build-Depends and - Build-Conflicts fields apply to the targets + Build-Conflicts fields must be satisfied when + any of the following targets is invoked: build, binary, binary-arch and binary-indep.

@@ -3340,8 +3624,9 @@

The Build-Depends-Indep and - Build-Conflicts-Indep fields apply to the - targets binary and binary-indep. + Build-Conflicts-Indep fields must be + satisfied when any of the following targets is + invoked: binary and binary-indep.

@@ -3356,393 +3641,516 @@

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

- -

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

- -

- The easy method is to ship a best-effort configuration in the - package, and use dpkg's conffile mechanism to - handle updates. If the user is unlikely to want to edit the - file, but you need them to be able to without losing their - changes, and a new package with a changed version of the file - is only released infrequently, this is a good approach. + This chapter has been superseded by .

-

- The hard method is to build the configuration file from - scratch in the postinst script, and to take the - responsibility for fixing any mistakes made in earlier - versions of the package automatically. This will be - appropriate if the file is likely to need to be different on - each system. -

- - Shared libraries - + Shared libraries

Packages containing shared libraries must be constructed with a little care to make sure that the shared library is always available. This is especially important for packages whose - shared libraries are vitally important, such as the libc. + shared libraries are vitally important, such as the C library + (currently libc6).

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

- Secondly, your package should include the symlink that + Secondly, the package should include the symbolic link that ldconfig would create for the shared libraries. - For example, the libgdbm1 package should include - a symlink from /usr/lib/libgdbm.so.1 to - libgdbm.so.1.7.3. This is needed so that - ld.so can find the library in between the time - dpkg installs it and ldconfig is run - in the postinst script. Furthermore, older - versions of the package management system required the library - must be placed before the symlink pointing to it in the - .deb file. This is so that by the time - dpkg comes to install the symlink (overwriting - the previous symlink pointing at an older version of the - library) the new shared library is already in place. - Unfortunately, this was not not always possible, since it - highly depends on the behavior of the file system. Some - file systems (such as reiserfs) will reorder the files so it - doesn't matter in what order you create them. Starting with - release 1.7.0 dpkg will reorder the - files itself when building a package. + For example, the libgdbmg1 package should include + a symbolic link from /usr/lib/libgdbm.so.1 to + libgdbm.so.1.7.3. This is needed so that the dynamic + linker (for example ld.so or + ld-linux.so.*) can find the library between the + time that dpkg installs it and the time that + ldconfig is run in the postinst + script. + +

+ The package management system requires the library to be + placed before the symbolic link pointing to it in the + .deb file. This is so that when + dpkg comes to install the symlink + (overwriting the previous symlink pointing at an older + version of the library), the new shared library is already + in place. In the past, this was achieved by creating the + library in the temporary packaging directory before + creating the symlink. Unfortunately, this was not always + effective, since the building of the tar file in the + .deb depended on the behavior of the underlying + file system. Some file systems (such as reiserfs) reorder + the files so that the order of creation is forgotten. + Starting with release 1.7.0, dpkg + will reorder the files itself as necessary when building a + package. Thus it is no longer important to concern + oneself with the order of file creation. +

+

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

- Any package installing shared libraries in a directory that's listed - in /etc/ld.so.conf or in one of the default library - directories of ld.so (currently, these are /usr/lib - and /lib) must call ldconfig in its postinst - script if and only if the first argument is `configure'. However, it - is important not to call ldconfig in the postrm or preinst - scripts in the case where the package is being upgraded (see ), as ldconfig will see the temporary names - that dpkg uses for the files while it is + 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 + +

+ These are currently + +

/usr/X11R6/lib/Xaw3d

+

/usr/local/lib

 +

/usr/lib/libc5-compat

 +

/lib/libc5-compat

 +

/usr/X11R6/lib

 + +

+ + must call ldconfig in its postinst + script if and only if the first argument is configure + and should call it in the postrm script if the + first argument is remove. +

+ +

+ However, postrm and preinst scripts + must not call ldconfig in the case where + the package is being upgraded (see for + details), as ldconfig will see the temporary + names that dpkg uses for the files while it is installing them and will make the shared library links point to them, just before dpkg continues the - installation and removes the links! + installation and renames the temporary files!

- The shlibs File Format - + + Handling shared library dependencies - the + shlibs system + +

+ If a package contains a binary or library which links to a + shared library, we must ensure that when the package is + installed on the system, all of the libraries needed are + also installed. This requirement led to the creation of the + shlibs system, which is very simple in its design: + any package which provides a shared library also + provides information on the package dependencies required to + ensure the presence of this library, and any package which + uses a shared library uses this information to + determine the dependencies it requires. The files which + contain the mapping from shared libraries to the necessary + dependency information are called shlibs files. +

+ +

+ Thus, when a package is built which contains any shared + libraries, it must provide a shlibs file for other + packages to use, and when a package is built which contains + any shared libraries or compiled binaries, it must run + dpkg-shlibdeps on these to determine the + libraries used and hence the dependencies needed by this + package. + +

+ In the past, the shared libraries linked to were + determined by calling ldd, but now + objdump 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. +

-

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

+

+ 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 needs to depend on + the libraries it directly uses, and the dependencies for + those libraries should automatically pull in the other + libraries. +

-

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

+

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

-

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

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

+

- version-or-soname is the soname of the library - - i.e., the thing that must exactly match for the library to be - recognized by ld.so. Usually this is the major - version number of the library. + 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.

+ -

- dependencies has the same syntax as a dependency - field in a binary package control file. It should give - details of which package(s) are required to satisfy a binary - built against the version of the library contained in the - package. See . -

+ The shlibs files present on the system +

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

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

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

- The debian/shlibs file provides a way of checking - for shared library dependencies on packaged binaries. - They are intended to be used by package maintainers to - make their lives easier. -

- -

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

/etc/dpkg/shlibs.default

-

/etc/dpkg/shlibs.override

 -

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

 -

debian/shlibs.local

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

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

- dpkg-shlibdeps - determines the shared libraries directly - + + +

debian/shlibs.local

- It used to do this by calling ldd, but it - now calls objdump to to this. This - requires a couple of changes in the way that packages - are built. + This lists overrides for this package. Its use is + described below (see ).

+ + + +

/etc/dpkg/shlibs.override

- A binary foo directly uses a library - libbar if it is linked with that - library. Other libraries that are needed by - libbar are linked indirectly to foo, - and the dynamic linker will load them automatically - when it loads libbar. Runningldd - lists all of the libraries used, both directly and - indirectly; but objdump only lists the - directly linked libraries. A package only needs to - depend on the libraries it is directly linked to, - since the dependencies for those libraries should - automatically pull in the other libraries. + This lists global overrides. This list is normally + empty. It is maintained by the local system + administrator.

+ + + +

DEBIAN/shlibs files in the `build directory'

- This change does mean a change in the way packages are - build though: currently dpkg-shlibdeps is - only run on binaries. But since we will now rely on the - libraries depending on the libraries they themselves - need, the packages containing those libraries will - need to run dpkg-shlibdeps on the - libraries. + 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. + +

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

+

+ + + +

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

- A good example where this would help us is the current - mess with multiple version of the mesa - library. With the ldd-based system, every - package that uses mesa needs to add a - dependency on svgalib|svgalib-dummy in order - to handle the glide mesa variant. With an - objdump-based system this isn't necessary - anymore and would have saved everyone a lot of work. + 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

- Another example: we could update libimlib - with a new version that supports a new graphics format - called dgf. If we use 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 wouldn't - need to be updated. + 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.

- - used by the compiled binaries and libraries passed through - on its command line. -

+ + +

+ -

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

the package containing the library, and

-

the library version number,

 - - and it scans the following files in this order: - -

debian/shlibs.local

 -

/etc/dpkg/shlibs.override

 -

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

 -

/etc/dpkg/shlibs.default

 - -

- + + How to use dpkg-shlibdeps and the + shlibs files - Who maintains the various - 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. + +

+ If you are using debhelper, the + dh_shlibdeps program will do this work for + you. It will also correctly handle multi-binary + packages. +

+ +

-

- - -

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

- - -

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

- - -

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

- - -

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

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

- +

+ This command puts the dependency information into the + debian/substvars file, which is then used by + dpkg-gencontrol. You will need to place a + ${shlib:Depends} variable in the Depends + field in the control file for this to work. +

- How to use dpkg-shlibdeps and - the shlibs files - +

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

+ +

+ If you have multiple binary packages, you will need to call + dpkg-shlibdeps on each one which contains + compiled libraries or binaries. In such a case, you will + need to use the -T option to the dpkg + utilities to specify a different substvars file. + For more details on this and other options, see . +

+ + + The shlibs File Format + + +

+ Each shlibs file has the same format. Lines + beginning with # are considered to be commments and + are ignored. Each line is of the form: + +library-name soname-version-number dependencies ... + +

- If your package doesn't provide a shared - library - +

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

+

+ library-name is the name of the shared library, + in this case libz. (This must match the name part + of the soname, see below.) +

+ +

+ soname-version-number 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 + name.so.major-version, in our + example, libz.so.1. +

- Put a call to dpkg-shlibdeps into your - debian/rules file. If your package contains - only binaries (e.g. no scripts) use: - - dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* + This can be determined using the command + +objdump -p /usr/lib/libz.so.1.1.3 | grep SONAME - If dpkg-shlibdeps doesn't complain, you're - done. If it does complain you might need to create your - own debian/shlibs.local file.

- +

+ + The version part is the part which comes after + .so., so in our case, it is 1. +

+ +

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

+ - If your package provides a shared library - + + Providing a shlibs file +

+ If your package provides a shared library, you should create + a shlibs file following the format described above. + It is usual to call this file debian/shlibs (but if + you have multiple binary packages, you might want to call it + debian/shlibs.package 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.package debian/package/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, +

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

- - + + since the debian/shlibs file itself is ignored by + dpkg-shlibdeps. +

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

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

+ -

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

+ + Writing the debian/shlibs.local file -

- Let's assume you are packaging a binary foo. Your - output in building the package might look like this. - - $ ldd foo - libbar.so.1 => /usr/X11R6/lib/libbar.so.1.0 (0x4001e000) - libX11.so.6 => /usr/X11R6/lib/libX11.so.6 (0x4002c000) - libc.so.6 => /lib/libc.so.6 (0x40114000) - /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000) - - And when you ran dpkg-shlibdeps - - $ dpkg-shlibdeps -O foo - dpkg-shlibdeps: warning: unable to find dependency information for shared library libbar - (soname 1, path /usr/X11R6/lib/libbar.so.1.0, dependency field Depends) - shlibs:Depends=libc6 (>= 2.2.1), xlibs (>= 4.0.1-11) - - The foo binary depends on the - libbar shared library, but no package seems - to provide a *.shlibs file in - /var/lib/dpkg/info/. Let's determine the package - responsible: -

+

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

-

- - $ dpkg -S /usr/X11R6/lib/libbar.so.1.0 - bar1: /usr/X11R6/lib/libbar.so.1.0 - $ dpkg -s bar1 | grep Version - Version: 1.0-1 - - This tells us that the bar1 package, version - 1.0-1 is the one we are using. Now we can create our own - debian/shlibs.local to temporarily fix the above - problem. Include the following line into your - debian/shlibs.local file. - - libbar 1 bar1 (>= 1.0-1) - - Now your package build should work. As soon as the - maintainer of libbar1 provides a - shlibs file, you can remove your - debian/shlibs.local file. -

- +

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

The Operating System - File system hierarchy @@ -3801,13 +4209,13 @@

For example, the emacs package will contain - - mkdir -p /usr/local/lib/emacs/site-lisp || true + +mkdir -p /usr/local/lib/emacs/site-lisp || true in the postinst script, and - - rmdir /usr/local/lib/emacs/site-lisp || true - rmdir /usr/local/lib/emacs || true + +rmdir /usr/local/lib/emacs/site-lisp || true +rmdir /usr/local/lib/emacs || true in the prerm script.

@@ -3829,8 +4237,27 @@ permissions 2775 (group-writable and set-group-id) and be owned by root.staff.

+ + The system-wide mail directory +

+ The system-wide mail directory is /var/mail. This + directory is part of the base system and should not owned + by any particular mail agents. The use of the old + location /var/spool/mail is deprecated, even + though the spool may still be physically located there. + To maintain partial upgrade compatibility for systems + which have /var/spool/mail as their physical mail + spool, packages using /var/mail must depend on + either libc6 (>= 2.1.3-13), or on + base-files (>= 2.2.0), or on later + versions of either one of these packages. +

+ + + + Users and groups @@ -3852,7 +4279,7 @@

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.

+ order, but the behavior should be configurable.

Packages other than base-passwd must not modify @@ -4011,7 +4438,7 @@

The two-digit number mm is used to decide which - order to start and stop things in--low-numbered links have + order to start and stop things in: low-numbered links have their scripts run first. For example, the K20 scripts will be executed before the K30 scripts. This is used when a certain service must be started before @@ -4021,9 +4448,9 @@ access lists. In this case, the script that starts bind would have a lower number than the script that starts inn so that it runs first: - - /etc/rc2.d/S17bind - /etc/rc2.d/S70inn + +/etc/rc2.d/S17bind +/etc/rc2.d/S70inn

@@ -4091,8 +4518,8 @@ the package is removed but not purged. Therefore, you should include a test statement at the top of the script, like this: - - test -f program-executed-later-in-script || exit 0 + +test -f program-executed-later-in-script || exit 0

@@ -4159,14 +4586,14 @@

To get the default behavior for your package, put in your postinst script - - update-rc.d package defaults >/dev/null + +update-rc.d package defaults >/dev/null and in your postrm - - if [ purge = "$1" ]; then - update-rc.d package remove >/dev/null - fi + +if [ purge = "$1" ]; then + update-rc.d package remove >/dev/null +fi

@@ -4214,10 +4641,10 @@ correctly in the maintainer scripts (see ). (This is important since we want to give the local system administrator the chance to adapt - the scripts to the local system--e.g., to disable a + the scripts to the local system, e.g., to disable a service without de-installing the package, or to specify some special command line options when starting a - service--while making sure her changes aren't lost during + service, while making sure her changes aren't lost during the next package upgrade.)

@@ -4240,55 +4667,55 @@

- - #!/bin/sh - # - # Original version by Robert Leslie - # <rob@mars.org>, edited by iwj and cs - - test -x /usr/sbin/named || exit 0 - - # Source defaults file. - PARAMS='' - if [ -f /etc/default/bind ]; then - . /etc/default/bind - fi - - - case "$1" in - start) - echo -n "Starting domain name service: named" - start-stop-daemon --start --quiet --exec /usr/sbin/named \ - -- $PARAMS - echo "." - ;; - stop) - echo -n "Stopping domain name service: named" - start-stop-daemon --stop --quiet \ - --pidfile /var/run/named.pid --exec /usr/sbin/named - echo "." - ;; - restart) - echo -n "Restarting domain name service: named" - start-stop-daemon --stop --quiet \ - --pidfile /var/run/named.pid --exec /usr/sbin/named - start-stop-daemon --start --verbose --exec /usr/sbin/named \ - -- $PARAMS - echo "." - ;; - force-reload|reload) - echo -n "Reloading configuration of domain name service: named" - start-stop-daemon --stop --signal 1 --quiet \ - --pidfile /var/run/named.pid --exec /usr/sbin/named - echo "." - ;; - *) - echo "Usage: /etc/init.d/bind {start|stop|restart|reload|force-reload}" >&2 - exit 1 - ;; - esac - - exit 0 + +#!/bin/sh +# +# Original version by Robert Leslie +# <rob@mars.org>, edited by iwj and cs + +test -x /usr/sbin/named || exit 0 + +# Source defaults file. +PARAMS='' +if [ -f /etc/default/bind ]; then + . /etc/default/bind +fi + + +case "$1" in +start) + echo -n "Starting domain name service: named" + start-stop-daemon --start --quiet --exec /usr/sbin/named \ + -- $PARAMS + echo "." + ;; +stop) + echo -n "Stopping domain name service: named" + start-stop-daemon --stop --quiet \ + --pidfile /var/run/named.pid --exec /usr/sbin/named + echo "." + ;; +restart) + echo -n "Restarting domain name service: named" + start-stop-daemon --stop --quiet \ + --pidfile /var/run/named.pid --exec /usr/sbin/named + start-stop-daemon --start --verbose --exec /usr/sbin/named \ + -- $PARAMS + echo "." + ;; +force-reload|reload) + echo -n "Reloading configuration of domain name service: named" + start-stop-daemon --stop --signal 1 --quiet \ + --pidfile /var/run/named.pid --exec /usr/sbin/named + echo "." + ;; +*) + echo "Usage: /etc/init.d/bind {start|stop|restart|reload|force-reload}" >&2 + exit 1 + ;; +esac + +exit 0

@@ -4298,10 +4725,10 @@ parameters used by the script.

- - # Specified parameters to pass to named. See named(8). - # You may uncomment the following line, and edit to taste. - #PARAMS="-u nobody" + +# Specified parameters to pass to named. See named(8). +# You may uncomment the following line, and edit to taste. +#PARAMS="-u nobody"

@@ -4314,15 +4741,15 @@ update-rc.d, namely an ordering number of 20 and having named running in all runlevels, it can say in its postinst: - - update-rc.d bind defaults >/dev/null + +update-rc.d bind defaults >/dev/null And in its postrm, to remove the links when the package is purged: - - if [ purge = "$1" ]; then - update-rc.d bind remove >/dev/null - fi + +if [ purge = "$1" ]; then + update-rc.d bind remove >/dev/null +fi

@@ -4338,10 +4765,10 @@ If a package wants to install a job that has to be executed via cron, it should place a file with the name of the package in one of the following directories: - - /etc/cron.daily - /etc/cron.weekly - /etc/cron.monthly + +/etc/cron.daily +/etc/cron.weekly +/etc/cron.monthly As these directory names imply, the files within them are executed on a daily, weekly, or monthly basis, @@ -4357,7 +4784,7 @@

If a certain job has to be executed more frequently than daily, the package should install a file - /etc/cron.d/package-name. This file uses + /etc/cron.d/package. This file uses the same syntax as /etc/crontab and is processed by cron automatically. The file must also be treated as a configuration file. (Note, that entries in the @@ -4418,14 +4845,17 @@ what he is doing (let him be polite :-) but don't mention ``him'' directly. For example, if you think of saying - - I'm starting network daemons: nfsd mountd. + +I'm starting network daemons: nfsd mountd. just say - - Starting network daemons: nfsd mountd. -

-

+ +Starting network daemons: nfsd mountd. + +

+ + +

The following formats should be used

@@ -4439,8 +4869,8 @@ Use this format if your script starts one or more daemons. The output should look like this (a single line, no leading spaces): - - Starting <description>: <daemon-1> <daemon-2> <...> <daemon-n>. + +Starting <description>: <daemon-1> ... <daemon-n>. The <description> should describe the subsystem the daemon or set of daemons are part of, while @@ -4450,25 +4880,25 @@

For example, the output of /etc/init.d/lpd would look like: - - Starting printer spooler: lpd. + +Starting printer spooler: lpd.

This can be achieved by saying - - echo -n "Starting printer spooler: lpd" - start-stop-daemon --start --quiet lpd - echo "." + +echo -n "Starting printer spooler: lpd" +start-stop-daemon --start --quiet lpd +echo "." in the script. If you have more than one daemon to start, you should do the following: - - echo -n "Starting remote file system services:" - echo -n " nfsd"; start-stop-daemon --start --quiet nfsd - echo -n " mountd"; start-stop-daemon --start --quiet mountd - echo -n " ugidd"; start-stop-daemon --start --quiet ugidd - echo "." + +echo -n "Starting remote file system services:" +echo -n " nfsd"; start-stop-daemon --start --quiet nfsd +echo -n " mountd"; start-stop-daemon --start --quiet mountd +echo -n " ugidd"; start-stop-daemon --start --quiet ugidd +echo "." This makes it possible for the user to see what takes so long and when the final daemon has been @@ -4476,8 +4906,9 @@ example above the system administrator can easily comment out a line if he don't wants to start a specific daemon, while the displayed message still - looks good.

- + looks good. +

+

when something needs to be configured.

@@ -4485,19 +4916,23 @@

If you have to set up different parameters of the system upon boot up, you should use this format: - - Setting <parameter> to `<value>'. -

+ +Setting <parameter> to `<value>'. + +

You can use the following echo statement to get the quotes right: - - echo "Setting DNS domainname to \`"value"'." -

+ +echo "Setting DNS domainname to \`"value"'." + +

Note that the left quotation mark (`) is different - from the right (').

 + from the right ('). +

+

when a daemon is stopped.

@@ -4509,8 +4944,8 @@

So stopping the printer daemon will like like this: - - Stopping printer spooler: lpd. + +Stopping printer spooler: lpd.

@@ -4522,18 +4957,20 @@ specific task. For example, setting the system's clock via `netdate' or killing all processes when the system comes down. Your message should like this: - - Doing something very useful...done. + +Doing something very useful...done. You should print the `done.' right after the job has been completed, so that the user gets informed why he has to wait. You can get this behavior by saying - - echo -n "Doing something very useful..." - do_something - echo "done." + +echo -n "Doing something very useful..." +do_something +echo "done." - in your script.

 + in your script. +

+

when the configuration is reloaded.

@@ -4541,9 +4978,11 @@

When a daemon is forced to reload its configuration files you should use the following format: - - Reloading <daemon's-name> configuration...done. -

+ +Reloading <daemon's-name> configuration...done. + +

+

when none of the above rules apply.

@@ -4552,9 +4991,12 @@ If you have to print a message that doesn't fit into the styles described above, you can use something appropriate, but please have a look at the overall - rules listed above.

 -

- + rules listed above. +

+ + +

+ Menus @@ -4562,7 +5004,7 @@

Menu entries should follow the current menu policy as defined in the file ftp.debian.org in - /debian/doc/package-developer/menu-policy.text.gz + /debian/doc/package-developer/menu-policy.txt.gz or your local mirror. In addition, it is included in the debian-policy package.

@@ -4598,7 +5040,7 @@ compose, edit or print MIME types should register themselves as such following the current MIME support policy as defined in the file found on ftp.debian.org in - /debian/doc/package-developer/mime-policy.text.gz + /debian/doc/package-developer/mime-policy.txt.gz or your local mirror. In addition, it is included in the debian-policy package.

@@ -4650,7 +5092,7 @@ should be set up to achieve this:

- +

`<--' generates KB_Backspace in X.

@@ -4703,7 +5145,7 @@ This will solve the problem except for:

- +

Some terminals have a <-- key that cannot be made to produce anything except ^H. On @@ -4766,11 +5208,11 @@

Here is an example of a wrapper script for this purpose: - - #!/bin/sh - BAR=${BAR:-/var/lib/fubar} - export BAR - exec /usr/lib/foo/foo "$@" + +#!/bin/sh +BAR=${BAR:-/var/lib/fubar} +export BAR +exec /usr/lib/foo/foo "$@"

@@ -4801,11 +5243,11 @@

Generally the following compilation parameters should be used: - - CC = gcc - CFLAGS = -O2 -Wall # sane warning options vary between programs - LDFLAGS = # none - install -s # (or use strip on the files in debian/tmp) + +CC = gcc +CFLAGS = -O2 -Wall # sane warning options vary between programs +LDFLAGS = # none +install -s # (or use strip on the files in debian/tmp)

@@ -4850,7 +5292,7 @@ compiling that package.

Now this has several added benefits: - +

It is actually easier to build debugging bins and @@ -4872,20 +5314,20 @@ - - CFLAGS = -O2 -Wall - 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 (,$(findstring debug,$(DEB_BUILD_OPTIONS))) - CFLAGS += -g - endif - ifeq (,$(findstring nostrip,$(DEB_BUILD_OPTIONS))) - INSTALL_PROGRAM += -s - endif + +CFLAGS = -O2 -Wall +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 (,$(findstring debug,$(DEB_BUILD_OPTIONS))) +CFLAGS += -g +endif +ifeq (,$(findstring nostrip,$(DEB_BUILD_OPTIONS))) +INSTALL_PROGRAM += -s +endif Please note that the above example is merely informative, @@ -4903,7 +5345,7 @@ here. Don't use flags for the sake of it; only use them if there is good reason to do so. Feel free to override the upstream author's ideas about which compilation - options are best--they are often inappropriate for our + options are best: they are often inappropriate for our environment.

 @@ -4925,14 +5367,15 @@

Note that all installed shared libraries should be stripped with - - strip --strip-unneeded <your-lib> + +strip --strip-unneeded <your-lib> - (The option `--strip-unneeded' makes strip remove - only the symbols which aren't needed for relocation - processing.) Shared libraries can function perfectly well - when stripped, since the symbols for dynamic linking are - in a separate part of the ELF object file.

+ (The option --strip-unneeded makes + strip remove only the symbols which aren't + needed for relocation processing.) Shared libraries can + function perfectly well when stripped, since the symbols for + dynamic linking are in a separate part of the ELF object + file.

Note that under some circumstances it may be useful to @@ -4999,7 +5442,7 @@ libraries you need to create two packages: librarynamesoname (soname is the shared object name of the shared - library--it's the thing that has to match exactly between + library: 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; usually the soname is the major number of the library) and @@ -5034,7 +5477,7 @@ without getting filename clashes. Instead, either create a third package for the runtime binaries (this package might typically be named - libraryname-runtime--note the absence + libraryname-runtime; note the absence of the soname in the package name) or if the development package is small include them in there.

@@ -5048,10 +5491,11 @@

You should follow the directions in the Debian Packaging - Manual for putting the shared library in its package, - and you must include a shlibs control area - file with details of the dependencies for packages which - use the library.

+ Manual (or other documentation of the Debian + packaging tools) for putting the shared library in its + package, and you must include a shlibs control area + file with details of the dependencies for packages which use + the library.

Shared libraries should not be installed @@ -5173,11 +5617,11 @@

For example, in your Makefile or debian/rules, do things like: - - ln -fs gcc $(prefix)/bin/cc - ln -fs gcc debian/tmp/usr/bin/cc - ln -fs ../sbin/sendmail $(prefix)/bin/runq - ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq + +ln -fs gcc $(prefix)/bin/cc +ln -fs gcc debian/tmp/usr/bin/cc +ln -fs ../sbin/sendmail $(prefix)/bin/runq +ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq

@@ -5275,7 +5719,7 @@

Configuration file handling must conform to the following behavior: - +

local changes must be preserved during a package upgrade

@@ -5313,8 +5757,9 @@ upgrading conffiles.

+

-

+

The other way to do it is via the maintainer scripts. In this case, the configuration file must not be listed as a conffile and must not be part of the package @@ -5338,17 +5783,20 @@ have to do any configuration other than that done (semi-)automatically by the postinst script.

-

- A common practice is to create a script called - package-configure and have the - package's postinst call it if and only if the - configuration file does not already exist. In certain - cases it is useful for there to be an example or template - file which the maintainer scripts use. Such files should - be in /usr/share/doc if they are examples or - /usr/lib if they are templates, and should be - perfectly ordinary dpkg-handled files - (not conffiles).

+

+ A common practice is to create a script called + package-configure and have the + package's postinst call it if and only if the + configuration file does not already exist. In certain + cases it is useful for there to be an example or template + file which the maintainer scripts use. Such files should + be in /usr/share/<package> or + /usr/lib/<package> with a symbolic link + from /usr/share/doc/<package>/examples + if they are examples, and should be + perfectly ordinary dpkg-handled files + (not conffiles). +

These two styles of configuration file handling must @@ -5497,15 +5945,15 @@ logrotate. Here is a good example for a logrotate config file (for more information see ): - - /var/log/foo/* { - rotate 12 - weekly - compress - postrotate - /etc/init.d/foo force-reload - endscript - } + +/var/log/foo/* { +rotate 12 +weekly +compress +postrotate +/etc/init.d/foo force-reload +endscript +} Which rotates all files under `/var/log/foo', saves 12 compressed generations, and sends a HUP signal at the end of @@ -5540,7 +5988,7 @@

Directories should be mode 755 or (for group-writability) mode 2775. The ownership of the directory should be - consistent with its mode--if a directory is mode 2775, it + consistent with its mode: if a directory is mode 2775, it should be owned by the group that needs write access to it.

@@ -5550,7 +5998,7 @@ They should not be made unreadable (modes like 4711 or 2711 or even 4111); doing so achieves no extra security, because anyone can find the binary in the freely available - Debian package--it is merely inconvenient. For the same + Debian package, it is merely inconvenient. For the same reason you should not restrict read or execute permissions on non-set-id executables.

@@ -5620,7 +6068,7 @@ - + Customized programs @@ -5629,8 +6077,8 @@

If a program needs to specify an architecture specification string in some place, the following format should be used: - - <arch>-<os> + +<arch>-<os> where `<arch>' is one of the following: i386, alpha, arm, m68k, powerpc, sparc and `<os>' is one of: linux, gnu. Use @@ -5768,14 +6216,15 @@

Cgi-bin executable files are installed in the directory - - /usr/lib/cgi-bin/<cgi-bin-name> + +/usr/lib/cgi-bin/<cgi-bin-name> and should be referred to as - - http://localhost/cgi-bin/<cgi-bin-name> -

- + +http://localhost/cgi-bin/<cgi-bin-name> + +

+

Access to html documents

@@ -5786,10 +6235,11 @@ /usr/doc/package for backward compatibility, see and can be referred to as - - http://localhost/doc/<package>/<filename> -

- + +http://localhost/doc/<package>/<filename> + +

+

Web Document Root

@@ -5799,8 +6249,8 @@ /usr/share/doc/<package> directory for documents and register the Web Application via the menu package. If access to the web-root is unavoidable then use - - /var/www + +/var/www as the Document Root. This might be just a symbolic link to the location where the sysadmin has @@ -5810,7 +6260,7 @@

- + Mail transport, delivery and user agents

@@ -5822,10 +6272,14 @@ serious brain damage!

- The mail spool is /var/spool/mail and the interface + The mail spool is /var/mail and the interface to send a mail message is /usr/sbin/sendmail (as - per the FHS). The mail spool is part of the base system - and not part of the MTA package.

+ per the FHS). On older systems, the mail spool may be + physically located in /var/spool/mail, but all access to the + mail spool should be via the /var/mail symlink. The mail + spool is part of the base system and not part of the MTA + package. +

All Debian MUAs, MTAs, MDAs and other mailbox accessing @@ -5863,7 +6317,7 @@

/etc/aliases is the source file for the system mail - aliases (e.g., postmaster, usenet, etc.)--it is the one + aliases (e.g., postmaster, usenet, etc.), it is the one which the sysadmin and postinst scripts may edit. After /etc/aliases is edited the program or human editing it must call newaliases. All MTA @@ -5902,16 +6356,17 @@ configuration. The prompt should make it clear that the name will not just be used by that package. For example, in this situation the INN package says: - - Please enter the `mail name' of your system. This is the - hostname portion of the address to be shown on outgoing - news and mail messages. The default is - syshostname, your system's host name. Mail - name [`syshostname']: + +Please enter the `mail name' of your system. This is the +hostname portion of the address to be shown on outgoing +news and mail messages. The default is +syshostname, your system's host name. Mail +name [`syshostname']: where syshostname is the output of hostname - --fqdn.

 - + --fqdn. +

+ News system configuration @@ -5991,7 +6446,7 @@ x-window-manager. They should also register themselves as an alternative for /usr/bin/x-window-manager, with a priority calculated as follows: - + Start with a priority of 20. If the window manager supports the Debian menu system, add 20 points if this support is available in the @@ -6028,10 +6483,10 @@ BDF fonts should be converted to PCF fonts with the bdftopcf utility (available in the - xutils package, gzipped, and + xutils package), gzipped, and placed in a directory that corresponds to their resolution: - + 100 dpi fonts should be placed in /usr/X11R6/lib/X11/fonts/100dpi/. @@ -6088,7 +6543,7 @@ Font packages must not provide the files fonts.dir, fonts.alias, or fonts.scale in a font directory. - + fonts.dir files must not be provided at all. @@ -6153,7 +6608,7 @@ Application defaults files must be installed in the directory /etc/X11/app-defaults/ (use of a localized subdirectory of /etc/X11/ as described in - the X Toolkit Intrinsics - C Language Interface + the X Toolkit Intrinsics - C Language Interface manual is also permitted). They must be registered as conffiles or handled as configuration files. For programs that are not linked against the X Toolkit (Xt) @@ -6172,36 +6627,37 @@

- Packages using the X Window System should abide by the FHS - standard whenever possible; they should install binaries, - libraries, manual pages, and other files in FHS-mandated - locations wherever possible. This means that files must - not be installed into /usr/X11R6/bin/, - /usr/X11R6/lib/, or /usr/X11R6/man/ unless - this is necessary for the package to operate properly. - Configuration files for window managers and display managers - should be placed in a subdirectory of /etc/X11/ - corresponding to the package name due to these programs' - tight integration with the mechanisms of the X Window - System. Application-level programs should use the - /etc/ directory unless otherwise mandated by - policy. The installation of files into subdirectories of - /usr/X11R6/include/X11/ and - /usr/X11R6/lib/X11/ is permitted but discouraged; - package maintainers should determine if subdirectories of - /usr/lib/ and /usr/share/ can be used - instead (symlinks from the X11R6 directories to - FHS-compliant locations is encouraged if the program is not - easily configured to look elsewhere for its files). - Packages must not provide -- or install files into -- the - directories /usr/bin/X11/, - /usr/include/X11/, or /usr/lib/X11/. - Files within a package should, however, make reference to - these directories, rather than their X11R6-named - counterparts /usr/X11R6/bin/, - /usr/X11R6/include/X11/, and - /usr/X11R6/lib/X11/, if the resources being - referred to have not been moved to FHS-compliant locations. + Packages using the X Window System should abide by the + FHS standard whenever possible; they should install + binaries, libraries, manual pages, and other files in + FHS-mandated locations wherever possible. This means that + files must not be installed into /usr/X11R6/bin/, + /usr/X11R6/lib/, or /usr/X11R6/man/ + unless this is necessary for the package to operate + properly. Configuration files for window managers and + display managers should be placed in a subdirectory of + /etc/X11/ corresponding to the package name due + to these programs' tight integration with the mechanisms + of the X Window System. Application-level programs should + use the /etc/ directory unless otherwise mandated + by policy. The installation of files into subdirectories + of /usr/X11R6/include/X11/ and + /usr/X11R6/lib/X11/ is permitted but discouraged; + package maintainers should determine if subdirectories of + /usr/lib/ and /usr/share/ can be used + instead (symlinks from the X11R6 directories to + FHS-compliant locations is encouraged if the program is + not easily configured to look elsewhere for its files). + Packages must not provide or install files into the + directories /usr/bin/X11/, + /usr/include/X11/, or /usr/lib/X11/. + Files within a package should, however, make reference to + these directories, rather than their X11R6-named + counterparts /usr/X11R6/bin/, + /usr/X11R6/include/X11/, and + /usr/X11R6/lib/X11/, if the resources being + referred to have not been moved to FHS-compliant + locations.

@@ -6228,6 +6684,17 @@

+ + Perl programs and modules +

+ Perl programs and modules should follow the current Perl + policy as defined in the file found on + ftp.debian.org in + /debian/doc/package-developer/perl-policy.txt.gz + or your local mirror. In addition, it is included in the + debian-policy package. +

+ Emacs lisp programs @@ -6313,9 +6780,9 @@ to the manual page may be provided. This symbolic link can be created from debian/rules like this: - - ln -s ../man7/undocumented.7.gz \ - debian/tmp/usr/share/man/man[1-9]/the_requested_manpage.[1-9].gz + +ln -s ../man7/undocumented.7.gz \ +debian/tmp/usr/share/man/man[1-9]/the_requested_manpage.[1-9].gz This manpage claims that the lack of a manpage has been reported as a bug, so you may only do this if it really has @@ -6327,7 +6794,7 @@ upstream authors, and mark the bug as forwarded in the Debian bug tracking system. Even though the GNU Project do not in general consider the lack of a manpage to be a bug, - we do--if they tell you that they don't consider it a bug + we do; if they tell you that they don't consider it a bug you should leave the bug in our bug tracking system open anyway.

@@ -6340,7 +6807,7 @@ is better to use a symbolic link than the .so feature, but there is no need to fiddle with the relevant parts of the upstream source to change from .so to - symlinks--don't do it unless it's easy. You should not create hard + symlinks: don't do it unless it's easy. You should not create hard links in the manual page directories, nor put absolute filenames in .so directives. The filename in a .so in a manpage should be relative to the @@ -6359,9 +6826,9 @@ Your package should call install-info to update the Info dir file, in its post-installation script: - - install-info --quiet --section Development Development \ - /usr/share/info/foobar.info + +install-info --quiet --section Development Development \ +/usr/share/info/foobar.info

@@ -6377,8 +6844,8 @@

You should remove the entries in the pre-removal script: - - install-info --quiet --remove /usr/share/info/foobar.info + +install-info --quiet --remove /usr/share/info/foobar.info

@@ -6444,20 +6911,20 @@ with dpkg. One reasonable way to accomplish this is to put the following in the package's postinst: - - if [ "$1" = "configure" ]; then - if [ -d /usr/doc -a ! -e /usr/doc/#PACKAGE# \ - -a -d /usr/share/doc/#PACKAGE# ]; then - ln -sf ../share/doc/#PACKAGE# /usr/doc/#PACKAGE# - fi - fi + +if [ "$1" = "configure" ]; then + if [ -d /usr/doc -a ! -e /usr/doc/#PACKAGE# \ + -a -d /usr/share/doc/#PACKAGE# ]; then + ln -sf ../share/doc/#PACKAGE# /usr/doc/#PACKAGE# + fi +fi And the following in the package's prerm: - - if [ \( "$1" = "upgrade" -o "$1" = "remove" \) \ - -a -L /usr/doc/#PACKAGE# ]; then - rm -f /usr/doc/#PACKAGE# - fi + +if [ \( "$1" = "upgrade" -o "$1" = "remove" \) \ + -a -L /usr/doc/#PACKAGE# ]; then + rm -f /usr/doc/#PACKAGE# +fi

@@ -6494,7 +6961,7 @@

Every package must be accompanied by a verbatim copy of its copyright and distribution license in the file - /usr/share/doc/<package-name>/copyright. This file must + /usr/share/doc/<package>/copyright. This file must neither be compressed nor be a symbolic link.

@@ -6512,7 +6979,7 @@

- /usr/share/doc/<package-name> may be a symbolic link to a + /usr/share/doc/<package> may be a symbolic link to a directory in /usr/share/doc only if two packages both come from the same source and the first package has a "Depends" relationship on the second. These rules are important @@ -6562,7 +7029,7 @@ Any examples (configurations, source files, whatever), should be installed in a directory /usr/share/doc/package/examples. These - files should not be referenced by any program--they're there + files should not be referenced by any program: they're there for the benefit of the system administrator and users, as documentation only. Architecture-specific example files should be installed in a directory