X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=policy.sgml;h=733e1f0c6f39c9c025a9f5cf8f1e10b75d1e2816;hb=8005797abdddb3b4762ed13d88ef22bc15ad8c75;hp=583cac08f628e4d0c8ab04b6015a5d4706d844cd;hpb=b47647cd32ffd4ac29328f963677e0279e272cbb;p=debian%2Fdebian-policy.git diff --git a/policy.sgml b/policy.sgml index 583cac0..733e1f0 100644 --- a/policy.sgml +++ b/policy.sgml @@ -4,41 +4,11 @@ %versiondata; ]> - Debian Policy Manual - - Ian Jackson - ijackson@gnu.ai.mit.edu - - - Christian Schwarz - schwarz@debian.org - - - revised: David A. Morris - bweaver@debian.org - - - The Debian Policy mailing List - debian-policy@lists.debian.org - + The Debian Policy Mailing List version &version;, &date; @@ -47,23 +17,11 @@ contents of the Debian archive and several design issues of the operating system, as well as technical requirements that each package must satisfy to be included in the distribution. - The policy package itself is maintained by a group of - maintainers that have no editorial powers. The current list - of maintainers is: - - -

Julian Gilbey jdg@debian.org

- - -

Manoj Srivastava srivasta@debian.org

- - - - Copyright ©1996,1997,1998 Ian Jackson + Copyright © 1996,1997,1998 Ian Jackson and Christian Schwarz.

@@ -86,14 +44,14 @@ /usr/share/common-licenses/GPL in the Debian GNU/Linux distribution or on the World Wide Web at . You can also + 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.

- + About this manual @@ -108,7 +66,6 @@ distribution.

-

This manual also describes Debian policy as it relates to creating Debian packages. It is not a tutorial on how to build @@ -116,13 +73,11 @@ the behavior of the packaging system. Instead, this manual attempts to define the interface to the package management system that the developers have to be conversant with. -

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 @@ -133,22 +88,18 @@ compatibility with these interface definitions. (Control file and changelog file formats are examples.) -

Chosen Convention -

If there are a number of technically viable choices that can be made, but one needs to select one of these options for inter-operability. The version number format is one example. -

Please note that these are not mutually exclusive; selected conventions often become parts of standard interfaces. -

@@ -157,9 +108,14 @@ merely informative, and are not part of Debian policy itself.

+

+ The appendices to this manual are not necessarily normative, + either. Please see for more information. +

- In this manual, the words must, should and + In the normative part of this manual, + the words must, should and may, and the adjectives required, recommended and optional, are used to distinguish the significance of the various guidelines in @@ -173,6 +129,7 @@ may (or optional) are truly optional and adherence is left to the maintainer's discretion.

+

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

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

+ items). + + 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 @@ -192,37 +151,63 @@ only.

+ New versions of this document +

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

+ This manual is distributed via the Debian package + . +

- In addition, this manual is distributed via the Debian package - debian-policy. + The current version of this document is also available from + the Debian web mirrors at + . + Also available from the same directory are several other + formats: policy.html.tar.gz, policy.pdf.gz + and policy.ps.gz.

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

- - Feedback + + + Authors and Maintainers

- As the Debian GNU/Linux system is continuously evolving this - manual does so too. -

+ Originally called "Debian GNU/Linux Policy Manual", this + manual was initially written in 1996 by Ian Jackson. + It was revised on November 27th, 1996 by David A. Morris. + Christian Schwarz added new sections on March 15th, 1997, + and reworked/restructured it in April-July 1997. + Christoph Lameter contributed the "Web Standard". + Julian Gilbey largely restructured it in 2001. +

+ +

+ Since September 1998, the responsibility for the contents of + this document lies on the . Proposals + are discussed there and inserted into policy after a certain + consensus is established. + + The actual editing is done by a group of maintainers that have + no editorial powers. These are the current maintainers: + + + Julian Gilbey + Branden Robinson + Josip Rodin + Manoj Srivastava + +

+

While the authors of this document have tried hard to avoid typos and other errors, these do still occur. If you discover @@ -232,11 +217,58 @@ debian-policy@lists.debian.org, or submit a bug report against the debian-policy package.

+ +

+ Please do not try to reach the individual authors or maintainers + of the Policy Manual regarding changes to the Policy. +

+ + + + Related documents + +

+ There are several other documents other than this Policy Manual + that are necessary to fully understand some Debian policies and + procedures. +

+ +

+ The external "sub-policy" documents are referred to in: + + + + + + + + + +

+ +

+ In addition to those, which carry the weight of policy, there + is the Debian Developer's Reference. This document describes + procedures and resources for Debian developers, but it is + not normative; rather, it includes things that don't + belong into the Policy, such as best practices for developers. +

+ +

+ The Developer's Reference is available in the + developers-reference package. + It's also available from the Debian web mirrors at + . +

+ + The Debian Archive +

The Debian GNU/Linux system is maintained and distributed as a collection of packages. Since there are so many of @@ -244,16 +276,27 @@ sections and given priorities to simplify the handling of them.

+

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

+ +

+ The aims of this are: + + + to allow us to make as much software available as we can + to allow us to encourage everyone to write free software, + and + to allow us to make it easy for people to produce + CD-ROMs of our system without violating any licenses, + import/export restrictions, or any other laws. +

@@ -266,71 +309,44 @@ 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.

+ to these packages as well. +

- - Package copyright and sections + + The Debian Free Software Guidelines

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

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

- - -

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

- - -

to allow us to make it easy for people to produce - CD-ROMs of our system without violating any licenses, - import/export restrictions, or any other laws.

- - -

- - The Debian Free Software Guidelines -

- The Debian Free Software Guidelines (DFSG) form our - definition of `free software'. These are: + The Debian Free Software Guidelines (DFSG) form our + definition of "free software". These are: Free Redistribution -

The license of a Debian component may not restrict any party from selling or giving away the software as a component of an aggregate software distribution containing programs from several different sources. The license may not require a royalty or other fee for such sale. -

Source Code -

The program must include source code, and must allow distribution in source code as well as compiled form. -

Derived Works -

The license must allow modifications and derived works, and must allow them to be distributed under the same terms as the license of the original software. -

Integrity of The Author's Source Code -

The license may restrict source-code from being distributed in modified form only if the - license allows the distribution of ``patch files'' + license allows the distribution of "patch files" with the source code for the purpose of modifying the program at build time. The license must explicitly permit distribution of software built from modified @@ -339,41 +355,33 @@ original software. (This is a compromise. The Debian Project encourages all authors to not restrict any files, source or binary, from being modified.) -

No Discrimination Against Persons or Groups -

The license must not discriminate against any person or group of persons. -

No Discrimination Against Fields of Endeavor -

The license must not restrict anyone from making use of the program in a specific field of endeavor. For example, it may not restrict the program from being used in a business, or from being used for genetic research. -

Distribution of License -

The rights attached to the program must apply to all to whom the program is redistributed without the need for execution of an additional license by those parties. -

License Must Not Be Specific to Debian -

The rights attached to the program must not depend on the program's being part of a Debian system. If the program is extracted from Debian and used or @@ -382,89 +390,82 @@ the program is redistributed must have the same rights as those that are granted in conjunction with the Debian system. -

License Must Not Contaminate Other Software -

The license must not place restrictions on other software that is distributed along with the licensed software. For example, the license must not insist that all other programs distributed on the same medium must be free software. -

Example Licenses -

- The ``GPL,'' ``BSD,'' and ``Artistic'' licenses are - examples of licenses that we consider free. -

+ The "GPL," "BSD," and "Artistic" licenses are examples of + licenses that we consider free. -

- - +

+ + + + Sections + + The main section +

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

+ Guidelines). +

In addition, the packages in main -

must not require a package outside of main for compilation or execution (thus, the package must not declare a "Depends", "Recommends", or "Build-Depends" relationship on a non-main package), -

-

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

-

must meet all policy requirements presented in this manual. -

+

Similarly, the packages in non-US/main -

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

-

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

-

must meet all policy requirements presented in this manual. -

+ - + + The contrib section +

Every package in contrib and non-US/contrib must comply with the DFSG. @@ -475,16 +476,12 @@ non-US/contrib -

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

-

must meet all policy requirements presented in this manual. -

@@ -500,223 +497,219 @@ 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. -

- + + The non-free section +

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

+

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

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

-

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

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

Non-free programs with cryptographic program code need to be stored on the non-us server because of export restrictions of the U.S.

+

Programs which use patented algorithms that have a - restrictied license also need to be stored on "non-us", + restricted license also need to be stored on "non-us", since that is located in a country where it is not allowed to patent algorithms.

+

A package depends on another package which is distributed via the non-us server has to be stored on the non-us server as well.

- - 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/copyright - (see for further details). -

-

- We reserve the right to restrict files from being included - anywhere in our archives if - - -

+ + + + Copyright considerations + +

+ 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 + + their use or distribution would break a law, -

- - -

+ + there is an ethical conflict in their distribution or use, -

- - -

+ + we would have to sign a license for them, or -

- - -

+ + their distribution would conflict with other project policies. -

- - -

+ + +

-

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

+

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

-

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

+

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

-

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

+

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

-

- Many authors are unaware of the problems that restrictive - copyrights (or lack of copyright notices) can cause for - the users of their supposedly-free software. It is often - worthwhile contacting such authors diplomatically to ask - them to modify their license terms. However, this can be a - politically difficult thing to do and you should ask for - advice on the debian-legal mailing list first, as - explained below. -

+

+ Many authors are unaware of the problems that restrictive + copyrights (or lack of copyright notices) can cause for + the users of their supposedly-free software. It is often + worthwhile contacting such authors diplomatically to ask + them to modify their license terms. However, this can be a + politically difficult thing to do and you should ask for + advice on the debian-legal mailing list first, as + explained below. +

-

- When in doubt about a copyright, send mail to - 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'. -

- - - Subsections +

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

+ -

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

+ + Subsections -

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

+

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

+ +

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

- - -

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

- - -

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

- - -

+ + +

-

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

- - +

+ The Debian archive maintainers provide the authoritative + list of subsections. At present, they are: + admin, base, comm, + contrib, devel, doc, + editors, electronics, embedded, + games, gnome, graphics, + hamradio, interpreters, kde, + libs, libdevel, mail, + math, misc, net, news, + non-US, non-free, oldlibs, + otherosfs, perl, python, + 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 by the Debian package management tools - to separate high-priority packages from less-important - packages.

+ included in the package's control record + (see ). + This information is used by the Debian package management tools to + separate high-priority packages from less-important packages. +

The following priority levels are recognised by the @@ -724,7 +717,6 @@ required -

Packages which are necessary for the proper functioning of the system. You must not remove these packages or your system may become totally broken and @@ -732,22 +724,19 @@ 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.

+ sysadmin to boot and install more software. important -

Important programs, including those which one would expect to find on any Unix-like system. If the expectation is that an experienced Unix person who - found it missing would say `What on earth is going on, - where is foo?', it must be an + 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 @@ -755,19 +744,17 @@ 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.

+ commonly-expected and necessary tools. standard -

These packages provide a reasonably small but not too limited character-mode system. This is what will be installed by default if the user doesn't select anything - else. It doesn't include many large applications.

+ else. It doesn't include many large applications. optional -

(In a sense everything that isn't required is optional, but that's not what is meant here.) This is all the software that you might reasonably want to @@ -776,19 +763,17 @@ and includes the X Window System, a full TeX distribution, and many applications. Note that optional packages should not conflict with each other. -

extra -

This contains all packages that conflict with others with required, important, standard or optional priorities, or are only likely to be useful if you already know what they are or have specialised requirements. -

-

+ +

Packages must not depend on packages with lower priority @@ -798,541 +783,639 @@

- - Binary packages + -

- The Debian GNU/Linux distribution is based on the Debian - package management system, called dpkg. Thus, - all packages in the Debian distribution must be provided - in the .deb file format.

+ + Binary packages - - The package name +

+ The Debian GNU/Linux distribution is based on the Debian + package management system, called dpkg. Thus, + all packages in the Debian distribution must be provided + in the .deb file format. +

-

- Every package must have a name that's unique within the Debian - archive.

+ + The package name + +

+ Every package must have a name that's unique within the Debian + archive. +

+ +

+ The package name is included in the control field + Package, the format of which is described + in . + The package name is also included as a part of the file name + of the .deb file. +

+ + + + The version of a package + +

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

+ +

+ The package management system imposes an ordering on version + numbers, so that it can tell whether packages are being up- or + downgraded and so that package system front end applications + can tell whether a package it finds available is newer than + the one installed on the system. The version number format + has the most significant parts (as far as comparison is + concerned) at the beginning. +

+ +

+ If an upstream package has problematic version numbers they + should be converted to a sane form for use in the + Version field. +

+ + + Version numbers based on dates

- 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 start - with an alphanumeric character. + In general, Debian packages should use the same version + numbers as the upstream sources.

- The package name is part of the file name of the - .deb file and is included in the control field - information. + However, in some cases where the upstream version number is + based on a date (e.g., a development "snapshot" release) the + package management system cannot handle these version + numbers without epochs. For example, dpkg will consider + "96May01" to be greater than "96Dec24".

- - - The maintainer of a package -

- Every package must have a Debian maintainer (the - maintainer may be one person or a group of people - reachable from a common email address, such as a mailing - list). The maintainer is responsible for ensuring that - the package is placed in the appropriate distributions. +

+ To prevent having to use epochs for every new upstream + version, the date based portion of the version number + should be changed to the following format in such cases: + "19960501", "19961224". It is up to the maintainer whether + he/she wants to bother the upstream maintainer to change + the version numbers upstream, too.

- The maintainer must be specified in the - Maintainer control field with their correct name - and a working email address. If one person maintains - several packages, he/she should try to avoid having - different forms of their name and email address in - the Maintainer fields of those packages. + Note that other version formats based on dates which are + parsed correctly by the package management system should + not be changed.

- If the maintainer of a package quits from the Debian - 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. -

- + Native Debian packages (i.e., packages which have been + written especially for Debian) whose version numbers include + dates should always use the "YYYYMMDD" format.

+ + + + The maintainer of a package - - The description of a package +

+ Every package must have a Debian maintainer (the + maintainer may be one person or a group of people + reachable from a common email address, such as a mailing + list). The maintainer is responsible for ensuring that + the package is placed in the appropriate distributions. +

+ +

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

+ +

+ The format of the Maintainer control field is + described in . +

+ +

+ If the maintainer of a package quits from the Debian + 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, + see . + +

+ + + + The description of a package + +

+ Every Debian package must have an extended description + stored in the appropriate field of the control record. + The technical information about the format of the + Description field is in . +

+ +

+ The description should describe the package (the program) to a + user (system administrator) who has never met it before so that + they have enough information to decide whether they want to + install it. This description should not just be copied verbatim + from the program's documentation. +

+ +

+ Put important information first, both in the synopsis and + extended description. Sometimes only the first part of the + synopsis or of the description will be displayed. You can + assume that there will usually be a way to see the whole + extended description. +

+ +

+ The description should also give information about the + significant dependencies and conflicts between this package + and others, so that the user knows why these dependencies and + conflicts have been declared. +

+ +

+ Instructions for configuring or using the package should + not be included (that is what installation scripts, + manual pages, info files, etc., are for). Copyright + statements and other administrivia should not be included + either (that is what the copyright file is for). +

+ + The single line synopsis

- Every Debian package must have an extended description - stored in the appropriate field of the control record.

+ The single line synopsis should be kept brief - certainly + under 80 characters. +

- 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). + Do not include the package name in the synopsis line. The + display software knows how to display this already, and you + do not need to state it. Remember that in many situations + the user may only see the synopsis line - make it as + informative as you can.

- + - - Dependencies + The extended description

- Every package must specify the dependency information - about other packages that are required for the first to - work correctly.

+ Do not try to continue the single line synopsis into the + extended description. This will not work correctly when + the full description is displayed, and makes no sense + where only the summary (the single line synopsis) is + available. +

- For example, a dependency entry must be provided for any - shared libraries required by a dynamically-linked executable - binary in a package.

+ The extended description should describe what the package + does and how it relates to the rest of the system (in terms + of, for example, which subsystem it is which part of). +

- Packages are not required to declare any dependencies they - have on other packages which are marked Essential - (see below), and should not do so unless they depend on a - particular version of that package.

+ The description field needs to make sense to anyone, even + people who have no idea about any of the things the + package deals with. + The blurb that comes with a program in its + announcements and/or README files is + rarely suitable for use in a description. It is + usually aimed at people who are already in the + community where the package is used. + +

-

- Sometimes, a package requires another package to be installed - and configured before it can be installed. In this - case, you must specify a Pre-Depends entry for - the package.

+ -

- You should not specify a Pre-Depends entry for a - package before this has been discussed on the - debian-devel mailing list and a consensus about - doing that has been reached.

 + + + Dependencies - - Virtual packages +

+ Every package must specify the dependency information + about other packages that are required for the first to + work correctly. +

-

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

+

+ For example, a dependency entry must be provided for any + shared libraries required by a dynamically-linked executable + binary in a package. +

-

- All packages should use virtual package names where - appropriate, and arrange to create new ones if necessary. - They should not use virtual package names (except privately, - amongst a cooperating group of packages) unless they have - been agreed upon and appear in the list of virtual package - names. (See also )

+

+ Packages are not required to declare any dependencies they + have on other packages which are marked Essential + (see below), and should not do so unless they depend on a + particular version of that package. +

-

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

 +

+ Sometimes, a package requires another package to be installed + and configured before it can be installed. In this + case, you must specify a Pre-Depends entry for + the package. +

+

+ You should not specify a Pre-Depends entry for a + package before this has been discussed on the + debian-devel mailing list and a consensus about + doing that has been reached. +

- - Base packages +

+ The format of the package interrelationship control fields is + described in . +

+ -

- The packages included in the base section have a - special function. They form a minimum subset of the Debian - GNU/Linux system that is installed before everything else - on a new system. Thus, only very few packages are allowed - to go into the base section to keep the required - disk usage very small.

+ + Virtual packages -

- Most of these packages will have the priority value - required or at least important, and many - of them will be tagged essential (see below).

+

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

-

- You must not place any packages into the base - section before this has been discussed on the - debian-devel mailing list and a consensus about - doing that has been reached.

+

+ All packages should use virtual package names where + appropriate, and arrange to create new ones if necessary. + They should not use virtual package names (except privately, + amongst a cooperating group of packages) unless they have + been agreed upon and appear in the list of virtual package + names. (See also ) +

+

+ The latest version of the authoritative list of virtual + package names can be found in the debian-policy package. + It is also available from the Debian web mirrors at + . +

- - Essential packages +

+ The procedure for updating the list is described in the preface + to the list. +

-

- Some packages are tagged essential. (They have - Essential: yes in their package control record.) - This flag is used for packages that are essential - for a system.

+ -

- Since these packages cannot be easily removed (one has to - specify an extra force option to - dpkg to do so), this flag must not be used - unless absolutely necessary. A shared library package - must not be tagged essential; dependencies will - prevent its premature removal, and we need to be able to - remove it when it has been superseded. -

+ + Base system -

- Since dpkg will not prevent upgrading of other packages - while an essential package is in an unconfigured +

+ The base system is a minimum subset of the Debian + GNU/Linux system that is installed before everything else + on a new system. Thus, only very few packages are allowed + to go into the base section to keep the required + disk usage very small. +

+ +

+ Most of these packages will have the priority value + required or at least important, and many + of them will be tagged essential (see below). +

+ + + + Essential packages + +

+ Some packages are tagged essential for a system + using the Essential control file field. + The format of the Essential control field is + described in . +

+ +

+ Since these packages cannot be easily removed (one has to + specify an extra force option to + dpkg to do so), this flag must not be used + unless absolutely necessary. A shared library package + must not be tagged essential; dependencies will + prevent its premature removal, and we need to be able to + remove it when it has been superseded. +

+ +

+ Since dpkg will not prevent upgrading of other packages + while an essential package is in an unconfigured state, all essential packages must supply all of their core functionality even when unconfigured. If the package cannot satisfy this requirement it must not be tagged as essential, and any packages depending on this package must instead have explicit dependency fields as appropriate. -

+

-

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

- - - Tasks +

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

+ -

- The Debian install process allows the user to choose from - a number of common tasks which a Debian system can be used to - perform. Selecting a task with tasksel causes - a set of packages that are useful in performing that task to be - installed. -

+ + Tasks -

- This set of packages is all available packages which have the - name of the selected task in the Task field of their - control file. The format of this field is a list of tasks, - separated by commas. -

+

+ The Debian install process allows the user to choose from + a number of common tasks which a Debian system can be used to + perform. Selecting a task with tasksel causes + a set of packages that are useful in performing that task to be + installed. +

-

- You should not tag any packages as belonging to a task - before this has been discussed on the - debian-devel mailing list and a consensus about - doing that has been reached. -

+

+ This set of packages is all available packages which have the + name of the selected task in the Task field of their + control file. The format of this field is a list of tasks, + separated by commas. +

-

- For third parties (and historical reasons), tasksel also - supports constructing tasks based on task - packages. These are packages whose names begin with - task-. Task packages should not be included in the - Debian archive. -

- +

+ You should not tag any packages as belonging to a task + before this has been discussed on the + debian-devel mailing list and a consensus about + doing that has been reached. +

- - Maintainer Scripts +

+ For third parties (and historical reasons), tasksel also + supports constructing tasks based on task + packages. These are packages whose names begin with + task-. Task packages should not be included in the + Debian archive. +

+ -

- The package installation scripts should avoid producing - output which it is unnecessary for the user to see and - should rely on dpkg to stave off boredom on - the part of a user installing many packages. This means, - amongst other things, using the --quiet option on - install-info.

+ + Maintainer Scripts -

- Errors which occur during the execution of an installation - script must be checked and the installation must not - continue after an error. -

+

+ The package installation scripts should avoid producing + output which is unnecessary for the user to see and + should rely on dpkg to stave off boredom on + the part of a user installing many packages. This means, + amongst other things, using the --quiet option on + install-info. +

-

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

+

+ Errors which occur during the execution of an installation + script must be checked and the installation must not + continue after an error. +

+

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

+ +

+ You should not use dpkg-divert on a file + belonging to another package without consulting the + maintainer of that package first. +

+ +

+ All packages which supply an instance of a common command + name (or, in general, filename) should generally use + update-alternatives, so that they may be + installed together. If update-alternatives + is not used, then each package must use + Conflicts to ensure that other packages are + de-installed. (In this case, it may be appropriate to + specify a conflict against earlier versions of something + that previously did not use + update-alternatives; this is an exception to + the usual rule that versioned conflicts should be + avoided.) +

+ + + Prompting in maintainer scripts

- You should not use dpkg-divert on a file - belonging to another package without consulting the - maintainer of that package first. + Package maintainer scripts may prompt the user if + necessary. Prompting should be done by communicating + through a program, such as debconf, which + conforms to the Debian Configuration management + specification, version 2 or higher. Prompting the user by + other means, such as by hand + From the Jargon file: by hand 2. By extension, + writing code which does something in an explicit or + low-level way for which a presupplied library + (debconf, in this instance) routine ought + to have been available. + , is now deprecated.

- All packages which supply an instance of a common command - name (or, in general, filename) should generally use - update-alternatives, so that they may be - installed together. If update-alternatives - is not used, then each package must use - Conflicts to ensure that other packages are - de-installed. (In this case, it may be appropriate to - specify a conflict against earlier versions of something - that previously did not use - update-alternatives; this is an exception to - the usual rule that versioned conflicts should be - avoided.) + The Debian Configuration management specification is included + in the debconf_specification files in the + debian-policy package. + It is also available from the Debian web mirrors at + .

- - - Prompting in maintainer scripts -

- Package maintainer scripts may prompt the user if - necessary. Prompting may be accomplished by hand, or by - communicating with a program, such as - debconf, which conforms to the Debian - Configuration management specification, version 2 or - higher. These are included in the - debconf_specification files in the - debian-policy package. - You may also find this file on the FTP site - ftp.debian.org in - /debian/doc/package-developer/debconf_specification.txt.gz - or on your local mirror. -

- 4% 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, etc. -

-

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

- -

-

- Packages which use the Debian Configuration management - specification may contain an additional - config script and a templates - file in their control archive. The config - script might be run before the preinst - script, and before the package is unpacked or any of its - dependencies or pre-dependancies are satisfied. - Therefore it must work using only the tools present in - essential packages. -

+

+ Packages which use the Debian Configuration management + specification may contain an additional + config script and a templates + file in their control archive + The control.tar.gz inside the .deb. + See . + . + The config script might be run before the + preinst script, and before the package is unpacked + or any of its dependencies or pre-dependancies are satisfied. + Therefore it must work using only the tools present in + essential packages. 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. -

- -

- -

- Packages should try to minimize the amount of prompting - they need to do, and they should ensure that the user - will only ever be asked each question once. This means - that packages should try to use appropriate shared - configuration files (such as /etc/papersize and - /etc/news/server), and shared - debconf variables rather than each - prompting for their own list of required pieces of - information. -

- -

- It also means that an upgrade should not ask the same - questions again, unless the user has used dpkg - --purge to remove the package's configuration. The - answers to configuration questions should be stored in an - appropriate place in /etc so that the user can - modify them, and how this has been done should be - documented.

- -

- If a package has a vitally important piece of - information to pass to the user (such as "don't run me - as I am, you must edit the following configuration files - first or you risk your system emitting badly-formatted - messages"), it should display this in the - config or postinst script and - prompt the user to hit return to acknowledge the - message. Copyright messages do not count as vitally - important (they belong in - /usr/share/doc/package/copyright); - neither do instructions on how to use a program (these - should be in on-line documentation, where all the users - can see them).

- -

- Any necessary prompting should almost always be confined - to the config or postinst - script. If it is done in the postinst, it - should be protected with a conditional so that - unnecessary prompting doesn't happen if a package's - installation fails and the postinst is - called with abort-upgrade, - abort-remove or abort-deconfigure.

- - - - - Source packages - - - Standards conformance + +

- In the source package's Standards-Version control - field, you should specify the most recent version number - of this policy document with which your package complied - when it was last updated. The current version number is - &version;. + Packages should try to minimize the amount of prompting + they need to do, and they should ensure that the user + will only ever be asked each question once. This means + that packages should try to use appropriate shared + configuration files (such as /etc/papersize and + /etc/news/server), and shared + debconf variables rather than each + prompting for their own list of required pieces of + information.

- This information may be used to file bug reports - automatically if your package becomes too much out of - date. + It also means that an upgrade should not ask the same + questions again, unless the user has used + dpkg --purge to remove the package's configuration. + The answers to configuration questions should be stored in an + appropriate place in /etc so that the user can + modify them, and how this has been done should be + documented.

- The version number has four components: major and minor - version number and major and minor patch level. When the - standards change in a way that requires every package to - change the major number will be changed. Significant - changes that will require work in many packages will be - signaled by a change to the minor number. The major patch - level will be changed for any change to the meaning of the - standards, however small; the minor patch level will be - changed when only cosmetic, typographical or other edits - are made which neither change the meaning of the document - nor affect the contents of packages.

+ If a package has a vitally important piece of + information to pass to the user (such as "don't run me + as I am, you must edit the following configuration files + first or you risk your system emitting badly-formatted + messages"), it should display this in the + config or postinst script and + prompt the user to hit return to acknowledge the + message. Copyright messages do not count as vitally + important (they belong in + /usr/share/doc/package/copyright); + neither do instructions on how to use a program (these + should be in on-line documentation, where all the users + can see them). +

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

- + Any necessary prompting should almost always be confined + to the config or postinst + script. If it is done in the postinst, it + should be protected with a conditional so that + unnecessary prompting doesn't happen if a package's + installation fails and the postinst is + called with abort-upgrade, + abort-remove or abort-deconfigure.

+ -

- You should regularly, and especially if your package has - become out of date, check for the newest Policy Manual - available and update your package, if necessary. When your - package complies with the new standards you should update the - Standards-Version source package field and - release it. -

- See the file upgrading-checklist for - information about policy which has changed between + + + + + + + Source packages + + + Standards conformance + +

+ Source packages should specify the most recent version number + of this policy document with which your package complied + when it was last updated. +

+ +

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

+ +

+ The version is specified in the Standards-Version + control field. + The format of the Standards-Version field is + described in . +

+ +

+ You should regularly, and especially if your package has + become out of date, check for the newest Policy Manual + available and update your package, if necessary. When your + package complies with the new standards you should update the + Standards-Version source package field and + release it. + See the file upgrading-checklist for + information about policy which has changed between different versions of this document. -

- -

- + +

+ - - Package relationships + + Package relationships -

- Source packages should specify which binary packages they - require to be installed or not to be installed in order to - build correctly. For example, if building a package - requires a certain compiler, then the compiler should be - specified as a build-time dependency. -

+

+ Source packages should specify which binary packages they + require to be installed or not to be installed in order to + build correctly. For example, if building a package + requires a certain compiler, then the compiler should be + specified as a build-time dependency. +

-

- It is not necessary to explicitly specify build-time - relationships on a minimal set of packages that are always - needed to compile, link and put in a Debian package a - standard "Hello World!" program written in C or C++. The - required packages are called build-essential, and - an informational list can be found in - /usr/share/doc/build-essential/list (which is - contained in the build-essential - package). -

Rationale: +

+ It is not necessary to explicitly specify build-time + relationships on a minimal set of packages that are always + needed to compile, link and put in a Debian package a + standard "Hello World!" program written in C or C++. The + required packages are called build-essential, and + an informational list can be found in + /usr/share/doc/build-essential/list (which is + contained in the build-essential + package). + Rationale: -

This allows maintaining the list separately + This allows maintaining the list separately from the policy documents (the list does not need the kind of control that the policy documents do). -

-

Having a separate package allows one to install the build-essential packages on a machine, as well as allowing other packages such as tasks to require installation of the build-essential packages using the depends relation. -

-

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

-

- - -

+ +

-

- When specifying the set of build-time dependencies, one - should list only those packages explicitly required by the - build. It is not necessary to list packages which are - required merely because some other package in the list of - build-time dependencies depends on them. -

+

+ When specifying the set of build-time dependencies, one + should list only those packages explicitly required by the + build. It is not necessary to list packages which are + required merely because some other package in the list of + build-time dependencies depends on them. The reason for this is that dependencies change, and you should list all those packages, and only those packages that you need directly. What @@ -1344,568 +1427,308 @@ 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 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 not - specific to the needs of the Debian system, they should be - sent to the upstream authors in whatever form they prefer - so as to be included in the upstream version of the - package.

- -

- If you need to configure the package differently for - Debian or for Linux, and the upstream source doesn't - provide a way to do so, you should add such configuration - facilities (for example, a new autoconf test - or #define) and send the patch to the upstream - authors, with the default set to the way they originally - had it. You can then easily override the default in your - debian/rules or wherever is appropriate.

- -

- You should make sure that the configure utility - detects the correct architecture specification string - (refer to for details).

- -

- If you need to edit a Makefile where - GNU-style configure scripts are used, you - should edit the .in files rather than editing the - Makefile directly. This allows the user to - reconfigure the package if necessary. You should - not configure the package and edit the generated - Makefile! This makes it impossible for - someone else to later reconfigure the package.

 - + +

- - Documenting your changes +

+ If build-time dependencies are specified, it must be + possible to build the package and produce working binaries + on a system with only essential and build-essential + packages installed and also those required to satisfy the + build-time relationships (including any implied + relationships). In particular, this means that version + clauses should be used rigorously in build-time + relationships so that one cannot produce bad or + inconsistently configured packages when the relationships + are properly satisfied. +

-

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

+

+ explains the technical details. +

+ -

- In non-experimental packages you must use a format for - debian/changelog which is supported by the most - 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.) -

- -

- + + Changes to the upstream sources +

+ If changes to the source code are made that are not + specific to the needs of the Debian system, they should be + sent to the upstream authors in whatever form they prefer + so as to be included in the upstream version of the + package. +

- - Error trapping in makefiles +

+ If you need to configure the package differently for + Debian or for Linux, and the upstream source doesn't + provide a way to do so, you should add such configuration + facilities (for example, a new autoconf test + or #define) and send the patch to the upstream + authors, with the default set to the way they originally + had it. You can then easily override the default in your + debian/rules or wherever is appropriate. +

-

- When make invokes a command in a makefile - (including your package's upstream makefiles and - debian/rules), it does so using sh. This - means that sh's usual bad error handling - properties apply: if you include a miniature script as one - of the commands in your makefile you'll find that if you - don't do anything about it then errors are not detected - and make will blithely continue after - problems.

+

+ You should make sure that the configure utility + detects the correct architecture specification string + (refer to for details). +

-

- Every time you put more than one shell command (this - includes using a loop) in a makefile command you - must make sure that errors are trapped. For - simple compound commands, such as changing directory and - then running a program, using && rather - than semicolon as a command separator is sufficient. For - more complex commands including most loops and - conditionals you should include a separate set -e - command at the start of every makefile command that's - actually one of these miniature shell scripts.

 +

+ If you need to edit a Makefile where GNU-style + configure scripts are used, you should edit the + .in files rather than editing the + Makefile directly. This allows the user to + reconfigure the package if necessary. You should + not configure the package and edit the generated + Makefile! This makes it impossible for someone + else to later reconfigure the package without losing the + changes you made. +

+ - - Obsolete constructs and libraries + + Debian changelog: debian/changelog -

- The include file <varargs.h> is - provided to support end-users compiling very old software; - the library libtermcap is provided to support the - execution of software which has been linked against it - (either old programs or those such as Netscape which are - only available in binary form).

+

+ Changes in the Debian version of the package should be + briefly explained in the Debian changelog file + debian/changelog. This includes modifications + made in the Debian package compared to the upstream one + as well as other changes and updates to the package. + + Although there is nothing stopping an author who is also + the Debian maintainer from using this changelog for all + their changes, it will have to be renamed if the Debian + and upstream maintainers become different people. In such + a case, however, it might be better to maintain the package + as a non-native package. + +

-

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

- - - +

+ Mistakes in changelogs are usually best rectified by making + a new changelog entry rather than "rewriting history" by + editing old changelog entries. +

- Control files and their fields +

+ The format of the debian/changelog allows the + package building tools to discover which version of the package + is being built and find out other release-specific information. +

-

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

+

+ That format is a series of entries like this: - Syntax of control files + +package (version) distribution(s); urgency=urgency + + [optional blank line(s), stripped] + + * change details + more change details + + [blank line(s), included in output of dpkg-parsechangelog] + + * even more change details + + [optional blank line(s), stripped] + + -- maintainer name <email address>[two spaces] date + +

- 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.) + package and version are the source + package name and version number.

- 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. + distribution(s) lists the distributions where + this version should be installed when it is uploaded - it + is copied to the Distribution field in the + .changes file. See .

- Some fields' values may span several lines; in this case - each continuation line must start with a space or - tab. Any trailing spaces or tabs at the end of individual - lines of a field value are ignored. + urgency is the value for the Urgency + field in the .changes file for the upload + (see ). It is not possible to specify + an urgency containing commas; commas are used to separate + keyword=value settings in the + dpkg changelog format (though there is + currently only one useful keyword, + urgency). + Recognised urgency values are low, + medium, high and emergency. + They have an effect on how quickly a package will be + considered for inclusion into the testing + distribution, and give an indication of the importance + of any fixes included in this upload. +

- Except where otherwise stated only a single line of data is - allowed and whitespace is not significant in a field body. - Whitespace must not appear inside names (of packages, - architectures, files or anything else) or version numbers, - or between the characters of multi-character version - relationships. + The change details may in fact be any series of lines + starting with at least two spaces, but conventionally each + change starts with an asterisk and a separating space and + continuation lines are indented so as to bring them in + line with the start of the text above. Blank lines may be + used here to separate groups of changes, if desired.

- Field names are not case-sensitive, but it is usual to - capitalize the field names using mixed case as shown below. + 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. + + This information is conveyed via the Closes field + in the .changes file (see ).

- Blank lines, or lines consisting only of spaces and tabs, - are not allowed within field values or between fields - that - would mean a new paragraph. + The maintainer name and email address used in the changelog + should be the details of the person uploading this + version. They are not necessarily those of the + usual package maintainer. The information here will be + copied to the Changed-By field in the + .changes file (see ), + and then later used to send an acknowledgement when the + upload has been installed.

- - - List of fields

- This list here is not supposed to be exhaustive. Most fields - are dealt with elsewhere in this document. + The date should be in RFC822 format + This is generated by the 822-date + program. + ; it should include the time zone specified + numerically, with the time zone name or abbreviation + optionally present as a comment in parentheses.

- Package - -

- The name of the binary package. Package names consist of - lower case letters (a-z), digits (0-9), - plus (+) and minus (-) signs, and - periods (.). -

+

+ The first "title" line with the package name should start + at the left hand margin; the "trailer" line with the + maintainer and date details should be preceded by exactly + one space. The maintainer details and the date must be + separated by exactly two spaces. +

-

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

- +

+ For more information on placement of the changelog files + within binary packages, please see . +

- Version - + Alternative changelog formats

- This lists the source or binary package's version number - - see . + In non-experimental packages you must use a format for + debian/changelog which is supported by the most + recent released version of dpkg.

- - - Standards-Version - -

- The most recent version of the standards (the policy - manual and associated texts) with which the package - complies. This is updated manually when editing the - source package to conform to newer standards; it can - sometimes be used to tell when a package needs attention. - Its format is described above; see - . + It is possible to use a format different from the standard + one by providing a changelog parser for the format you wish + to use. The parser must have an API compatible with that + expected by dpkg-genchanges and + dpkg-gencontrol, and it must not interact with + the user at all. + + 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 + man page may be distributed under the GNU GPL, just as the rest + of dpkg is.) +

+ + + Error trapping in makefiles - Distribution - - -

- In a .changes file or parsed changelog output - this contains the (space-separated) name(s) of the - distribution(s) where this version of the package should - be installed. Valid distributions are determined by the - archive maintainers. - Current distribution names are: - - stable - -

- This is the current `released' version of Debian - GNU/Linux. Once the distribution is - stable only security fixes and other - major bug fixes are allowed. When changes are - made to this distribution, the release number is - increased (for example: 2.2r1 becomes 2.2r2 then - 2.2r3, etc). -

- +

+ When make invokes a command in a makefile + (including your package's upstream makefiles and + debian/rules), it does so using sh. This + means that sh's usual bad error handling + properties apply: if you include a miniature script as one + of the commands in your makefile you'll find that if you + don't do anything about it then errors are not detected + and make will blithely continue after + problems. +

- unstable - -

- This distribution value refers to the - developmental part of the Debian - distribution tree. New packages, new upstream - versions of packages and bug fixes go into the - unstable directory tree. Download from - this distribution at your own risk. -

- +

+ Every time you put more than one shell command (this + includes using a loop) in a makefile command you + must make sure that errors are trapped. For + simple compound commands, such as changing directory and + then running a program, using && rather + than semicolon as a command separator is sufficient. For + more complex commands including most loops and + conditionals you should include a separate set -e + command at the start of every makefile command that's + actually one of these miniature shell scripts. +

+ - testing - -

- This distribution value refers to the - testing part of the Debian distribution - tree. It receives its packages from the - unstable distribution after a short time lag to - ensure that there are no major issues with the - unstable packages. It is less prone to breakage - than unstable, but still risky. It is not - possible to upload packages directly to - testing. -

- - - frozen - -

- From time to time, the testing - distribution enters a state of `code-freeze' in - anticipation of release as a stable - version. During this period of testing only - fixes for existing or newly-discovered bugs will - be allowed. The exact details of this stage are - determined by the Release Manager. -

- - - experimental - -

- The packages with this distribution value are - deemed by their maintainers to be high - risk. Oftentimes they represent early beta or - developmental packages from various sources that - the maintainers want people to try, but are not - ready to be a part of the other parts of the - Debian distribution tree. Download at your own - risk. -

- - - - You should list all distributions that the - package should be installed into. - -

- - - - - - - Version numbering - -

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

- -

- The package management system imposes an ordering on version - numbers, so that it can tell whether packages are being up- or - downgraded and so that package system front end applications - can tell whether a package it finds available is newer than - the one installed on the system. The version number format - has the most significant parts (as far as comparison is - concerned) at the beginning. -

- -

- The version number format is: - [epoch:]upstream_version[-debian_revision] -

- -

- The three components here are: - - epoch - -

- 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 - contain any colons. -

- -

- It is provided to allow mistakes in the version numbers - of older versions of a package, and also a package's - previous version numbering schemes, to be left behind. -

- - - upstream_version - -

- 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 - portion of the version number is mandatory. -

- -

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

- 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. - This format represents the case where a piece of - software was written specifically to be turned into a - Debian package, and so there is only one `debianization' - of it and therefore no revision indication is required. -

- -

- It is conventional to restart the - debian_revision at 1 each time the - upstream_version is increased. -

- -

- The package management system will break the version - number apart at the last hyphen in the string (if there - is one) to determine the 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 - parts are compared by the package management system using the - same algorithm: -

- -

- The strings are compared from left to right. -

- -

- First the initial part of each string consisting entirely of - non-digit characters is determined. These two parts (one of - which may be empty) are compared lexically. If a difference - is found it is returned. The lexical comparison is a - comparison of ASCII values modified so that all the letters - sort earlier than all the non-letters. -

- -

- Then the initial part of the remainder of each string which - consists entirely of digit characters is determined. The - numerical values of these two parts are compared, and any - difference found is returned as the result of the comparison. - For these purposes an empty string (which can only occur at - the end of one or both version strings being compared) counts - as zero. -

- -

- These two steps (comparing and removing initial non-digit - strings and initial digit strings) are repeated until a - difference is found or both strings are exhausted. -

- -

- Note that the purpose of epochs is to allow us to leave behind - mistakes in version numbering, and to cope with situations - where the version numbering scheme changes. It is - not intended to cope with version numbers containing - strings of letters which the package management system cannot - interpret (such as ALPHA or pre-), or with - silly orderings (the author of this manual has heard of a - package whose versions went 1.1, 1.2, - 1.3, 1, 2.1, 2.2, - 2 and so forth). -

- -

- If an upstream package has problematic version numbers they - should be converted to a sane form for use in the - Version field. -

- - - Version numbers based on dates -

- In general, Debian packages should use the same version - numbers as the upstream sources.

- -

- However, in some cases where the upstream version number is - based on a date (e.g., a development `snapshot' release) the - package management system cannot handle these version - numbers without epochs. For example, dpkg will consider - `96May01' to be greater than `96Dec24'.

- -

- To prevent having to use epochs for every new upstream - version, the version number should be changed to the - following format in such cases: `19960501', `19961224'. It - is up to the maintainer whether he/she wants to bother the - upstream maintainer to change the version numbers upstream, - too.

- -

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

- -

- Native Debian packages (i.e., packages which have been - written especially for Debian) whose version numbers include - dates should always use the `YYYYMMDD' format.

- - - - Packaging Considerations - - Time Stamps + + Time Stamps

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 by knowing the age of the file, for example, you could recognize that some documentation is very old by looking at the modification time, so it would be nice if the modification time of the upstream source would be preserved. + +

+ + + + Restrictions on objects in source packages + +

+ The source package may not contain any hard links +

+ This is not currently detected when building source + packages, but only when extracting + them. +

+

+ Hard links may be permitted at some point in the + future, but would require a fair amount of + work.

+ , device special files, sockets or setuid or + setgid files. + Setgid directories are allowed.

- debian/rules - the - main building script + + Main building script: debian/rules

This file must be an executable makefile, and contains the @@ -1933,15 +1756,14 @@ Package: libc6

- The required and optional targets are as follows: + The targets are as follows (required unless stated otherwise): - build, build-arch (optional), - build-indep (optional) + build

- The build target should perform all - non-interactive configuration and compilation of the - package. If a package has an interactive pre-build + The build target should perform all the + configuration and compilation of the package. + If a package has an interactive pre-build configuration routine, the Debianized source package must either be built after this has taken place (so that the binary package can be built without rerunning @@ -1984,7 +1806,6 @@ Package: libc6 complete. This will ensure that if debian/rules 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 @@ -1997,11 +1818,50 @@ Package: libc6 .PHONY target). See the documentation of make for more information on phony targets. -

+ build-arch (optional), + build-indep (optional) + + +

+ A package may also provide both of the targets + build-arch and build-indep. + The build-arch target, if provided, should + perform all the configuration and compilation required + for producing all architecture-dependant binary packages + (those packages for which the body of the + Architecture field in debian/control + is not all). + Similarly, the build-indep target, if + provided, should perform all the configuration and + compilation required for producing all + architecture-independent binary packages + (those packages for which the body of the + Architecture field in debian/control + is all). + The build target should depend on those of the + targets build-arch and build-indep that + are provided in the rules file. +

+ +

+ If one or both of the targets build-arch and + build-indep are not provided, then invoking + debian/rules with one of the not-provided + targets as arguments should produce a exit status code + of 2. Usually this is provided automatically by make + if the target is missing. +

+ +

+ The build-arch and build-indep targets + must not do anything that might require root privilege. +

+ + binary, binary-arch, binary-indep @@ -2009,8 +1869,7 @@ Package: libc6

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

The binary targets must be invoked as root. -

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

@@ -2061,7 +1918,7 @@ Package: libc6 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. + target.

@@ -2124,7 +1981,8 @@ Package: libc6

The architectures we build on and build for are determined by make variables using the utility - dpkg-architecture. You can determine the + 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 @@ -2132,19 +1990,19 @@ Package: libc6 supported make variables: -

DEB_*_ARCH (the Debian architecture)

+ DEB_*_ARCH (the Debian architecture) -

DEB_*_GNU_TYPE (the GNU style architecture - specification string)

+ DEB_*_GNU_TYPE (the GNU style architecture + 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_SYSTEM (the System part of + DEB_*_GNU_TYPE) where * is either BUILD for specification of the build machine or HOST for specification of the @@ -2167,8087 +2025,7624 @@ Package: libc6

- debian/changelog - + + + Variable substitutions: debian/substvars

- This file records the changes to the Debian-specific parts of the - package -

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

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

- It has a special format which allows the package building - tools to discover which version of the package is being - built and find out other release-specific information. + The debian/substvars file is usually generated and + modified dynamically by debian/rules targets, in + which case it must be removed by the clean target.

- That format is a series of entries like this: - -package (version) distribution(s); urgency=urgency - -

[optional blank line(s), stripped]

- - * change details - more change details - -

[blank line(s), included in output of dpkg-parsechangelog]

- - * even more change details - -

[optional blank line(s), stripped]

- - -- maintainer name <email - address>[two spaces] date - -

+ See for full + details about source variable substitutions, including the + format of debian/substvars.

+ + + + Generated files list: debian/files

- package and version are the source - package name and version number. + This file is not a permanent part of the source tree; it + is used while building packages to record which files are + being generated. dpkg-genchanges uses it + when it generates a .changes file.

- distribution(s) lists the distributions where - this version should be installed when it is uploaded - it - is copied to the Distribution field in the - .changes file. See . + It should not exist in a shipped source package, and so it + (and any backup files or temporary files such as + files.new + files.new is used as a temporary file by + dpkg-gencontrol and + dpkg-distaddfile - they write a new + version of files here before renaming it, + to avoid leaving a corrupted copy if an error + occurs. + ) should be removed by the + clean target. It may also be wise to + ensure a fresh start by emptying or removing it at the + start of the binary target.

- urgency is the value for the Urgency - field in the .changes file for the upload. It is - not possible to specify an urgency containing commas; commas - are used to separate - keyword=value settings in the - dpkg changelog format (though there is - currently only one useful keyword, - urgency). -

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

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

- The change details may in fact be any series of lines - starting with at least two spaces, but conventionally each - change starts with an asterisk and a separating space and - continuation lines are indented so as to bring them in - line with the start of the text above. Blank lines may be - used here to separate groups of changes, if desired. + If a package upload includes files besides the source + package and any binary packages whose control files were + made with dpkg-gencontrol then they should be + placed in the parent of the package's top-level directory + and dpkg-distaddfile should be called to add + the file to the list in debian/files.

+ + + + + + + Control files and their fields + +

+ The package management system manipulates data represented in + a common format, known as control data, stored in + control files. + Control files are used for source packages, binary packages and + the .changes files which control the installation + of uploaded files + dpkg's internal databases are in a similar + format. + . +

+ + + Syntax of control files + +

+ A control file consists of one or more paragraphs of + fields + The paragraphs are also sometimes referred to as stanzas. + . + 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.)

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

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

- 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. + Some fields' values may span several lines; in this case + each continuation line must start with a space or a tab. + Any trailing spaces or tabs at the end of individual + lines of a field value are ignored.

- The date should be in RFC822 format -

- This is generated by the 822-date - program. -

- ; it should include the time zone specified - numerically, with the time zone name or abbreviation - optionally present as a comment in parentheses. + Except where otherwise stated, only a single line of data is + allowed and whitespace is not significant in a field body. + Whitespace must not appear inside names (of packages, + architectures, files or anything else) or version numbers, + or between the characters of multi-character version + relationships.

- The first `title' line with the package name should start - at the left hand margin; the `trailer' line with the - maintainer and date details should be preceded by exactly - one space. The maintainer details and the date must be - separated by exactly two spaces. + Field names are not case-sensitive, but it is usual to + capitalize the field names using mixed case as shown below.

- Defining alternative changelog formats +

+ Blank lines, or lines consisting only of spaces and tabs, + are not allowed within field values or between fields - that + would mean a new paragraph. +

-

- It is possible to use a different format to the standard - one, by providing a parser for the format you wish to - use. -

-

- A changelog parser must not interact with the user at - all. -

- - debian/substvars - and variable substitutions + + Source package control files -- debian/control

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

- 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. + The first paragraph of the control file contains information about + the source package in general. The subsequent sets each describe a + binary package that the source tree builds.

- See for full - details about source variable substitutions, including the - format of debian/substvars.

- + The fields in the general paragraph (the first one, for the source + package) are: - debian/files - + + Source (mandatory) + Maintainer (mandatory) + Section (recommended) + Priority (recommended) + Build-Depends et al + Standards-Version (recommended) + +

- This file is not a permanent part of the source tree; it - is used while building packages to record which files are - being generated. dpkg-genchanges uses it - when it generates a .changes file. + The fields in the binary package paragraphs are: + + + Package (mandatory) + Architecture (mandatory) + Section (recommended) + Priority (recommended) + Essential + Depends et al + Description (mandatory) +

- It should not exist in a shipped source package, and so it - (and any backup files or temporary files such as - files.new -

- files.new is used as a temporary file by - dpkg-gencontrol and - dpkg-distaddfile - they write a new - version of files here before renaming it, - to avoid leaving a corrupted copy if an error - occurs -

- ) should be removed by the - clean target. It may also be wise to - ensure a fresh start by emptying or removing it at the - start of the binary target. + The syntax and semantics of the fields are described below.

+ +

- 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. + These fields are used by dpkg-gencontrol to + generate control files for binary packages (see below), by + dpkg-genchanges to generate the + .changes file to accompany the upload, and by + dpkg-source when it creates the .dsc + source control file as part of a source archive.

- If a package upload includes files besides the source - package and any binary packages whose control files were - made with dpkg-gencontrol then they should be - placed in the parent of the package's top-level directory - and dpkg-distaddfile should be called to add - the file to the list in debian/files.

+ The fields here may contain variable references - their + values will be substituted by dpkg-gencontrol, + dpkg-genchanges or dpkg-source + when they generate output control files. + See for details. +

+ - Restrictions on objects in source packages - + + Binary package control files -- DEBIAN/control

- The source package may not contain any hard links -

- This is not currently detected when building source - packages, but only when extracting - them. -

-

- Hard links may be permitted at some point in the - future, but would require a fair amount of - work. -

- , device special files, sockets or setuid or - setgid files. -

- Setgid directories are allowed. -

- + The DEBIAN/control file contains the most vital + (and version-dependent) information about a binary package. +

+ +

+ The fields in this file are: + + + Package (mandatory) + Source + Version (mandatory) + Section (recommended) + Priority (recommended) + Architecture (mandatory) + Essential + Depends et al + Installed-Size + Maintainer (mandatory) + Description (mandatory) +

- Descriptions of packages - the - Description field + + + Debian source control files -- .dsc

- The description is intended to describe the program to a user - who has never met it before so that they know whether they - want to install it. It should also give information about the - significant dependencies and conflicts between this package - and others, so that the user knows why these dependencies and - conflicts have been declared. + This file contains a series of fields, identified and + separated just like the fields in the control file of + a binary package. The fields are listed below; their + syntax is described above, in . + + + Format + Source (mandatory) + Version (mandatory) + Maintainer (mandatory) + Binary + Architecture + Build-Depends et al + Standards-Version (recommended) + Files (mandatory) +

- Notes about writing descriptions - +

+ The source package control file is generated by + dpkg-source when it builds the source + archive, from other files in the source package, + described above. When unpacking, it is checked against + the files and directories in the other parts of the + source package. +

+ + + + + Debian changes files -- .changes + +

+ The .changes files are used by the Debian archive maintenance + software to process updates to packages. They contain one + paragraph which contains information from the + debian/control file and other data about the + source package gathered via debian/changelog + and debian/rules. +

+ +

+ The fields in this file are: + + + Format (mandatory) + Date (mandatory) + Source (mandatory) + Binary (mandatory) + Architecture (mandatory) + Version (mandatory) + Distribution (mandatory) + Urgency (recommended) + Maintainer (mandatory) + Changed-By + Description (mandatory) + Closes + Changes (mandatory) + Files (mandatory) + +

+ + + + List of fields + + + Source

- The single line synopsis should be kept brief - certainly - under 80 characters. + This field identifies the source package name.

- Do not include the package name in the synopsis line. The - display software knows how to display this already, and you - do not need to state it. Remember that in many situations - the user may only see the synopsis line - make it as - informative as you can. + In a main source control information, a .changes + or a .dsc file this may contain only the name + of the source package.

- Do not try to continue the single line synopsis into the - extended description. This will not work correctly when - the full description is displayed, and makes no sense - where only the summary (the single line synopsis) is - available. + In the control file of a binary package it may be followed + by a version number in parentheses + It is customary to leave a space after the package name + if a version number is specified. + . + This version number may be omitted (and is, by + dpkg-gencontrol) if it has the same value as + the Version field of the binary package in + question. The field itself may be omitted from a binary + package control file when the source package has the same + name and version as the binary package.

+ + + + Maintainer

- The extended description should describe what the package - does and how it relates to the rest of the system (in terms - of, for example, which subsystem it is which part of). + The package maintainer's name and email address. The name + should come first, then the email address inside angle + brackets <> (in RFC822 format).

- The description field needs to make sense to anyone, even - people who have no idea about any of the things the - package deals with. -

- The blurb that comes with a program in its - announcements and/or README files is - rarely suitable for use in a description. It is - usually aimed at people who are already in the - community where the package is used. -

- + If the maintainer's name contains a full stop then the + whole field will not work directly as an email address due + to a misfeature in the syntax specified in RFC822; a + program using this field as an address must check for this + and correct the problem if necessary (for example by + putting the name in round brackets and moving it to the + end, and bringing the email address forward).

+ + + + Changed-By

- Put important information first, both in the synopsis and - extended description. Sometimes only the first part of the - synopsis or of the description will be displayed. You can - assume that there will usually be a way to see the whole - extended description. + The name and email address of the person who changed the + said package. Usually the name of the maintainer. + All the rules for the Maintainer field apply here, too.

+ + + + Section

- You may include information about dependencies and so forth - in the extended description, if you wish. + This field specifies an application area into which the package + has been classified. See .

- Do not use tab characters. Their effect is not predictable. + When it appears in the debian/control file, + it gives the value for the subfield of the same name in + the Files field of the .changes file. + It also gives the default for the same field in the binary + packages.

+

+ By default, dpkg-gencontrol does not include this + field in the control file of a binary package - use the + -is (or -isp) options to achieve this effect. +

- - + + Priority - Package maintainer scripts - and installation procedure - +

+ This field represents how important that it is that the user + have the package installed. See . +

- Introduction to package maintainer scripts - +

+ When it appears in the debian/control file, + it gives the value for the subfield of the same name in + the Files field of the .changes file. + It also gives the default for the same field in the binary + packages. +

-

- It is possible to supply scripts as part of a package which - the package management system will run for you when your - package is installed, upgraded or removed. -

+

+ By default, dpkg-gencontrol does not include this + field in the control file of a binary package - use the + -ip (or -isp) options to achieve this effect. +

+ -

- These scripts are the files preinst, - postinst, prerm and postrm in the - control area of the package. They must be proper executable - files; if they are scripts (which is recommended), they must - start with the usual #! convention. They should be - readable and executable by anyone, and not world-writable. -

+ + Package -

- The package management system looks at the exit status from - these scripts. It is important that they exit with a - non-zero status if there is an error, so that the package - management system can stop its processing. For shell - scripts this means that you almost always need to - use set -e (this is usually true when writing shell - scripts, in fact). It is also important, of course, that - they don't exit with a non-zero status if everything went - well. -

+

+ The name of the binary package. +

-

- When a package is upgraded a combination of the scripts from - the old and new packages is called during the upgrade - procedure. If your scripts are going to be at all - complicated you need to be aware of this, and may need to - check the arguments to your scripts. -

+

+ Package names must consist only of lower case letters + (a-z), digits (0-9), plus (+) + and minus (-) signs, and periods (.). + They must be at least two characters long and must start + with an alphanumeric character. +

+ -

- Broadly speaking the preinst is called before - (a particular version of) a package is installed, and the - postinst afterwards; the prerm - before (a version of) a package is removed and the - postrm afterwards. -

+ + Architecture + +

+ Depending on context and the control file used, the + Architecture field can include the following sets of + values: + + A unique single word identifying a Debian machine + architecture, see . + all, which indicates an + architecture-independent package. + any, which indicates a package available + for building on any architecture. + source, which indicates a source package. + +

-

- Programs called from maintainer scripts should not normally - have a path prepended to them. Before installation is - started, the package management system checks to see if the - programs ldconfig, - start-stop-daemon, install-info, - and update-rc.d can be found via the - PATH environment variable. Those programs, and any - other program that one would expect to be on the - PATH, should thus be invoked without an absolute - pathname. Maintainer scripts should also not reset the - PATH, though they might choose to modify it by - prepending or appending package-specific directories. These - considerations really apply to all shell scripts.

- +

+ In the main debian/control file in the source + package, or in the source package control file + .dsc, one may specify a list of architectures + separated by spaces, or the special values any or + all. +

- - Maintainer scripts Idempotency +

+ Specifying any indicates that the source package + isn't dependent on any particular architecture and should + compile fine on any one. The produced binary package(s) + will be specific to whatever the current build architecture + is. + This is the most often used setting, and is recommended + for new packages that aren't Architecture: all. + +

-

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

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

- -

- +

+ Specifying a list of architectures indicates that the source + will build an architecture-dependent package, and will only + work correctly on the listed architectures. + This is a setting used for a minority of cases where the + program is not portable. Generally, it should not be used + for new packages. + +

- - Controlling terminal for maintainer scripts +

+ In a .changes file, the Architecture + field lists the architecture(s) of the package(s) + currently being uploaded. This will be a list; if the + source for the package is also being uploaded, the special + entry source is also present. +

-

- The maintainer scripts are guaranteed to run with a - controlling terminal and can interact with the user. - If they need to prompt for passwords, do full-screen - interaction or something similar you should do these - things to and from /dev/tty, since - dpkg will at some point redirect scripts' - standard input and output so that it can log the - installation process. Likewise, because these scripts - may be executed with standard output redirected into a - pipe for logging purposes, Perl scripts should set - unbuffered output by setting $|=1 so that the - output is printed immediately rather than being - buffered. -

+

+ See for information how to get the + architecture for the build process. +

+ -

- Each script should return a zero exit status for - success, or a nonzero one for failure. -

- + + Essential - Summary of ways maintainer - scripts are called - +

+ This is a boolean field which may occur only in the + control file of a binary package or in a per-package fields + paragraph of a main source control data file. +

-

- - -

new-preinst install

- - -

new-preinst install - old-version

- - -

new-preinst upgrade - old-version

- - -

old-preinst abort-upgrade - new-version -

- - +

+ If set to yes then the package management system + will refuse to remove the package (upgrading and replacing + it is still possible). The other possible value is no, + which is the same as not having the field at all. +

+ -

- - -

postinst configure - most-recently-configured-version

- - -

old-postinst abort-upgrade - new-version

- - -

conflictor's-postinst abort-remove - in-favour package - new-version

- - -

- deconfigured's-postinst - abort-deconfigure in-favour - failed-install-package version - removing conflicting-package - version -

- - + + Package interrelationship fields: + Depends, Pre-Depends, + Recommends, Suggests, Conflicts, + Provides, Replaces, Enhances + -

- - -

prerm remove

- - -

old-prerm upgrade - new-version

- - -

new-prerm failed-upgrade - old-version

- - -

conflictor's-prerm remove - in-favour package - new-version

- - -

- deconfigured's-prerm deconfigure - in-favour package-being-installed - version removing - conflicting-package - version -

- - +

+ These fields describe the package's relationships with + other packages. Their syntax and semantics are described + in .

+ + + + Standards-Version + +

+ The most recent version of the standards (the policy + manual and associated texts) with which the package + complies. +

+ +

+ The version number has four components: major and minor + version number and major and minor patch level. When the + standards change in a way that requires every package to + change the major number will be changed. Significant + changes that will require work in many packages will be + signaled by a change to the minor number. The major patch + level will be changed for any change to the meaning of the + standards, however small; the minor patch level will be + changed when only cosmetic, typographical or other edits + are made which neither change the meaning of the document + nor affect the contents of packages. +

+ +

+ Thus only the first three components of the policy version + are significant in the Standards-Version control + field, and so either these three components or the all + four components may be specified. + 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. + +

+ + + + + Version + +

+ The version number of a package. The format is: + [epoch:]upstream_version[-debian_revision] +

+ +

+ The three components here are: + + epoch + +

+ 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 + contain any colons. +

+ +

+ It is provided to allow mistakes in the version numbers + of older versions of a package, and also a package's + previous version numbering schemes, to be left behind. +

+ + + upstream_version + +

+ 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 + portion of the version number is mandatory. +

+ +

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

+ 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. + This format represents the case where a piece of + software was written specifically to be turned into a + Debian package, and so there is only one "debianization" + of it and therefore no revision indication is required. +

+ +

+ It is conventional to restart the + debian_revision at 1 each time the + upstream_version is increased. +

+ +

+ The package management system will break the version + number apart at the last hyphen in the string (if there + is one) to determine the 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 + parts are compared by the package management system using the + same algorithm: +

+ +

+ The strings are compared from left to right. +

+ +

+ First the initial part of each string consisting entirely of + non-digit characters is determined. These two parts (one of + which may be empty) are compared lexically. If a difference + is found it is returned. The lexical comparison is a + comparison of ASCII values modified so that all the letters + sort earlier than all the non-letters. +

+ +

+ Then the initial part of the remainder of each string which + consists entirely of digit characters is determined. The + numerical values of these two parts are compared, and any + difference found is returned as the result of the comparison. + For these purposes an empty string (which can only occur at + the end of one or both version strings being compared) counts + as zero. +

+ +

+ These two steps (comparing and removing initial non-digit + strings and initial digit strings) are repeated until a + difference is found or both strings are exhausted. +

+ +

+ Note that the purpose of epochs is to allow us to leave behind + mistakes in version numbering, and to cope with situations + where the version numbering scheme changes. It is + not intended to cope with version numbers containing + strings of letters which the package management system cannot + interpret (such as ALPHA or pre-), or with + silly orderings (the author of this manual has heard of a + package whose versions went 1.1, 1.2, + 1.3, 1, 2.1, 2.2, + 2 and so forth). +

+ + + + Description + +

+ In a source or binary control file, the Description + field contains a description of the binary package, consisting + of two parts, the synopsis or the short description, and the + long description. The field's format is as follows: +

+ +

+ + Description: <single line synopsis> + <extended description over several lines> + +

+ +

+ The lines in the extended description can have these formats: +

+ +

-

- - -

postrm remove

- -

postrm purge

+ Those starting with a single space are part of a paragraph. + Successive lines of this form will be word-wrapped when + displayed. The leading space will usually be stripped off. + -

- old-postrm upgrade - new-version

+ Those starting with two or more spaces. These will be + displayed verbatim. If the display cannot be panned + horizontally, the displaying program will linewrap them "hard" + (i.e., without taking account of word breaks). If it can they + will be allowed to trail off to the right. None, one or two + initial spaces may be deleted, but the number of spaces + deleted from each line will be the same (so that you can have + indenting work correctly, for example). + -

new-postrm failed-upgrade - old-version

+ Those containing a single space followed by a single full stop + character. These are rendered as blank lines. This is the + only way to get a blank line + Completely empty lines will not be rendered as blank lines. + Instead, they will cause the parser to think you're starting + a whole new record in the control file, and will therefore + likely abort with an error. + . + -

new-postrm abort-install

+ Those containing a space, a full stop and some more characters. + These are for future expansion. Do not use them. - -

new-postrm abort-install - old-version

- - -

new-postrm abort-upgrade - old-version

- - -

- disappearer's-postrm disappear - overwriter - overwriter-version

 - -

+

- Details of unpack phase of - installation or upgrade - +

+ Do not use tab characters. Their effect is not predictable. +

-

- The procedure on installation/upgrade/overwrite/disappear - (i.e., when running dpkg --unpack, or the unpack - stage of dpkg --install) is as follows. In each - case, if a major error occurs (unless listed below) the - actions are, in general, run backwards - this means that the - maintainer scripts are run with different arguments in - reverse order. These are the `error unwind' calls listed - below. +

+ See for further information on this. +

- - -

- - -

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

- +

+ In a .changes file, the Description field + contains a summary of the descriptions for the packages being + uploaded. +

+ +

+ The part of the field before the first newline is empty; + thereafter each line has the name of a binary package and + the summary description line from that binary package. + Each line is indented by one space. +

+ + + + + Distribution + +

+ In a .changes file or parsed changelog output + this contains the (space-separated) name(s) of the + distribution(s) where this version of the package should + be installed. Valid distributions are determined by the + archive maintainers. + Current distribution names are: + + stable -

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

+ This is the current "released" version of Debian + GNU/Linux. Once the distribution is + stable only security fixes and other + major bug fixes are allowed. When changes are + made to this distribution, the release number is + increased (for example: 2.2r1 becomes 2.2r2 then + 2.2r3, etc). - -

- - -

If a `conflicting' package is being removed at the same time: - + + unstable -

- 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 - - Error unwind: - -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 - --install is used they will be - configured again if possible.

+ This distribution value refers to the + developmental part of the Debian + distribution tree. New packages, new upstream + versions of packages and bug fixes go into the + unstable directory tree. Download from + this distribution at your own risk. + + testing -

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

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

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

+ From time to time, the testing + distribution enters a state of "code-freeze" in + anticipation of release as a stable + version. During this period of testing only + fixes for existing or newly-discovered bugs will + be allowed. The exact details of this stage are + determined by the Release Manager. - -

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

+ experimental -

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

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

- - -

- The new package's files are unpacked, overwriting any - that may be on the system already, for example any - from the old version of the same package or from - another package. Backups of the old files are kept - temporarily, and if anything goes wrong the package - management system will attempt to put them back as - part of the error unwind. -

+ -

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

+

+ You should list all distributions that the + package should be installed into. +

-

- It is a more serious error for a package to contain a - plain file or other kind of non-directory where another - package has a directory (again, unless - Replaces is used). This error can be - overridden if desired using - --force-overwrite-dir, but this is not - advisable. -

+

+ More information is available in the Debian Developer's + Reference, section "The Debian archive". +

+ +

+ -

- Packages which overwrite each other's files produce - behavior which, though deterministic, is hard for the - system administrator to understand. It can easily - lead to `missing' programs if, for example, a package - is installed which overwrites a file from another - package, and is then removed again. -

- Part of the problem is due to what is arguably a - bug in dpkg. -

- -

+ + Date -

- A directory will never be replaced by a symbolic link - to a directory or vice versa; instead, the existing - state (symlink or not) will be left alone and - dpkg will follow the symlink if there is - one.

- +

+ This field includes the date the package was built or last edited. +

- -

- - -

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

- - -

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

- - -

-

- This is the point of no return - if - dpkg gets this far, it won't back off - past this point if an error occurs. This will - leave the package in a fairly bad state, which - will require a successful re-installation to clear - up, but it's when dpkg starts doing - things that are irreversible. -

- - -

- Any files which were in the old version of the package - but not in the new are removed.

- - -

The new file list replaces the old.

- - -

The new maintainer scripts replace the old.

- +

+ The value of this field is usually extracted from the + debian/changelog file - see + ). +

+ - -

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

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

- - -

The package's maintainer scripts are removed. -

- - -

- It is noted in the status database as being in a - sane state, namely not installed (any conffiles - it may have are ignored, rather than being - removed by dpkg). Note that - disappearing packages do not have their prerm - called, because dpkg doesn't know - in advance that the package is going to - vanish. -

- - -

- - -

- Any files in the package we're unpacking that are also - listed in the file lists of other packages are removed - from those lists. (This will lobotomize the file list - of the `conflicting' package if there is one.) -

- - -

- The backup files made during installation, above, are - deleted. -

- + + Format - -

- The new package's status is now sane, and recorded as - `unpacked'. -

+

+ This field specifies a format revision for the file. + The most current format described in the Policy Manual + is version 1.5. The syntax of the + format value is the same as that of a package version + number except that no epoch or Debian revision is allowed + - see . +

+ -

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

- + + Urgency - -

- If there was a conflicting package we go and do the - removal actions (described below), starting with the - removal of the conflicting package's files (any that - are also in the package being installed have already - been removed from the conflicting package's file list, - and so do not get removed now). -

- - -

- +

+ This is a description of how important it is to upgrade to + this version from previous ones. It consists of a single + keyword usually taking one of the values low, + medium or high (not case-sensitive) + followed by an optional commentary (separated by a space) + which is usually in parentheses. For example: - Details of configuration + + Urgency: low (HIGH for users of diversions) + -

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

+

-

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

+

+ The value of this field is usually extracted from the + debian/changelog file - see + . +

+ -

- If there is no most recently configured version - dpkg will pass a null argument; older versions - of dpkg may pass <unknown> (including the - angle brackets) in this case. Even older ones do not pass a - second argument at all, under any circumstances. -

- + + Changes - Details of removal and/or - configuration purging +

+ This field contains the human-readable changes data, describing + the differences between the last version and the current one. +

-

- - -

- -prerm remove - -

- - -

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

- - -

- -postrm remove - -

- - -

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

+

+ There should be nothing in this field before the first + newline; all the subsequent lines must be indented by at + least one space; blank lines must be represented by a line + consiting only of a space and a full stop. +

-

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

- - -

- The conffiles and any backup files - (~-files, #*# files, - %-files, .dpkg-{old,new,tmp}, etc.) - are removed.

- - -

- -postrm purge - -

- - -

The package's file list is removed.

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

- - +

+ The value of this field is usually extracted from the + debian/changelog file - see + ). +

+

+ Each version's change information should be preceded by a + "title" line giving at least the version, distribution(s) + and urgency, in a human-readable way. +

- Declaring relationships between - packages +

+ If data from several versions is being returned the entry + for the most recent version should be returned first, and + entries should be separated by the representation of a + blank line (the "title" line may also be followed by the + representation of blank line). +

+ -

- Packages can declare in their control file that they have - certain relationships to other packages - for example, that - they may not be installed at the same time as certain other - packages, and/or that they depend on the presence of others, - or that they should overwrite files in certain other packages - if present. -

+ + Binary -

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

+

+ This field is a list of binary packages. +

-

- Source packages may declare relationships to binary packages, - saying that they require certain binary packages to be - installed or absent at the time of building the package. -

+

+ When it appears in the .dsc file it is the list + of binary packages which a source package can produce. It + does not necessarily produce all of these binary packages + for every architecture. The source control file doesn't + contain details of which architectures are appropriate for + which of the binary packages. +

-

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

+

+ When it appears in a .changes file it lists the + names of the binary packages actually being uploaded. +

- Syntax of relationship fields - +

+ The syntax is a list of binary packages separated by + commas + A space after each comma is conventional. + . Currently the packages must be separated using + only spaces in the .changes file. +

+ -

- These fields all have a uniform syntax. They are a list of - package names separated by commas. -

+ + Installed-Size -

- In the Depends, Recommends, - Suggests, Pre-Depends, - Build-Depends and Build-Depends-Indep - control file fields of the package, which declare - dependencies on other packages, the package names listed may - also include lists of alternative package names, separated - by vertical bar (pipe) symbols |. In such a case, - if any one of the alternative packages is installed, that - part of the dependency is considered to be satisfied. -

+

+ This field appears in the control files of binary + packages, and in the Packages files. It gives + the total amount of disk space required to install the + named package. +

-

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

+

+ The disk space is represented in kilobytes as a simple + decimal number. +

+ -

- The relations allowed are <<, <=, - =, >= and >> for - strictly earlier, earlier or equal, exactly equal, later or - equal and strictly later, respectively. The deprecated - forms < and > were used to mean - earlier/later or equal, rather than strictly earlier/later, - so they should not appear in new packages (though - dpkg still supports them). -

+ + Files -

- Whitespace may appear at any point in the version - 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 also conventional to put a single space after - each comma, on either side of each vertical bar, and before - each open parenthesis. -

+

+ This field contains a list of files with information about + each one. The exact information and syntax varies with + the context. In all cases the part of the field + contents on the same line as the field name is empty. The + remainder of the field is one line per file, each line + being indented by one space and containing a number of + sub-fields separated by spaces. +

-

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

+ In the .dsc file, each line contains the MD5 + checksum, size and filename of the tar file and (if applicable) + diff file which make up the remainder of the source + package + That is, the parts which are not the .dsc. + . + The exact forms of the filenames are described + in . +

+ +

+ In the .changes file this contains one line per + file being uploaded. Each line contains the MD5 checksum, + size, section and priority and the filename. + The section + and priority + are the values of the corresponding fields in + the main source control file. If no section or priority is + specified then - should be used, though section + and priority values must be specified for new packages to + be installed properly. +

+ +

+ The special value byhand for the section in a + .changes file indicates that the file in question + is not an ordinary package file and must by installed by + hand by the distribution maintainers. If the section is + byhand the priority should be -. +

+ +

+ If a new Debian revision of a package is being shipped and + no new original source archive is being distributed the + .dsc must still contain the Files field + entry for the original source archive + package-upstream-version.orig.tar.gz, + but the .changes file should leave it out. In + this case the original source archive on the distribution + site must match exactly, byte-for-byte, the original + source archive which was used to generate the + .dsc file and diff which are being uploaded.

+ + + + Closes + +

+ A space-separated list of bug report numbers that the upload + governed by the .changes file closes. +

+ + + + + + User-defined fields + +

+ Additional user-defined fields may be added to the + source package control file. Such fields will be + ignored, and not copied to (for example) binary or + source package control files or upload control files.

-

- All fields that specify build-time relationships - (Build-Depends, Build-Depends-Indep, - Build-Conflicts and Build-Conflicts-Indep) - may be restricted to a certain set of architectures. This - is indicated in brackets after each individual package name and - the optional version specification. The brackets enclose a - list of Debian architecture names separated by whitespace. - Exclamation marks may be prepended to each of the names. - (It is not permitted for some names to be prepended with - exclamation marks and others not.) If the current Debian - host architecture is not in this list and there are no - exclamation marks in the list, or it is in the list with a - prepended exclamation mark, the package name and the - associated version specification are ignored completely for - the purposes of defining the relationships. +

+ If you wish to add additional unsupported fields to + these output files you should use the mechanism + described here.

- 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] - + Fields in the main source control information file with + names starting X, followed by one or more of + the letters BCS and a hyphen -, will + be copied to the output files. Only the part of the + field name after the hyphen will be used in the output + file. Where the letter B is used the field + will appear in binary package control files, where the + letter S is used in source package control + files and where C is used in upload control + (.changes) files.

- Note that the binary package relationship fields such as - Depends appear in one of the binary package - sections of the control file, whereas the build-time - relationships such as Build-Depends appear in the - source package section of the control file (which is the - first section). + For example, if the main source information control file + contains the field + + XBS-Comment: I stand between the candle and the star. + + then the binary and source package control files will contain the + field + + Comment: I stand between the candle and the star. +

+ + + + + + Package maintainer scripts and installation procedure + - Binary Dependencies - Depends, - Recommends, Suggests, Enhances, - Pre-Depends - + Introduction to package maintainer scripts

- These five fields are used to declare a dependency - relationship by one package on another. Except for - Enhances, they appear in the depending (binary) - package's control file. (Enhances appears in the - recommending package's control file.) + It is possible to supply scripts as part of a package which + the package management system will run for you when your + package is installed, upgraded or removed.

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

- For this reason packages in an installation run are usually - all unpacked first and all configured later; this gives - later versions of packages with dependencies on later - versions of other packages the opportunity to have their - dependencies satisfied. + The package management system looks at the exit status from + these scripts. It is important that they exit with a + non-zero status if there is an error, so that the package + management system can stop its processing. For shell + scripts this means that you almost always need to + use set -e (this is usually true when writing shell + scripts, in fact). It is also important, of course, that + they don't exit with a non-zero status if everything went + well.

- The Depends field thus allows package maintainers - to impose an order in which packages should be configured. + When a package is upgraded a combination of the scripts from + the old and new packages is called during the upgrade + procedure. If your scripts are going to be at all + complicated you need to be aware of this, and may need to + check the arguments to your scripts.

- The meaning of the five dependency fields is as follows: - - Depends - -

- This declares an absolute dependency. A package will - not be configured unless all of the packages listed in - its Depends field have been correctly - configured. -

+ Broadly speaking the preinst is called before + (a particular version of) a package is installed, and the + postinst afterwards; the prerm + before (a version of) a package is removed and the + postrm afterwards. +

-

- The Depends field should be used if the - depended-on package is required for the depending - package to provide a significant amount of - functionality. -

-

- The Depends field should also be used if the - postinst, prerm or - postrm scripts require the package to be - present in order to run. Note, however, that the - postrm cannot rely on any non-essential - packages to be present during the purge - phase. - +

+ Programs called from maintainer scripts should not normally + have a path prepended to them. Before installation is + started, the package management system checks to see if the + programs ldconfig, + start-stop-daemon, install-info, + and update-rc.d can be found via the + PATH environment variable. Those programs, and any + other program that one would expect to be on the + PATH, should thus be invoked without an absolute + pathname. Maintainer scripts should also not reset the + PATH, though they might choose to modify it by + prepending or appending package-specific directories. These + considerations really apply to all shell scripts.

+ - Recommends - -

This declares a strong, but not absolute, dependency. -

+ + Maintainer scripts Idempotency -

- The Recommends field should list packages - that would be found together with this one in all but - unusual installations.

- +

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

+ - Suggests + + Controlling terminal for maintainer scripts + +

+ The maintainer scripts are guaranteed to run with a + controlling terminal and can interact with the user. + If they need to prompt for passwords, do full-screen + interaction or something similar you should do these + things to and from /dev/tty, since + dpkg will at some point redirect scripts' + standard input and output so that it can log the + installation process. Likewise, because these scripts + may be executed with standard output redirected into a + pipe for logging purposes, Perl scripts should set + unbuffered output by setting $|=1 so that the + output is printed immediately rather than being + buffered. +

+ +

+ Each script should return a zero exit status for + success, or a nonzero one for failure. +

+ + + Summary of ways maintainer + scripts are called + + +

+ -

- This is used to declare that one package may be more - useful with one or more others. Using this field - tells the packaging system and the user that the - listed packages are related to this one and can - perhaps enhance its usefulness, but that installing - this one without them is perfectly reasonable. -

+ new-preinst install - - Enhances -

- This field is similar to Suggests but works in the - opposite direction. It is used to declare that a - package can enhance the functionality of another - package. -

+ new-preinst install old-version + + + new-preinst upgrade old-version + + + old-preinst abort-upgrade + new-version + + + +

+ + + postinst configure + most-recently-configured-version + + + old-postinst abort-upgrade + new-version + + + conflictor's-postinst abort-remove + in-favour package + new-version + + + deconfigured's-postinst + abort-deconfigure in-favour + failed-install-package version + removing conflicting-package + version + + + +

+ + + prerm remove + + + old-prerm upgrade + new-version + + + new-prerm failed-upgrade + old-version + + + conflictor's-prerm remove + in-favour package + new-version + + + deconfigured's-prerm deconfigure + in-favour package-being-installed + version removing + conflicting-package + version + + + +

+ + + postrm remove + + + postrm purge + + + old-postrm upgrade + new-version + + + new-postrm failed-upgrade + old-version + + + new-postrm abort-install + + + new-postrm abort-install + old-version + + + new-postrm abort-upgrade + old-version + + + disappearer's-postrm disappear + overwriter + overwriter-version + + +

+ + + + Details of unpack phase of installation or upgrade + +

+ The procedure on installation/upgrade/overwrite/disappear + (i.e., when running dpkg --unpack, or the unpack + stage of dpkg --install) is as follows. In each + case, if a major error occurs (unless listed below) the + actions are, in general, run backwards - this means that the + maintainer scripts are run with different arguments in + reverse order. These are the "error unwind" calls listed + below. + + + + + + If a version of the package is already installed, call + +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 + + Error unwind, for both the above cases: + +old-postinst abort-upgrade new-version + + + + + + + If a "conflicting" package is being removed at the same time: + + + 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 + + Error unwind: + +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 + --install is used they will be + configured again if possible. + + + To prepare for removal of the conflicting package, call: + +conflictor's-prerm remove \ + in-favour package new-version + + Error unwind: + +conflictor's-postinst abort-remove \ + in-favour package new-version + + + + + + + + + If the package is being upgraded, call: + +new-preinst upgrade old-version + + + + 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 + + + + Otherwise (i.e., the package was completely purged): + +new-preinst install + + Error unwind actions, respectively: + +new-postrm abort-upgrade old-version +new-postrm abort-install old-version +new-postrm abort-install + + + - Pre-Depends

- This field is like Depends, except that it - also forces dpkg to complete installation - of the packages named before even starting the - installation of the package which declares the - pre-dependency, as follows: + The new package's files are unpacked, overwriting any + that may be on the system already, for example any + from the old version of the same package or from + another package. Backups of the old files are kept + temporarily, and if anything goes wrong the package + management system will attempt to put them back as + part of the error unwind.

- 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. + It is an error for a package to contain files which + are on the system in another package, unless + Replaces is used (see ). +

- 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. + It is a more serious error for a package to contain a + plain file or other kind of non-directory where another + package has a directory (again, unless + Replaces is used). This error can be + overridden if desired using + --force-overwrite-dir, but this is not + advisable.

- 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. + Packages which overwrite each other's files produce + behavior which, though deterministic, is hard for the + system administrator to understand. It can easily + lead to "missing" programs if, for example, a package + is installed which overwrites a file from another + package, and is then removed again. + Part of the problem is due to what is arguably a + bug in dpkg. +

- Pre-Depends are also required if the - preinst script depends on the named - package. It is best to avoid this situation if - possible. + A directory will never be replaced by a symbolic link + to a directory or vice versa; instead, the existing + state (symlink or not) will be left alone and + dpkg will follow the symlink if there is + one. +

- -

-

- When selecting which level of dependency to use you should - consider how important the depended-on package is to the - functionality of the one declaring the dependency. Some - packages are composed of components of varying degrees of - importance. Such a package should list using - Depends the package(s) which are required by the - more important components. The other components' - requirements may be mentioned as Suggestions or - Recommendations, as appropriate to the components' relative - importance. -

- - - Conflicting binary packages - - Conflicts -

- When one binary package declares a conflict with another - using a Conflicts field, dpkg will - refuse to allow them to be installed on the system at the - same time. -

+ +

+ + + If the package is being upgraded, call + +old-postrm upgrade new-version + + + + If this fails, dpkg will attempt: + +new-postrm failed-upgrade old-version + + Error unwind, for both cases: + +old-preinst abort-upgrade new-version + + + +

-

- If one package is to be installed, the other must be removed - first - if the package being installed is marked as - 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 is specifically designed to produce an error when - the installed package is Essential, but the new - package is not. -

+

+ This is the point of no return - if + dpkg gets this far, it won't back off + past this point if an error occurs. This will + leave the package in a fairly bad state, which + will require a successful re-installation to clear + up, but it's when dpkg starts doing + things that are irreversible. +

+ -

- A package will not cause a conflict merely because its - configuration files are still installed; it must be at least - half-installed. -

+ + Any files which were in the old version of the package + but not in the new are removed. + -

- A special exception is made for packages which declare a - conflict with their own package name, or with a virtual - package which they provide (see below): this does not - prevent their installation, and allows a package to conflict - with others providing a replacement for it. You use this - feature when you want the package in question to be the only - package providing some feature. -

+ + The new file list replaces the old. + -

- A Conflicts entry should almost never have an - `earlier than' version clause. This would prevent - dpkg from upgrading or installing the package - which declared such a conflict until the upgrade or removal - of the conflicted-with package had been completed. -

- + + The new maintainer scripts replace the old. + - Virtual packages - Provides - + + 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 + + + dpkg calls: + +disappearer's-postrm disappear \ + overwriter overwriter-version + + + + The package's maintainer scripts are removed. + + + It is noted in the status database as being in a + sane state, namely not installed (any conffiles + it may have are ignored, rather than being + removed by dpkg). Note that + disappearing packages do not have their prerm + called, because dpkg doesn't know + in advance that the package is going to + vanish. + + + -

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

+ + Any files in the package we're unpacking that are also + listed in the file lists of other packages are removed + from those lists. (This will lobotomize the file list + of the "conflicting" package if there is one.) + -

- A virtual package is one which appears in the - Provides control file field of another package. - The effect is as if the package(s) which provide a - particular virtual package name had been listed by name - everywhere the virtual package name appears. (See also ) + + The backup files made during installation, above, are + deleted. + + + +

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

+ + + + If there was a conflicting package we go and do the + removal actions (described below), starting with the + removal of the conflicting package's files (any that + are also in the package being installed have already + been removed from the conflicting package's file list, + and so do not get removed now). + +

+ + + Details of configuration

- If there are both concrete and virtual packages of the same - name, then the dependency may be satisfied (or the conflict - caused) by either the concrete package with the name in - question or any other concrete package which provides the - virtual package with the name in question. This is so that, - for example, supposing we have - -Package: foo -Depends: bar - - and someone else releases an enhanced version of the - bar package (for example, a non-US variant), they - can say: + When we configure a package (this happens with dpkg + --install and dpkg --configure), we first + update any conffiles and then call: -Package: bar-plus -Provides: bar +postinst configure most-recently-configured-version - and the bar-plus package will now also satisfy the - dependency for the foo package.

- If a dependency or a conflict has a version number attached - then only real packages will be considered to see whether - the relationship is satisfied (or the prohibition violated, - for a conflict) - it is assumed that a real package which - provides the virtual package is not of the `right' version. - So, a Provides field may not contain version - numbers, and the version number of the concrete package - which provides a particular virtual package will not be - looked at when considering a dependency on or conflict with - the virtual package name. + No attempt is made to unwind after errors during + configuration.

- It is likely that the ability will be added in a future - release of dpkg to specify a version number for - each virtual package it provides. This feature is not yet - present, however, and is expected to be used only - infrequently. + If there is no most recently configured version + dpkg will pass a null argument. + +

+ Historical note: Truly ancient (pre-1997) versions of + dpkg passed <unknown> + (including the angle brackets) in this case. Even older + ones did not pass a second argument at all, under any + circumstance. Note that upgrades using such an old dpkg + version are unlikely to work for other reasons, even if + this old argument behavior is handled by your postinst script. +

+

+ + + Details of removal and/or + configuration purging

- 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. + + + +prerm remove + + + + The package's files are removed (except conffiles). + + + +postrm remove + + + +

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

+ + + The conffiles and any backup files + (~-files, #*# files, + %-files, .dpkg-{old,new,tmp}, etc.) + are removed. + + + +postrm purge + + + + The package's file list is removed. + + + + If there are problems during this process, we call + postinst + abort-remove. No other attempt is made to unwind + after errors during removal.

+ - Overwriting files and replacing - packages - Replaces + + Declaring relationships between packages + + + Syntax of relationship fields

- The Replaces control file field has two distinct - purposes, which come into play in different situations. + These fields all have a uniform syntax. They are a list of + package names separated by commas.

- Overwriting files in other packages - -

- Firstly, as mentioned before, it is usually an error for a - package to contain files which are on the system in - another package. -

- -

- However, if the overwriting package declares that it - Replaces the one containing the file being - overwritten, then dpkg will replace the file - from the old package with that from the new. The file - will no longer be listed as `owned' by the old package. -

- -

- If a package is completely replaced in this way, so that - dpkg does not know of any files it still - contains, it is considered to have `disappeared'. It will - be marked as not wanted on the system (selected for - removal) and not installed. Any 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 Depends, Recommends, + Suggests, Pre-Depends, + Build-Depends and Build-Depends-Indep + control file fields of the package, which declare + dependencies on other packages, the package names listed may + also include lists of alternative package names, separated + by vertical bar (pipe) symbols |. In such a case, + if any one of the alternative packages is installed, that + part of the dependency is considered to be satisfied. +

-

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

+

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

-

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

+

+ The relations allowed are <<, <=, + =, >= and >> for + strictly earlier, earlier or equal, exactly equal, later or + equal and strictly later, respectively. The deprecated + forms < and > were used to mean + earlier/later or equal, rather than strictly earlier/later, + so they should not appear in new packages (though + dpkg still supports them). +

-

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

+

+ Whitespace may appear at any point in the version + 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 also conventional to put a single space after + each comma, on either side of each vertical bar, and before + each open parenthesis. +

- +

+ For example, a list of dependencies might appear as: + +Package: mutt +Version: 1.3.17-1 +Depends: libc6 (>= 2.2.1), exim | mail-transport-agent + +

- Replacing whole packages, forcing their - removal +

+ All fields that specify build-time relationships + (Build-Depends, Build-Depends-Indep, + Build-Conflicts and Build-Conflicts-Indep) + may be restricted to a certain set of architectures. This + is indicated in brackets after each individual package name and + the optional version specification. The brackets enclose a + list of Debian architecture names separated by whitespace. + Exclamation marks may be prepended to each of the names. + (It is not permitted for some names to be prepended with + exclamation marks and others not.) If the current Debian + host architecture is not in this list and there are no + exclamation marks in the list, or it is in the list with a + prepended exclamation mark, the package name and the + associated version specification are ignored completely for + the purposes of defining the relationships. +

-

- 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 usages of this field do not interfere with - each other. -

+

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

-

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

+ Note that the binary package relationship fields such as + Depends appear in one of the binary package + sections of the control file, whereas the build-time + relationships such as Build-Depends appear in the + source package section of the control file (which is the + first section). +

- Relationships between source and binary packages - - Build-Depends, Build-Depends-Indep, - Build-Conflicts, Build-Conflicts-Indep + + Binary Dependencies - Depends, + Recommends, Suggests, Enhances, + Pre-Depends

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

- If you make "build-arch" or "binary-arch", you need - Build-Depends. If you make "build-indep" or - "binary-indep", you need Build-Depends and - Build-Depends-Indep. If you make "build" or "binary", - you need both. -

-

- There is no Build-Depends-Arch; the autobuilders will - only need the Build-Depends if they know how to build - only build-arch and binary-arch. Anyone building the - build-indep/binary-indep targets is basically assumed to - be building the whole package and so installs all build - dependencies. -

-

- The purpose of the original split, I recall, was so that - the autobuilders wouldn't need to install extra packages - needed only for the binary-indep targets. But without a - build-arch/build-indep split, this didn't work, since - most of the work is done in the build target, not in the - binary target. -

- + Packages can declare in their control file that they have + certain relationships to other packages - for example, that + they may not be installed at the same time as certain other + packages, and/or that they depend on the presence of others. +

+ +

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

+ +

+ These six fields are used to declare a dependency + relationship by one package on another. Except for + Enhances, they appear in the depending (binary) + package's control file. (Enhances appears in the + recommending package's control file.) +

+ +

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

+ +

+ For this reason packages in an installation run are usually + all unpacked first and all configured later; this gives + later versions of packages with dependencies on later + versions of other packages the opportunity to have their + dependencies satisfied. +

+ +

+ The Depends field thus allows package maintainers + to impose an order in which packages should be configured. +

+

+ The meaning of the five dependency fields is as follows: - Build-Depends, Build-Conflicts + Depends

- The Build-Depends and - Build-Conflicts fields must be satisfied when - any of the following targets is invoked: - build, binary, binary-arch, - build-arch, build-indep - and binary-indep. + This declares an absolute dependency. A package will + not be configured unless all of the packages listed in + its Depends field have been correctly + configured. +

+ +

+ The Depends field should be used if the + depended-on package is required for the depending + package to provide a significant amount of + functionality.

+ +

+ The Depends field should also be used if the + postinst, prerm or + postrm scripts require the package to be + present in order to run. Note, however, that the + postrm cannot rely on any non-essential + packages to be present during the purge + phase. - Build-Depends-Indep, - Build-Conflicts-Indep + + Recommends

- The Build-Depends-Indep and - Build-Conflicts-Indep fields must be - satisfied when any of the following targets is - invoked: build, build-indep, - binary and binary-indep. + This declares a strong, but not absolute, dependency.

- - -

+

+ The Recommends field should list packages + that would be found together with this one in all but + unusual installations. +

+ - - - - - Configuration file handling - - -

- This chapter has been superseded by . -

+ Suggests + + This is used to declare that one package may be more + useful with one or more others. Using this field + tells the packaging system and the user that the + listed packages are related to this one and can + perhaps enhance its usefulness, but that installing + this one without them is perfectly reasonable. + + Enhances + + This field is similar to Suggests but works in the + opposite direction. It is used to declare that a + package can enhance the functionality of another + package. + - Shared libraries + Pre-Depends + +

+ This field is like Depends, except that it + also forces dpkg to complete installation + of the packages named before even starting the + installation of the package which declares the + pre-dependency, as follows: +

-

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

+

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

-

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

+

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

-

- Secondly, the package should include the symbolic link that - ldconfig would create for the shared libraries. - For example, the libgdbmg1 package should include - a symbolic link from /usr/lib/libgdbm.so.1 to - libgdbm.so.1.7.3. This is needed so that the dynamic - linker (for example ld.so or - ld-linux.so.*) can find the library between the - time that dpkg installs it and the time that - ldconfig is run in the postinst - script. -

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

- -

+

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

-

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

+

+ Pre-Depends are also required if the + preinst script depends on the named + package. It is best to avoid this situation if + possible. +

+ + +

-

- 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 use ldconfig to update the shared library - system. The package must call ldconfig in the - postinst script if the first argument is - configure; the postinst script may - optionally invoke ldconfig at other times. The - package should call ldconfig in the - postrm script if the first argument is - remove. The maintainer scripts must not invoke - ldconfig under any circumstances other than those - described in this paragraph. -

During install or upgrade, the preinst is called before - the new files are installed, so calling "ldconfig" is - pointless. The preinst of an existing package can also be - called if an upgrade fails. However, this happens during - the critical time when a shared libs may exist on-disk - under a temporary name. Thus, it is dangerous and - forbidden by current policy to call "ldconfig" at this - time. -

-

When a package is installed or upgraded, "postinst - configure" runs after the new files are safely on-disk. - Since it is perfectly safe to invoke ldconfig - unconditionally in a postinst, it is OK for a package to - simply put ldconfig in its postinst without checking the - argument. The postinst can also be called to recover from - a failed upgrade. This happens before any new files are - unpacked, so there is no reason to call "ldconfig" at this - point. -

-

For a package that is being removed, prerm is - called with all the files intact, so calling ldconfig is - useless. The other calls to "prerm" happen in the case of - upgrade at a time when all the files of the old package - are on-disk, so again calling "ldconfig" is pointless. -

-

postrm, on the other hand, is called with the "remove" - argument just after the files are removed, so this is the - proper time to call "ldconfig" to notify the system of the - fact shared libraries from the package are removed. - The postrm can be called at several other times. At the - time of "postrm purge", "postrm abort-install", or "postrm - abort-upgrade", calling "ldconfig" is useless because the - shared lib files are not on-disk. However, when "postrm" - is invoked with arguments "upgrade", "failed-upgrade", or - "disappear", a shared lib may exist on-disk under a - temporary filename. -

- -

+

+ When selecting which level of dependency to use you should + consider how important the depended-on package is to the + functionality of the one declaring the dependency. Some + packages are composed of components of varying degrees of + importance. Such a package should list using + Depends the package(s) which are required by the + more important components. The other components' + requirements may be mentioned as Suggestions or + Recommendations, as appropriate to the components' relative + importance. +

+ - - Handling shared library dependencies - the - shlibs system + + Conflicting binary packages - Conflicts

- 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. + When one binary package declares a conflict with another + using a Conflicts field, dpkg will + refuse to allow them to be installed on the system at the + same time.

- 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 is used to do this. The only - change this makes to package building is that - dpkg-shlibdeps must also be run on shared - libraries, whereas in the past this was unnecessary. - The rest of this footnote explains the advantage that - this method gives. -

- -

- We say that a binary foo directly uses - a library libbar if it is explicitly linked - with that library (that is, it uses the flag - -lbar during the linking stage). Other - libraries that are needed by libbar are linked - indirectly to foo, and the dynamic - linker will load them automatically when it loads - libbar. A package should depend on - the libraries it directly uses, and the dependencies for - those libraries should automatically pull in the other - libraries. -

+ If one package is to be installed, the other must be removed + first - if the package being installed is marked as + 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 is specifically designed to produce an error when + the installed package is Essential, but the new + package is not. +

-

- Unfortunately, the ldd program shows both - the directly and indirectly used libraries, meaning that - the dependencies determined included both direct and - indirect dependencies. The use of objdump - avoids this problem by determining only the directly - used libraries. -

+

+ A package will not cause a conflict merely because its + configuration files are still installed; it must be at least + half-installed. +

-

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

- +

+ A special exception is made for packages which declare a + conflict with their own package name, or with a virtual + package which they provide (see below): this does not + prevent their installation, and allows a package to conflict + with others providing a replacement for it. You use this + feature when you want the package in question to be the only + package providing some feature.

- 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. + A Conflicts entry should almost never have an + "earlier than" version clause. This would prevent + dpkg from upgrading or installing the package + which declared such a conflict until the upgrade or removal + of the conflicted-with package had been completed.

- The shlibs files present on the system + Virtual packages - Provides +

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

+

- 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.) + A virtual package is one which appears in the + Provides control file field of another package. + The effect is as if the package(s) which provide a + particular virtual package name had been listed by name + everywhere the virtual package name appears. (See also )

- - -

debian/shlibs.local

-

- This lists overrides for this package. Its use is - described below (see ). -

- - - -

/etc/dpkg/shlibs.override

-

- This lists global overrides. This list is normally - empty. It is maintained by the local system - administrator. -

- - - -

DEBIAN/shlibs files in the `build directory'

-

- When packages are being built, any - debian/shlibs files are copied into the - control file area of the temporary build directory and - given the name shlibs. These files give - details of any shared libraries included in the - package. -

- 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

-

- These are the shlibs files corresponding to - all of the packages installed on the system, and are - maintained by the relevant package maintainers. -

- - - -

/etc/dpkg/shlibs.default

-

- This file lists any shared libraries whose packages - have failed to provide correct shlibs files. - It was used when the shlibs setup was first - introduced, but it is now normally empty. It is - maintained by the dpkg maintainer. -

- - -

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

- Put a call to dpkg-shlibdeps into your - debian/rules file. If your package contains only - compiled binaries and libraries (but no scripts), you can - use a command such as: + If there are both concrete and virtual packages of the same + name, then the dependency may be satisfied (or the conflict + caused) by either the concrete package with the name in + question or any other concrete package which provides the + virtual package with the name in question. This is so that, + for example, supposing we have -dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* \ - debian/tmp/usr/lib/* +Package: foo +Depends: bar - 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. -

- + and someone else releases an enhanced version of the + bar package (for example, a non-US variant), they + can say: + +Package: bar-plus +Provides: bar + + and the bar-plus package will now also satisfy the + dependency for the foo package.

- This command puts the dependency information into the - debian/substvars file, which is then used by - dpkg-gencontrol. You will need to place a - ${shlib:Depends} variable in the Depends - field in the control file for this to work. + If a dependency or a conflict has a version number attached + then only real packages will be considered to see whether + the relationship is satisfied (or the prohibition violated, + for a conflict) - it is assumed that a real package which + provides the virtual package is not of the "right" version. + So, a Provides field may not contain version + numbers, and the version number of the concrete package + which provides a particular virtual package will not be + looked at when considering a dependency on or conflict with + the virtual package name.

- 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 - ). + It is likely that the ability will be added in a future + release of dpkg to specify a version number for + each virtual package it provides. This feature is not yet + present, however, and is expected to be used only + infrequently.

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

- The shlibs File Format - -

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

+ Overwriting files and replacing + packages - Replaces

- 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. + Packages can declare in their control file that they should + overwrite files in certain other packages, or completely + replace other packages. The Replaces control file + field has these two distinct purposes.

-

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

+ Overwriting files in other packages -

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

- This can be determined using the command - -objdump -p /usr/lib/libz.so.1.1.3 | grep SONAME - -

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

+

+ Firstly, as mentioned before, it is usually an error for a + package to contain files which are on the system in + another package. +

-

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

+

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

-

- 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 a package is completely replaced in this way, so that + dpkg does not know of any files it still + contains, it is considered to have "disappeared". It will + be marked as not wanted on the system (selected for + removal) and not installed. Any 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 . + +

+ Replaces is a one way relationship -- you have to + install the replacing package after the replaced + package. +

+ +

- - Providing a shlibs file +

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

-

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

- This is what dh_makeshlibs in the - debhelper suite does. -

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

+

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

-

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

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

+ Secondly, Replaces allows the packaging system to + resolve which package should be removed when there is a + conflict - see . This usage only + takes effect when the two packages do conflict, + so that the two usages of this field do not interfere with + each other. +

+ +

+ In this situation, the package declared as being replaced + can be a virtual package, so for example, all mail + transport agents (MTAs) would have the following fields in + their control files: + +Provides: mail-transport-agent +Conflicts: mail-transport-agent +Replaces: mail-transport-agent + + ensuring that only one MTA can be installed at any one + time. + - - Writing the debian/shlibs.local file + + Relationships between source and binary packages - + Build-Depends, Build-Depends-Indep, + Build-Conflicts, Build-Conflicts-Indep +

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

+ Source packages that require certain binary packages to be + installed or absent at the time of building the package + can declare relationships to those binary packages. +

-

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

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

+ +

+ Build-dependencies on "build-essential" binary packages can be + omitted. Please see for more information.

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

+ If you make "build-arch" or "binary-arch", you need + Build-Depends. If you make "build-indep" or + "binary-indep", you need Build-Depends and + Build-Depends-Indep. If you make "build" or "binary", + you need both. +

+

+ There is no Build-Depends-Arch; the autobuilders will + only need the Build-Depends if they know how to build + only build-arch and binary-arch. Anyone building the + build-indep/binary-indep targets is basically assumed to + be building the whole package and so installs all build + dependencies. +

+

+ The purpose of the original split, I recall, was so that + the autobuilders wouldn't need to install extra packages + needed only for the binary-indep targets. But without a + build-arch/build-indep split, this didn't work, since + most of the work is done in the build target, not in the + binary target. +

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

+ - - The Operating System + - - Filesystem hierarchy + Shared libraries - - Filesystem Structure +

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

-

- The location of all installed files and directories must - comply with the Filesystem Hierarchy Standard (FHS), - version 2.1, except where doing so would violate other - terms of Debian Policy. The version of this document - referred here can be found in the debian-policy - package or on - alongside this manual (or, if - you have the debian-policy installed, - you can try ). The - latest version, which may be a more recent version, may - be found on - . - Specific questions about following the standard may be - asked on the debian-devel mailing list, or - referred to the FHS mailing list (see the - for - more information). -

- +

+ Packages involving shared libraries should be split up into + several binary packages. This section mostly deals with how + this separation is to be accomplished; rules for files within + the shared library packages are in instead. +

- - Site-specific programs + + Run-time shared libraries -

- As mandated by the FHS, packages must not place any - files in /usr/local, either by putting them in - the file system archive to be unpacked by dpkg - or by manipulating them in their maintainer scripts. -

+

+ The run-time shared library needs to be placed in a package called + librarynamesoversion, where + soversion is the version number in the + soname of the shared library + The soname is the shared object name: it's the thing + that has to match exactly between building an executable + and running it for the dynamic linker to be able run the + program. For example, if the soname of the library is + libfoo.so.6, the library package would be + called libfoo6. + . + Alternatively, if it would be confusing to directly append + soversion to libraryname (e.g. because + libraryname itself ends in a number), you may use + libraryname-soversion and + libraryname-soversion-dev + instead. +

-

- However, the package may create empty directories below - /usr/local so that the system administrator knows - where to place site-specific files. These directories - should be removed on package removal if they are - empty. -

+

+ If you have several shared libraries built from the same + source tree you may lump them all together into a single + shared library package, provided that you change all of + their sonames at once (so that you don't get filename + clashes if you try to install different versions of the + combined shared libraries package). +

-

- Note, that this applies only to directories below - /usr/local, not in /usr/local. - Packages must not create sub-directories in the directory - /usr/local itself, except those listed in FHS, - section 4.5. However, you may create directories below - them as you wish. You must not remove any of the - directories listed in 4.5, even if you created them. -

+

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

-

- Since /usr/local can be mounted read-only from a - remote server, these directories must be created and - removed by the postinst and prerm - maintainer scripts and not be included in the - .deb archive. These scripts must not fail if - either of these operations fail. -

+

+ Shared libraries should not be installed executable, since + the dynamic linker does not require this and trying to + execute a shared library usually results in a core dump. +

-

- For example, the emacsen-common package could - contain something like - -if [ ! -e /usr/local/share/emacs ] -then - if mkdir /usr/local/share/emacs 2>/dev/null - then - chown root:staff /usr/local/share/emacs - chmod 2775 /usr/local/share/emacs - fi -fi - - in its postinst script, and - -rmdir /usr/local/share/emacs/site-lisp 2>/dev/null || true -rmdir /usr/local/share/emacs 2>/dev/null || true - - in the prerm script. (Note that this form is - used to ensure that if the script is interrupted, the - directory /usr/local/share/emacs will still be - removed.) -

+

+ The run-time library package should include the symbolic link that + ldconfig would create for the shared libraries. + For example, the libgdbm3 package should include + a symbolic link from /usr/lib/libgdbm.so.3 to + libgdbm.so.3.0.0. This is needed so that the dynamic + linker (for example ld.so or + ld-linux.so.*) can find the library between the + time that dpkg installs it and the time that + ldconfig is run in the postinst + script. + The package management system requires the library to be + placed before the symbolic link pointing to it in the + .deb file. This is so that when + dpkg comes to install the symlink + (overwriting the previous symlink pointing at an older + version of the library), the new shared library is already + in place. In the past, this was achieved by creating the + library in the temporary packaging directory before + creating the symlink. Unfortunately, this was not always + effective, since the building of the tar file in the + .deb depended on the behavior of the underlying + file system. Some file systems (such as reiserfs) reorder + the files so that the order of creation is forgotten. + Since version 1.7.0, dpkg + reorders the files itself as necessary when building a + package. Thus it is no longer important to concern + oneself with the order of file creation. + +

-

- If you do create a directory in /usr/local for - local additions to a package, you should ensure that - settings in /usr/local take precedence over the - equivalents in /usr. -

+ + ldconfig -

- However, because /usr/local and its contents are - for exclusive use of the local administrator, a package - must not rely on the presence or absence of files or - directories in /usr/local for normal operation. -

+

+ 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 use ldconfig to update the shared library + system. +

-

- The /usr/local directory itself and all the - subdirectories created by the package should (by default) have - permissions 2775 (group-writable and set-group-id) and be - owned by root.staff. -

- +

+ The package must call ldconfig in the + postinst script if the first argument is + configure; the postinst script may + optionally invoke ldconfig at other times. The + package should call ldconfig in the + postrm script if the first argument is + remove. The maintainer scripts must not invoke + ldconfig under any circumstances other than those + described in this paragraph. +

+ During install or upgrade, the preinst is called before + the new files are installed, so calling "ldconfig" is + pointless. The preinst of an existing package can also be + called if an upgrade fails. However, this happens during + the critical time when a shared libs may exist on-disk + under a temporary name. Thus, it is dangerous and + forbidden by current policy to call "ldconfig" at this + time. +

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

- - +

+ When a package is installed or upgraded, "postinst + configure" runs after the new files are safely on-disk. + Since it is perfectly safe to invoke ldconfig + unconditionally in a postinst, it is OK for a package to + simply put ldconfig in its postinst without checking the + argument. The postinst can also be called to recover from + a failed upgrade. This happens before any new files are + unpacked, so there is no reason to call "ldconfig" at this + point. +

- - Users and groups +

+ For a package that is being removed, prerm is + called with all the files intact, so calling ldconfig is + useless. The other calls to "prerm" happen in the case of + upgrade at a time when all the files of the old package + are on-disk, so again calling "ldconfig" is pointless. +

- - Introduction -

- The Debian system can be configured to use either plain or - shadow passwords. -

+

+ postrm, on the other hand, is called with the "remove" + argument just after the files are removed, so this is the + proper time to call "ldconfig" to notify the system of the + fact shared libraries from the package are removed. + The postrm can be called at several other times. At the + time of "postrm purge", "postrm abort-install", or "postrm + abort-upgrade", calling "ldconfig" is useless because the + shared lib files are not on-disk. However, when "postrm" + is invoked with arguments "upgrade", "failed-upgrade", or + "disappear", a shared lib may exist on-disk under a + temporary filename. +

+ +

+ -

- Some user ids (UIDs) and group ids (GIDs) are reserved - globally for use by certain packages. Because some - packages need to include files which are owned by these - users or groups, or need the ids compiled into binaries, - these ids must be used on any Debian system only for the - purpose for which they are allocated. This is a serious - restriction, and we should avoid getting in the way of - local administration policies. In particular, many sites - allocate users and/or local system groups starting at 100. -

+ -

- Apart from this we should have dynamically allocated ids, - which should by default be arranged in some sensible - order, but the behavior should be configurable. -

+ + Run-time support programs -

- Packages other than base-passwd must not modify - /etc/passwd, /etc/shadow, - /etc/group or /etc/gshadow. -

- +

+ If your package has some run-time support programs which use + the shared library you must not put them in the shared + library package. If you do that then you won't be able to + install several versions of the shared library without + getting filename clashes. +

- - UID and GID classes -

- The UID and GID numbers are divided into classes as - follows: - - 0-99: - -

- Globally allocated by the Debian project, the same - on every Debian system. These ids will appear in - the passwd and group files of all - Debian systems, new ids in this range being added - automatically as the base-passwd package is - updated. -

+

+ Instead, either create another package for the runtime binaries + (this package might typically be named + libraryname-runtime; note the absence + of the soversion in the package name), or if the + development package is small, include them in there. +

+ -

- Packages which need a single statically allocated - uid or gid should use one of these; their - maintainers should ask the base-passwd - maintainer for ids. -

- + + Static libraries - 100-999: - -

- Dynamically allocated system users and groups. - Packages which need a user or group, but can have - this user or group allocated dynamically and - differently on each system, should use adduser - --system to create the group and/or user. - adduser will check for the existence of - the user or group, and if necessary choose an unused - id based on the ranges specified in - adduser.conf. -

- +

+ The static library (libraryname.a) + is usually provided in addition to the shared version. + It is placed into the development package (see below). +

- 1000-29999: - -

- Dynamically allocated user accounts. By default - adduser will choose UIDs and GIDs for - user accounts in this range, though - adduser.conf may be used to modify this - behavior. -

- +

+ In some cases, it is acceptable for a library to be + available in static form only; these cases include: + + libraries for languages whose shared library support + is immature or unstable + libraries whose interfaces are in flux or under + development (commonly the case when the library's + major version number is zero, or where the ABI breaks + across patchlevels) + libraries which are explicitly intended to be + available only in static form by their upstream + author(s) + +

- 30000-59999: - -

Reserved.

- + + Development files - 60000-64999: - -

- Globally allocated by the Debian project, but only - created on demand. The ids are allocated centrally - and statically, but the actual accounts are only - created on users' systems on demand. -

+

+ The development files associated to a shared library need to be + placed in a package called + librarynamesoversion-dev, + or if you prefer only to support one development version at a + time, libraryname-dev. +

-

- These ids are for packages which are obscure or - which require many statically-allocated ids. These - packages should check for and create the accounts in - /etc/passwd or /etc/group (using - adduser if it has this facility) if - necessary. Packages which are likely to require - further allocations should have a `hole' left after - them in the allocation, to give them room to - grow. -

- +

+ In case several development versions of a library exist, you may + need to use dpkg's Conflicts mechanism (see + ) to ensure that the user only installs one + development version at a time (as different development versions are + likely to have the same header files in them, which would cause a + filename clash if both were installed). +

- 65000-65533: - -

Reserved.

- +

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

+ - 65534: - -

- User nobody. The corresponding gid refers - to the group nogroup. -

- + + Dependencies between the packages of the same library - 65535: - -

- (uid_t)(-1) == (gid_t)(-1) must - not be used, because it is the error return - sentinel value. -

- - -

- +

+ Typically the development version should have an exact + version dependency on the runtime library, to make sure that + compilation and linking happens correctly. The + ${Source-Version} substitution variable can be + useful for this purpose. +

- - System run levels and init.d scripts + + Dependencies between the library and other packages - + the shlibs system - - Introduction +

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

-

- The /etc/init.d directory contains the scripts - executed by init at boot time and when the - init state (or `runlevel') is changed (see ). -

+

+ 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 is used to do this. The only + change this makes to package building is that + dpkg-shlibdeps must also be run on shared + libraries, whereas in the past this was unnecessary. + The rest of this footnote explains the advantage that + this method gives. +

-

- There are at least two different, yet functionally - equivalent, ways of handling these scripts. For the sake - of simplicity, this document describes only the symbolic - link method. However, it must not be assumed by maintainer - scripts that this method is being used, and any automated - manipulation of the various runlevel behaviours by - maintainer scripts must be performed using - update-rc.d as described below and not by - manually installing or removing symlinks. For information - on the implementation details of the other method, - implemented in the file-rc package, please refer - to the documentation of that package. -

+

+ We say that a binary foo directly uses + a library libbar if it is explicitly linked + with that library (that is, it uses the flag + -lbar during the linking stage). Other + libraries that are needed by libbar are linked + indirectly to foo, and the dynamic + linker will load them automatically when it loads + libbar. A package should depend on + the libraries it directly uses, and the dependencies for + those libraries should automatically pull in the other + libraries. +

-

- These scripts are referenced by symbolic links in the - /etc/rcn.d directories. When changing - runlevels, init looks in the directory - /etc/rcn.d for the scripts it should - execute, where n is the runlevel that - is being changed to, or S for the boot-up - scripts. -

+

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

-

- The names of the links all have the form - Smmscript or - Kmmscript where - mm is a two-digit number and script - is the name of the script (this should be the same as the - name of the actual script in /etc/init.d). -

+

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

+ +

-

- When init changes runlevel first the targets - of the links whose names start with a K are - executed, each with the single argument stop, - followed by the scripts prefixed with an S, each - with the single argument start. (The links are - those in the /etc/rcn.d directory - corresponding to the new runlevel.) The K links - are responsible for killing services and the S - link for starting services upon entering the runlevel. -

+

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

-

- For example, if we are changing from runlevel 2 to - runlevel 3, init will first execute all of the K - prefixed scripts it finds in /etc/rc3.d, and then - all of the S prefixed scripts in that directory. - The links starting with K will cause the - referred-to file to be executed with an argument of - stop, and the S links with an argument - of start. -

+ + The shlibs files present on the system -

- The two-digit number mm is used to determine - the order in which to run the scripts: 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 another. For example, the name - server bind might need to be started before - the news server inn so that inn - can set up its 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 - -

+

+ 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 two runlevels 0 (halt) and 6 (reboot) are slightly - different. In these runlevels, the links with an - S prefix are still called after those with a - K prefix, but they too are called with the single - argument stop. -

+

+ + +

debian/shlibs.local

-

- Also, if the script name ends .sh, the script - will be sourced in runlevel S rather that being - run in a forked subprocess, but will be explicitly run by - sh in all other runlevels. -

- +

+ This lists overrides for this package. Its use is + described below (see ). +

+ - - Writing the scripts + +

/etc/dpkg/shlibs.override

-

- Packages that include daemons for system services should - place scripts in /etc/init.d to start or stop - services at boot time or during a change of runlevel. - These scripts should be named - /etc/init.d/package, and they should - accept one argument, saying what to do: +

+ This lists global overrides. This list is normally + empty. It is maintained by the local system + administrator. +

+ - - start -

start the service,

 + +

DEBIAN/shlibs files in the "build directory"

- stop -

stop the service,

 +

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

+ - restart -

stop and restart the service,

 + +

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

- reload -

cause the configuration of the service to be - reloaded without actually stopping and restarting - the service,

 +

+ These are the shlibs files corresponding to + all of the packages installed on the system, and are + maintained by the relevant package maintainers. +

+ - force-reload -

cause the configuration to be reloaded if the - service supports this, otherwise restart the - service.

 - + +

/etc/dpkg/shlibs.default

- The start, stop, restart, and - force-reload options should be supported by all - scripts in /etc/init.d, the reload - option is optional.

+

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

+ + +

+ -

- The init.d scripts should ensure that they will - behave sensibly if invoked with start when the - service is already running, or with stop when it - isn't, and that they don't kill unfortunately-named user - processes. The best way to achieve this is usually to use - start-stop-daemon.

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

- If a service reloads its configuration automatically (as - in the case of cron, for example), the - reload option of the init.d script - should behave as if the configuration has been reloaded - successfully.

- -

- The /etc/init.d scripts must be treated as - configuration files, either (if they are present in the - package, that is, in the .deb file) by marking them as - conffiles, or, (if they do not exist in the .deb) - by managing them 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 - 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 the next - package upgrade. -

- -

- These scripts should not fail obscurely when the - configuration files remain but the package has been - removed, as configuration files remain on the system after - the package has been removed. Only when dpkg - is executed with the --purge option will - configuration files be removed. In particular, as the - /etc/init.d/package script itself is - usually a conffile, it will remain on the system - if 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 - -

- -

- Often there are some variables in the init.d - scripts whose values control the behaviour of the scripts, - and which a system administrator is likely to want to - change. As the scripts themselves are frequently - conffiles, modifying them requires that the - administrator merge in their changes each time the package - is upgraded and the conffile changes. To ease - the burden on the system administrator, such configurable - values should not be placed directly in the script. - Instead, they should be placed in a file in - /etc/default, which typically will have the same - base name as the init.d script. This extra file - should be sourced by the script when the script runs. It - must contain only variable settings and comments in POSIX - sh format. It may either be a - conffile or a configuration file maintained by - the package maintainer scripts. See - for more details. -

+

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

-

- To ensure that vital configurable values are always - available, the init.d script should set default - values for each of the shell variables it uses, either - before sourcing the /etc/default/ file or - afterwards using something like the : - ${VAR:=default} syntax. Also, the init.d - script must behave sensibly and not fail if the - /etc/default file is deleted. -

- +

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

- - Interfacing with the initscript system +

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

-

- Maintainers should use the abstraction layer provided by - the update-rc.d and invoke-rc.d - programs to deal with initscripts in their packages' - scripts such as postinst, prerm - and postrm. -

-

- Directly managing the /etc/rc?.d links and directly - invoking the /etc/init.d/ initscripts should - be done only by packages providing the initscript - subsystem (such as sysvinit and - file-rc). +

+ 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 dpkg-shlibdeps, please see + and + . +

+ - - Managing the links + + The shlibs File Format -

- The program update-rc.d is provided for - package maintainers to arrange for the proper creation and - removal of /etc/rcn.d symbolic links, - or their functional equivalent if another method is being - used. This may be used by maintainers in their packages' - postinst and postrm scripts.

+

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

-

- You must not include any /etc/rcn.d - symbolic links in the actual archive or manually create or - remove the symbolic links in maintainer scripts; you must - use the update-rc.d program instead. (The - former will fail if an alternative method of maintaining - runlevel information is being used.) You must not include - the /etc/rcn.d directories themselves - in the archive either. (Only the sysvinit - package may do so.) -

+

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

-

- By default update-rc.d will start services in - each of the multi-user state runlevels (2, 3, 4, and 5) - and stop them in the halt runlevel (0), the single-user - runlevel (1) and the reboot runlevel (6). The system - administrator will have the opportunity to customize - runlevels by simply adding, moving, or removing the - symbolic links in /etc/rcn.d if - symbolic links are being used, or by modifying - /etc/runlevel.conf if the file-rc method - is being used. -

+

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

-

- To get the default behavior for your package, put in your - postinst script +

+ 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. + This can be determined using the command - update-rc.d package defaults +objdump -p /usr/lib/libz.so.1.1.3 | grep SONAME - and in your postrm - - if [ "$1" = purge ]; then - update-rc.d package remove - fi - . Note that is your package changes runlevels - or priority, you may have to remove and recreate the - links, since otherwise the old links may - persist. Refer to the documentation of - update-rc.d

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

-

- This will use a default sequence number of 20. If it does - not matter when or in which order the init.d - script is run, use this default. If it does, then you - should talk to the maintainer of the sysvinit - package or post to debian-devel, and they will - help you choose a number. -

+

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

-

- For more information about using update-rc.d, - please consult its manpage . -

- +

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

+ - - Running initscripts -

- The program invoke-rc.d is provided to make - it easier for package maintainers to properly invoke an - initscript, obeying runlevel and other locally-defined - constraints that might limit a package's right to start, - stop and otherwise manage services. This program may be - used by maintainers in their packages' scripts. -

-

- The use of invoke-rc.d to invoke the - /etc/init.d/* initscripts is strongly - recommended -

- In the future, the use of invoke-rc.d to invoke - initscripts shall be made mandatory. Maintainers are - advised to switch to invoke-rc.d as soon as - possible.

- , instead of calling them directly. -

+ + Providing a shlibs file -

- By default, invoke-rc.d will pass any - action requests (start, stop, reload, restart...) to the - /etc/init.d script, filtering out requests - to start or restart a service out of its intended - runlevels. -

-

- Most packages will simply need to change: - /etc/init.d/<package> - <action> in their postinst - and prerm scripts to: - - if [ -x /usr/sbin/invoke-rc.d ] ; then - invoke-rc.d package <action> - else - /etc/init.d/package <action> - fi -

-

- A package should register its initscript services using - update-rc.d before it tries to invoke them - using invoke-rc.d. Invocation of - unregistered services may fail. -

-

- For more information about using - invoke-rc.d, please consult its manpage - . -

- - +

+ 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, + This is what dh_makeshlibs in the + debhelper suite does. + + since the debian/shlibs file itself is ignored by + dpkg-shlibdeps. +

+

+ As dpkg-shlibdeps reads the + DEBIAN/shlibs files in all of the binary packages + being built from this source package, all of the + DEBIAN/shlibs files should be installed before + dpkg-shlibdeps is called on any of the binary + packages. +

+ - - Boot-time initialization + + Writing the debian/shlibs.local file -

- There used to be another directory, /etc/rc.boot, - which contained scripts which were run once per machine - boot. This has been deprecated in favour of links from - /etc/rcS.d to files in /etc/init.d as - described in . Packages must not - place files in /etc/rc.boot.

+

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

- - Example +

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

-

- The bind DNS (nameserver) package wants to - make sure that the nameserver is running in multiuser - runlevels, and is properly shut down with the system. It - puts a script in /etc/init.d, naming the script - appropriately bind. As you can see, the script - interprets the argument reload to send the - nameserver a HUP signal (causing it to reload its - configuration); this way the system administrator can say - /etc/init.d/bind reload to reload the name - server. The script has one configurable value, which can - be used to pass parameters to the named program at - startup; this value is read from - /etc/default/bind (see below). -

+

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

+ -

- -#!/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 + The Operating System -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 + + Filesystem hierarchy -exit 0 - -

+ + + Filesystem Structure

- Complementing the above init script is a configuration - file /etc/default/bind, which contains - configurable parameters used by the script. This would be - created by the postinst script if it was not - already present, and removed on purge by the - postrm script. - -# Specified parameters to pass to named. See named(8). -# You may uncomment the following line, and edit to taste. -#PARAMS="-u nobody" - + The location of all installed files and directories must + comply with the Filesystem Hierarchy Standard (FHS), + version 2.1, except where doing so would violate other + terms of Debian Policy. The version of this document + referred here can be found in the debian-policy + package or on + alongside this manual (or, if + you have the debian-policy installed, + you can try ). The + latest version, which may be a more recent version, may + be found on + . + Specific questions about following the standard may be + asked on the debian-devel mailing list, or + referred to the FHS mailing list (see the + for + more information).

+ + + + Site-specific programs

- Another example on which you can base your - /etc/init.d scripts is found in - /etc/init.d/skeleton. + As mandated by the FHS, packages must not place any + files in /usr/local, either by putting them in + the file system archive to be unpacked by dpkg + or by manipulating them in their maintainer scripts.

- If this package is happy with the default setup from - 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 - - And in its postrm, to remove the links when the - package is purged: - -if [ "$1" = purge ]; then - update-rc.d bind remove >/dev/null -fi - + However, the package may create empty directories below + /usr/local so that the system administrator knows + where to place site-specific files. These directories + should be removed on package removal if they are + empty.

- - - - Console messages from init.d scripts +

+ Note, that this applies only to directories below + /usr/local, not in /usr/local. + Packages must not create sub-directories in the directory + /usr/local itself, except those listed in FHS, + section 4.5. However, you may create directories below + them as you wish. You must not remove any of the + directories listed in 4.5, even if you created them. +

-

- This section describes the formats to be used for messages - written to standard output by the /etc/init.d - scripts. The intent is to improve the consistency of - Debian's startup and shutdown look and feel. For this - reason, please look very carefully at the details. We want - the messages to have the same format in terms of wording, - spaces, punctuation and case of letters. -

- -

- Here is a list of overall rules that you should use when you - create output messages. They can be useful if you have a - non-standard message that is not covered specifically in the - sections below. -

- -

- - -

- Every message should fit in one line (fewer than 80 - characters), start with a capital letter and end with - a period (.) and line feed ("\n"). -

- - - -

- If you want to express that the computer is working on - something (that is, performing a specific task, not - starting or stopping a program), we use an "ellipsis" - (three dots: ...). Note that we don't insert - spaces before or after the dots. If the task has been - completed we write done. and a line feed. -

- - - -

- Design your messages as if the computer is telling you - 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. - - just say - -Starting network daemons: nfsd mountd. - -

- - -

+

+ Since /usr/local can be mounted read-only from a + remote server, these directories must be created and + removed by the postinst and prerm + maintainer scripts and not be included in the + .deb archive. These scripts must not fail if + either of these operations fail. +

-

- There are standard message formats for the following - situations. They should be used by the init.d - scripts. -

+

+ For example, the emacsen-common package could + contain something like + +if [ ! -e /usr/local/share/emacs ] +then + if mkdir /usr/local/share/emacs 2>/dev/null + then + chown root:staff /usr/local/share/emacs + chmod 2775 /usr/local/share/emacs + fi +fi + + in its postinst script, and + +rmdir /usr/local/share/emacs/site-lisp 2>/dev/null || true +rmdir /usr/local/share/emacs 2>/dev/null || true + + in the prerm script. (Note that this form is + used to ensure that if the script is interrupted, the + directory /usr/local/share/emacs will still be + removed.) +

-

- - -

When daemons are started

+

+ If you do create a directory in /usr/local for + local additions to a package, you should ensure that + settings in /usr/local take precedence over the + equivalents in /usr. +

-

- 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-n. - - The description should describe the - subsystem the daemon or set of daemons are part of, - while daemon-1 up to daemon-n - denote each daemon's name (typically the file name of - the program). -

+

+ However, because /usr/local and its contents are + for exclusive use of the local administrator, a package + must not rely on the presence or absence of files or + directories in /usr/local for normal operation. +

-

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

+

+ The /usr/local directory itself and all the + subdirectories created by the package should (by default) have + permissions 2775 (group-writable and set-group-id) and be + owned by root.staff. +

+ -

- This can be achieved by saying - -echo -n "Starting printer spooler: lpd" -start-stop-daemon --start --quiet --exec /usr/sbin/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 "." - - This makes it possible for the user to see what takes - so long and when the final daemon has been started. - You should be careful where to put spaces: in the - 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. -

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

+ + - -

When a system parameter is being set

+ + Users and groups -

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

+ + Introduction +

+ The Debian system can be configured to use either plain or + shadow passwords. +

-

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

+

+ Some user ids (UIDs) and group ids (GIDs) are reserved + globally for use by certain packages. Because some + packages need to include files which are owned by these + users or groups, or need the ids compiled into binaries, + these ids must be used on any Debian system only for the + purpose for which they are allocated. This is a serious + restriction, and we should avoid getting in the way of + local administration policies. In particular, many sites + allocate users and/or local system groups starting at 100. +

-

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

- +

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

- -

When a daemon is stopped or restarted

+

+ Packages other than base-passwd must not modify + /etc/passwd, /etc/shadow, + /etc/group or /etc/gshadow. +

+ -

- When you stop or restart a daemon, you should issue a - message identical to the startup message, except that - Starting is replaced with Stopping - or Restarting respectively. -

+ + UID and GID classes +

+ The UID and GID numbers are divided into classes as + follows: + + 0-99: + +

+ Globally allocated by the Debian project, the same + on every Debian system. These ids will appear in + the passwd and group files of all + Debian systems, new ids in this range being added + automatically as the base-passwd package is + updated. +

-

- For example, stopping the printer daemon will like - like this: - -Stopping printer spooler: lpd. - -

- +

+ Packages which need a single statically allocated + uid or gid should use one of these; their + maintainers should ask the base-passwd + maintainer for ids. +

+ - -

When something is executed

- -

- There are several examples where you have to run a - program at system startup or shutdown to perform a - specific task, for example, setting the system's clock - using netdate or killing all processes - when the system shuts down. Your message should look - like this: - -Doing something very useful...done. - - You should print the done. immediately after - the job has been completed, so that the user is - informed why she has to wait. You can get this - behavior by saying - -echo -n "Doing something very useful..." -do_something -echo "done." - - in your script. -

- - - -

When the configuration is reloaded

- -

- When a daemon is forced to reload its configuration - files you should use the following format: - -Reloading description configuration...done. - - where description is the same as in the - daemon starting message. -

- - -

- - - - Cron jobs - -

- Packages must not modify the configuration file - /etc/crontab, and they must not modify the files in - /var/spool/cron/crontabs.

- -

- 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 or more of the following directories: - -/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, - respectively. The exact times are listed in - /etc/crontab.

- -

- All files installed in any of these directories must be - scripts (e.g., shell scripts or Perl scripts) so that they - can easily be modified by the local system administrator. - In addition, they should be treated as configuration - files. -

- -

- If a certain job has to be executed more frequently than - daily, the package should install a file - /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 - /etc/cron.d directory are not handled by - anacron. Thus, you should only use this - directory for jobs which may be skipped if the system is not - running.)

- -

- The scripts or crontab entries in these directories should - check if all necessary programs are installed before they - try to execute them. Otherwise, problems will arise when a - package was removed but not purged since configuration files - are kept on the system in this situation.

- - - - Menus - -

- Menu entries should follow the current menu policy found in - the menu-policy files in the debian-policy - package. It may also be found on the Debian FTP site - ftp.debian.org as the file - /debian/doc/package-developer/menu-policy.txt.gz, - or in the equivalent location on your local mirror. -

- -

- The Debian menu package provides a standard - interface between packages providing applications and - documents, and menu programs (either X window - managers or text-based menu programs such as - pdmenu). -

- -

- All packages that provide applications that need not be - passed any special command line arguments for normal - operation should register a menu entry for those - applications, so that users of the menu package - will automatically get menu entries in their window - managers, as well in shells like pdmenu.

- -

- Please also refer to the Debian Menu System - documentation that comes with the menu package for - information about how to register your applications and web - documents. -

- - - - Multimedia handlers - -

- Packages which provide the ability to view/show/play, - compose, edit or print MIME types should register themselves - as such following the current MIME support policy found in - the mime-policy files in the debian-policy - package. It may also be found on the Debian FTP site - ftp.debian.org as the file - /debian/doc/package-developer/mime-policy.txt.gz, - or in the equivalent location on your local mirror. -

- -

- MIME (Multipurpose Internet Mail Extensions, RFCs 2045-2049) - is a mechanism for encoding files and data streams and - providing meta-information about them, in particular their - type (e.g. audio or video) and format (e.g. PNG, HTML, - MP3). -

- -

- Registration of MIME type handlers allows programs like mail - user agents and web browsers to to invoke these handlers to - view, edit or display MIME types they don't support - directly. -

- - - - Keyboard configuration - -

- To achieve a consistent keyboard configuration so that all - applications interpret a keyboard event the same way, all - programs in the Debian distribution must be configured to - comply with the following guidelines. -

- -

- The following keys must have the specified interpretations: - - - <-- -

delete the character to the left of the cursor

- - Delete -

delete the character to the right of the cursor

 - - Control+H -

emacs: the help prefix

 - - - The interpretation of any keyboard events should be - independent of the terminal that is used, be it a virtual - console, an X terminal emulator, an rlogin/telnet session, - etc. -

- -

- The following list explains how the different programs - should be set up to achieve this: -

- -

- -

<-- generates KB_BackSpace - in X.

- -

Delete generates KB_Delete in - X.

 - - -

- X translations are set up to make - KB_Backspace generate ASCII DEL, and to make - KB_Delete generate ESC [ 3 ~ (this - is the vt220 escape code for the `delete character' - key). This must be done by loading the X resources - using xrdb on all local X displays, not - using the application defaults, so that the - translation resources used correspond to the - xmodmap settings.

 - - -

- The Linux console is configured to make - <-- generate DEL, and Delete - generate ESC [ 3 ~.

 - - -

- X applications are configured so that < - deletes left, and Delete deletes right. Motif - applications already work like this.

 - -

Terminals should have stty erase ^? .

 - - -

- The xterm terminfo entry should have ESC - [ 3 ~ for kdch1, just as for - TERM=linux and TERM=vt220.

 - - -

- Emacs is programmed to map KB_Backspace or - the stty erase character to - delete-backward-char, and KB_Delete - or kdch1 to delete-forward-char, and - ^H to help as always.

 - - -

- Other applications use the stty erase - character and kdch1 for the two delete keys, - with ASCII DEL being `delete previous character' and - kdch1 being `delete character under - cursor'.

 - - -

- -

- This will solve the problem except for the following - cases: -

- -

- - -

- Some terminals have a <-- key that cannot - be made to produce anything except ^H. On - these terminals Emacs help will be unavailable on - ^H (assuming that the stty erase - character takes precedence in Emacs, and has been set - correctly). M-x help or F1 (if - available) can be used instead.

- - -

- Some operating systems use ^H for stty - erase. However, modern telnet versions and all - rlogin versions propagate stty settings, and - almost all UNIX versions honour stty erase. - Where the stty settings are not propagated - correctly, things can be made to work by using - stty manually.

 - - -

- Some systems (including previous Debian versions) use - xmodmap to arrange for both - <-- and Delete to generate - KB_Delete. We can change the behavior of - their X clients using the same X resources that we use - to do it for our own clients, or configure our clients - using their resources when things are the other way - around. On displays configured like this - Delete will not work, but <-- - will.

 - - -

- Some operating systems have different kdch1 - settings in their terminfo database for - xterm and others. On these systems the - Delete key will not work correctly when you - log in from a system conforming to our policy, but - <-- will.

 - -

- - - - Environment variables - -

- A program must not depend on environment variables to get - reasonable defaults. (That's because these environment - variables would have to be set in a system-wide - configuration file like /etc/profile, which is not - supported by all shells.)

- -

- If a program usually depends on environment variables for its - configuration, the program should be changed to fall back to - a reasonable default configuration if these environment - variables are not present. If this cannot be done easily - (e.g., if the source code of a non-free program is not - available), the program must be replaced by a small - `wrapper' shell script which sets the environment variables - if they are not already defined, and calls the original program.

- -

- 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 "$@" - -

- -

- Furthermore, as /etc/profile is a configuration - file of the base-files package, other packages must not - put any environment variables or other commands into that - file.

- - - - - Files - - - Binaries - -

- Two different packages must not install programs with - different functionality but with the same filenames. (The - case of two programs having the same functionality but - different implementations is handled via `alternatives' or - the `Conflicts' mechanism. See and - respectively.) If this case happens, - one of the programs must be renamed. The maintainers should - report this to the debian-devel mailing list and - try to find a consensus about which program will have to be - renamed. If a consensus cannot be reached, both - programs must be renamed. -

- -

- By default, when a package is being built, any binaries - created should include debugging information, as well as - being compiled with optimization. You should also turn on - as many reasonable compilation warnings as possible; this - makes life easier for porters, who can then look at build - logs for possible problems. For the C programming language, - this means the following compilation parameters should be - used: - -CC = gcc -CFLAGS = -O2 -g -Wall # sane warning options vary between programs -LDFLAGS = # none -install -s # (or use strip on the files in debian/tmp) - -

- -

- Note that by default all installed binaries should be stripped, - either by using the -s flag to - install, or by calling strip on - the binaries after they have been copied into - debian/tmp but before the tree is made into a - package.

- -

- Although binaries in the build tree should be compiled with - debugging information by default, it can often be difficult - to debug programs if they are also subjected to compiler - optimization. For this reason, it is recommended to support - the standardized environment - variable DEB_BUILD_OPTIONS. This variable can - contain several flags to change how a package is compiled - and built. -

-

- - noopt - -

- The presence of this string means that the package - should be complied with a minimum of optimization. - For C programs, it is best to add -O0 - to CFLAGS (although this is usually the - default). Some programs might fail to build or run at - this level of optimization; it may be necessary to - use -O1, for example. -

- - nostrip - -

- This string means that the debugging symbols should - not be stripped from the binary during installation, - so that debugging information may be included in the package. -

- - -

-

- The following makefile snippet is an example of how one may - implement the build options; you will probably have to - massage this example in order to make it work for your - package. - -CFLAGS = -Wall -g -INSTALL = install -INSTALL_FILE = $(INSTALL) -p -o root -g root -m 644 -INSTALL_PROGRAM = $(INSTALL) -p -o root -g root -m 755 -INSTALL_SCRIPT = $(INSTALL) -p -o root -g root -m 755 -INSTALL_DIR = $(INSTALL) -p -d -o root -g root -m 755 - -ifneq (,$(findstring noopt,$(DEB_BUILD_OPTIONS))) -CFLAGS += -O0 -else -CFLAGS += -O2 -endif -ifeq (,$(findstring nostrip,$(DEB_BUILD_OPTIONS))) -INSTALL_PROGRAM += -s -endif - -

- -

- It is up to the package maintainer to decide what - compilation options are best for the package. Certain - binaries (such as computationally-intensive programs) will - function better with certain flags (-O3, for - example); feel free to use them. Please use good judgment - 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 - environment. -

- - - - - Libraries -

- In general, libraries must have a shared version in the - library package and a static version in the development - package. The shared version must be compiled with - -fPIC, and the static version must not be. In - other words, each source unit ( *.c, for example, - for C files) will need to be compiled twice. -

-

- In some cases, it is acceptable for a library to be - available in static form only; these cases include: - - -

libraries for languages whose shared library support - is immature or unstable

- - -

- libraries whose interfaces are in flux or under - development (commonly the case when the library's - major version number is zero, or where the ABI breaks - across patchlevels) -

- - -

- libraries which are explicitly intended to be - available only in static form by their upstream - author(s)

- - - If a library is available only in static form, then it must follow - the conventions for a development package. -

-

- All libraries must have a shared version in the - lib* package and a static version in the - lib*-dev package. The shared version must be - compiled with -fPIC, and the static version must - not be. In other words, each *.c file will need to - be compiled twice.

- -

- You must specify the gcc option -D_REENTRANT - when building a library (either static or shared) to make - the library compatible with LinuxThreads.

- -

- Note that all installed shared libraries should be - stripped with - -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. -

- You might also want to use the options - --remove-section=.comment and - --remove-section=.note on both shared libraries - and executables, and --strip-debug on static - libraries. -

- -

- -

- Note that under some circumstances it may be useful to - install a shared library unstripped, for example when - building a separate package to support debugging. -

- -

- Shared object files (often .so files) that are not - public libraries, that is, they are not meant to be linked - to by third party executables (binaries of other packages), - should be installed in subdirectories of the - /usr/lib directory. Such files are exempt from the - rules that govern ordinary shared libraries, except that - they must not be installed executable and should be - stripped. -

- A common example are the so-called ``plug-ins'', - internal shared objects that are dynamically loaded by - programs using . -

- -

- -

- Packages containing shared libraries that may be linked to - by other packages' binaries, but which for some - compelling reason can not be installed in - /usr/lib directory, may install the shared library - files in subdirectories of the /usr/lib directory, - in which case they should arrange to add that directory in - /etc/ld.so.conf in the package's post-installation - script, and remove it in the package's post-removal script. -

- -

- An ever increasing number of packages are using - libtool to do their linking. The latest GNU - libtools (>= 1.3a) can take advantage of the metadata in the - installed libtool archive files (*.la - files). The main advantage of libtool's - .la files is that it allows libtool to - store and subsequently access metadata with respect to the - libraries it builds. libtool will search for - those files, which contain a lot of useful information about - a library (such as library dependency information for static - linking). Also, they're essential for programs - using libltdl. -

- Although libtool is fully capable of - linking against shared libraries which don't have - .la files, as it is a mere shell script it can - add considerably to the build time of a - libtool-using package if that shell script - has to derive all this information from first principles - for each library every time it is linked. With the - advent of libtool version 1.4 (and to a - lesser extent libtool version 1.3), the - .la files also store information about - inter-library dependencies which cannot necessarily be - derived after the .la file is deleted. -

- -

+ 100-999: + +

+ Dynamically allocated system users and groups. + Packages which need a user or group, but can have + this user or group allocated dynamically and + differently on each system, should use adduser + --system to create the group and/or user. + adduser will check for the existence of + the user or group, and if necessary choose an unused + id based on the ranges specified in + adduser.conf. +

+ -

- Packages that use libtool to create shared - libraries should include the .la files in the - -dev package, unless the package relies on - libtool's libltdl library, in which case - the .la files must go in the run-time library - package. -

+ 1000-29999: + +

+ Dynamically allocated user accounts. By default + adduser will choose UIDs and GIDs for + user accounts in this range, though + adduser.conf may be used to modify this + behavior. +

+ -

- You must make sure that you use only released versions of - shared libraries to build your packages; otherwise other - users will not be able to run your binaries - properly. Producing source packages that depend on - unreleased compilers is also usually a bad - idea. -

- + 30000-59999: + +

Reserved.

+ - - Shared libraries + 60000-64999: + +

+ Globally allocated by the Debian project, but only + created on demand. The ids are allocated centrally + and statically, but the actual accounts are only + created on users' systems on demand. +

-

- Packages involving shared libraries should be split up - into several binary packages.

+

+ These ids are for packages which are obscure or + which require many statically-allocated ids. These + packages should check for and create the accounts in + /etc/passwd or /etc/group (using + adduser if it has this facility) if + necessary. Packages which are likely to require + further allocations should have a "hole" left after + them in the allocation, to give them room to + grow. +

+ -

- For a straightforward library which has a development - environment and a runtime kit including just shared - libraries you need to create two packages: - librarynamesoversion, where - soversion is the version number in the - soname of the shared library -

- The soname is the shared object name: it's the thing - that has to match exactly between building an executable - and running it for the dynamic linker to be able run the - program. For example, if the soname of the library is - libfoo.so.6, the library package would be - called libfoo6. -

- - and librarynamesoversion-dev. - Alternatively, if it would be confusing to directly append - soversion to libraryname (e.g. because - libraryname itself ends in a number), you may use - libraryname-soversion and - libraryname-soversion-dev - instead. -

+ 65000-65533: + +

Reserved.

+ -

- If you prefer only to support one development version at a - time you may name the development package - libraryname-dev; otherwise you may need - to use dpkg's Conflicts mechanism (see ) to ensure that the user only installs one - development version at a time (as different development - versions are likely to have the same header files in them, - which would cause a filename clash if both were installed). - Typically the development version should also have an exact - version dependency on the runtime library, to make sure that - compilation and linking happens correctly. The - ${Source-Version} substitution variable can be - useful for this purpose. -

+ 65534: + +

+ User nobody. The corresponding gid refers + to the group nogroup. +

+ -

- Packages which use the shared library should have a - dependency on the name of the shared library package, - librarynamesoversion. When - the soname changes you can have both versions of the library - installed while migrating from the old library to the new. -

+ 65535: + +

+ (uid_t)(-1) == (gid_t)(-1) must + not be used, because it is the error return + sentinel value. +

+ + +

+ + -

- If your package has some run-time support programs which use - the shared library you must not put them in the shared - library package. If you do that then you won't be able to - install several versions of the shared library 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 of the soversion in the package - name), or if the development package is small you may - include them in there. -

+ + System run levels and init.d scripts -

- If you have several shared libraries built from the same - source tree you may lump them all together into a single - shared library package, provided that you change all of - their sonames at once (so that you don't get filename - clashes if you try to install different versions of the - combined shared libraries package). -

+ + Introduction -

- Shared libraries should not be installed executable, since - the dynamic linker does not require this and trying to - execute a shared library usually results in a core dump. -

- +

+ The /etc/init.d directory contains the scripts + executed by init at boot time and when the + init state (or "runlevel") is changed (see ). +

- - Scripts +

+ There are at least two different, yet functionally + equivalent, ways of handling these scripts. For the sake + of simplicity, this document describes only the symbolic + link method. However, it must not be assumed by maintainer + scripts that this method is being used, and any automated + manipulation of the various runlevel behaviours by + maintainer scripts must be performed using + update-rc.d as described below and not by + manually installing or removing symlinks. For information + on the implementation details of the other method, + implemented in the file-rc package, please refer + to the documentation of that package. +

-

- All command scripts, including the package maintainer - scripts inside the package and used by dpkg, - should have a #! line naming the shell to be used - to interpret them.

+

+ These scripts are referenced by symbolic links in the + /etc/rcn.d directories. When changing + runlevels, init looks in the directory + /etc/rcn.d for the scripts it should + execute, where n is the runlevel that + is being changed to, or S for the boot-up + scripts. +

-

- In the case of Perl scripts this should be - #!/usr/bin/perl.

+

+ The names of the links all have the form + Smmscript or + Kmmscript where + mm is a two-digit number and script + is the name of the script (this should be the same as the + name of the actual script in /etc/init.d). +

-

- Shell scripts (sh and bash) - should almost certainly start with set -e so that - errors are detected. Every script should use - set -e or check the exit status of every - command.

+

+ When init changes runlevel first the targets + of the links whose names start with a K are + executed, each with the single argument stop, + followed by the scripts prefixed with an S, each + with the single argument start. (The links are + those in the /etc/rcn.d directory + corresponding to the new runlevel.) The K links + are responsible for killing services and the S + link for starting services upon entering the runlevel. +

-

- The standard shell interpreter /bin/sh can be a - symbolic link to any POSIX compatible shell, if echo - -n does not generate a newline. -

- Debian policy specifies POSIX behavior for - /bin/sh, but echo -n has widespread - use in the Linux community (in particular including this - policy, the Linux kernel source, many Debian scripts, - etc.). This echo -n mechanism is valid but not - required under POSIX, hence this explicit addition. - Also, rumour has it that this shall be mandated under - the LSB anyway. -

- - Thus, shell scripts specifying /bin/sh as - interpreter should only use POSIX features. If a script - requires non-POSIX features from the shell interpreter, the - appropriate shell must be specified in the first line of the - script (e.g., #!/bin/bash) and the package must - depend on the package providing the shell (unless the shell - package is marked `Essential', as in the case of - bash). -

+

+ For example, if we are changing from runlevel 2 to + runlevel 3, init will first execute all of the K + prefixed scripts it finds in /etc/rc3.d, and then + all of the S prefixed scripts in that directory. + The links starting with K will cause the + referred-to file to be executed with an argument of + stop, and the S links with an argument + of start. +

-

- You may wish to restrict your script to POSIX features when - possible so that it may use /bin/sh as its - interpreter. If your script works with dash - (originally called ash), it's probably POSIX - compliant, but if you are in doubt, use - /bin/bash. -

+

+ The two-digit number mm is used to determine + the order in which to run the scripts: 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 another. For example, the name + server bind might need to be started before + the news server inn so that inn + can set up its 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 + +

-

- Perl scripts should check for errors when making any - system calls, including open, print, - close, rename and system. -

+

+ The two runlevels 0 (halt) and 6 (reboot) are slightly + different. In these runlevels, the links with an + S prefix are still called after those with a + K prefix, but they too are called with the single + argument stop. +

-

- csh and tcsh should be avoided as - scripting languages. See Csh Programming Considered - Harmful, one of the comp.unix.* FAQs, which - can be found at . -

- It can also be found on - - or on the ftp site ftp.cpan.org as - /pub/perl/CPAN/doc/FMTEYEWTK/versus/csh.whynot. -

- - If an upstream package comes with csh scripts - then you must make sure that they start with - #!/bin/csh and make your package depend on the - c-shell virtual package. -

+

+ Also, if the script name ends .sh, the script + will be sourced in runlevel S rather that being + run in a forked subprocess, but will be explicitly run by + sh in all other runlevels. +

+ -

- Any scripts which create files in world-writeable - directories (e.g., in /tmp) must use a - mechanism which will fail if a file with the same name - already exists.

+ + Writing the scripts -

- The Debian base system provides the tempfile - and mktemp utilities for use by scripts for - this purpose.

 +

+ Packages that include daemons for system services should + place scripts in /etc/init.d to start or stop + services at boot time or during a change of runlevel. + These scripts should be named + /etc/init.d/package, and they should + accept one argument, saying what to do: + + start + start the service, - - Symbolic links + stop + stop the service, -

- In general, symbolic links within a top-level directory - should be relative, and symbolic links pointing from one - top-level directory into another should be absolute. (A - top-level directory is a sub-directory of the root - directory /.)

+ restart + stop and restart the service if it's already running, + otherwise start the service -

- In addition, symbolic links should be specified as short as - possible, i.e., link targets like foo/../bar are - deprecated.

+ reload +

cause the configuration of the service to be + reloaded without actually stopping and restarting + the service, -

- Note that when creating a relative link using - ln it is not necessary for the target of the - link to exist relative to the working directory you're - running ln from, nor is it necessary to change - directory to the directory where the link is to be made. - Simply include the string that should appear as the target - of the link (this will be a pathname relative to the - directory in which the link resides) as the first argument - to ln.

+ force-reload + cause the configuration to be reloaded if the + service supports this, otherwise restart the + service. + -

- For example, in your Makefile or - debian/rules, you can 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 -

+ The start, stop, restart, and + force-reload options should be supported by all + scripts in /etc/init.d, the reload + option is optional. +

-

- A symbolic link pointing to a compressed file should always - have the same file extension as the referenced file. (For - example, if a file foo.gz is referenced by a - symbolic link, the filename of the link has to end with - `.gz' too, as in bar.gz.) -

- +

+ The init.d scripts should ensure that they will + behave sensibly if invoked with start when the + service is already running, or with stop when it + isn't, and that they don't kill unfortunately-named user + processes. The best way to achieve this is usually to use + start-stop-daemon. +

- - Device files +

+ If a service reloads its configuration automatically (as + in the case of cron, for example), the + reload option of the init.d script + should behave as if the configuration has been reloaded + successfully. +

-

- Packages must not include device files in the package file - tree.

+

+ The /etc/init.d scripts must be treated as + configuration files, either (if they are present in the + package, that is, in the .deb file) by marking them as + conffiles, or, (if they do not exist in the .deb) + by managing them 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 + 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 the next + package upgrade. +

-

- If a package needs any special device files that are not - included in the base system, it must call - MAKEDEV in the postinst script, - after notifying the user -

- This notification could be done via a (low-priority) - debconf message, or an echo (printf) statement. -

- - .

+

+ These scripts should not fail obscurely when the + configuration files remain but the package has been + removed, as configuration files remain on the system after + the package has been removed. Only when dpkg + is executed with the --purge option will + configuration files be removed. In particular, as the + /etc/init.d/package script itself is + usually a conffile, it will remain on the system + if 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 + +

-

- Packages must not remove any device files in the - postrm or any other script. This is left to the - system administrator.

+

+ Often there are some variables in the init.d + scripts whose values control the behaviour of the scripts, + and which a system administrator is likely to want to + change. As the scripts themselves are frequently + conffiles, modifying them requires that the + administrator merge in their changes each time the package + is upgraded and the conffile changes. To ease + the burden on the system administrator, such configurable + values should not be placed directly in the script. + Instead, they should be placed in a file in + /etc/default, which typically will have the same + base name as the init.d script. This extra file + should be sourced by the script when the script runs. It + must contain only variable settings and comments in POSIX + sh format. It may either be a + conffile or a configuration file maintained by + the package maintainer scripts. See + for more details. +

-

- Debian uses the serial devices - /dev/ttyS*. Programs using the old - /dev/cu* devices should be changed to use - /dev/ttyS*.

- +

+ To ensure that vital configurable values are always + available, the init.d script should set default + values for each of the shell variables it uses, either + before sourcing the /etc/default/ file or + afterwards using something like the : + ${VAR:=default} syntax. Also, the init.d + script must behave sensibly and not fail if the + /etc/default file is deleted. +

+ - - Configuration files - Definitions -

- - configuration file - -

- A file that affects the operation of a program, or - provides site- or host-specific information, or - otherwise customizes the behavior of a program. - Typically, configuration files are intended to be - modified by the system administrator (if needed or - desired) to conform to local policy or to provide - more useful site-specific behavior. -

- + Interfacing with the initscript system - conffile - -

- A file listed in a package's conffiles - file, and is treated specially by dpkg - (see ). -

- - +

+ Maintainers should use the abstraction layer provided by + the update-rc.d and invoke-rc.d + programs to deal with initscripts in their packages' + scripts such as postinst, prerm + and postrm.

- The distinction between these two is important; they are - not interchangeable concepts. Almost all - conffiles are configuration files, but many - configuration files are not conffiles. + Directly managing the /etc/rc?.d links and directly + invoking the /etc/init.d/ initscripts should + be done only by packages providing the initscript + subsystem (such as sysv-rc and + file-rc).

-

- Note that a script that embeds configuration information - (such as most of the files in /etc/default and - /etc/cron.{daily,weekly,monthly}) is de-facto a - configuration file and should be treated as such. -

- + + Managing the links + +

+ The program update-rc.d is provided for + package maintainers to arrange for the proper creation and + removal of /etc/rcn.d symbolic links, + or their functional equivalent if another method is being + used. This may be used by maintainers in their packages' + postinst and postrm scripts. +

+ +

+ You must not include any /etc/rcn.d + symbolic links in the actual archive or manually create or + remove the symbolic links in maintainer scripts; you must + use the update-rc.d program instead. (The + former will fail if an alternative method of maintaining + runlevel information is being used.) You must not include + the /etc/rcn.d directories themselves + in the archive either. (Only the sysvinit + package may do so.) +

+ +

+ By default update-rc.d will start services in + each of the multi-user state runlevels (2, 3, 4, and 5) + and stop them in the halt runlevel (0), the single-user + runlevel (1) and the reboot runlevel (6). The system + administrator will have the opportunity to customize + runlevels by simply adding, moving, or removing the + symbolic links in /etc/rcn.d if + symbolic links are being used, or by modifying + /etc/runlevel.conf if the file-rc method + is being used. +

+ +

+ To get the default behavior for your package, put in your + postinst script + + update-rc.d package defaults + + and in your postrm + + if [ "$1" = purge ]; then + update-rc.d package remove + fi + . Note that if your package changes runlevels + or priority, you may have to remove and recreate the links, + since otherwise the old links may persist. Refer to the + documentation of update-rc.d. +

+ +

+ This will use a default sequence number of 20. If it does + not matter when or in which order the init.d + script is run, use this default. If it does, then you + should talk to the maintainer of the sysvinit + package or post to debian-devel, and they will + help you choose a number. +

- - Location -

- Any configuration files created or used by your package - must reside in /etc. If there are several you - should consider creating a subdirectory of /etc - named after your package.

+

+ For more information about using update-rc.d, + please consult its man page . +

+ -

- If your package creates or uses configuration files - outside of /etc, and it is not feasible to modify - the package to use the /etc, you should still put - the files in /etc and create symbolic links to - those files from the location that the package - requires.

- + + Running initscripts +

+ The program invoke-rc.d is provided to make + it easier for package maintainers to properly invoke an + initscript, obeying runlevel and other locally-defined + constraints that might limit a package's right to start, + stop and otherwise manage services. This program may be + used by maintainers in their packages' scripts. +

- - Behavior -

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

- local changes must be preserved during a package - upgrade, and -

- - -

- configuration files must be preserved when the - package is removed, and only deleted when the - package is purged. -

- - -

+

+ The use of invoke-rc.d to invoke the + /etc/init.d/* initscripts is strongly + recommended + In the future, the use of invoke-rc.d to invoke + initscripts shall be made mandatory. Maintainers are + advised to switch to invoke-rc.d as soon as + possible. + , instead of calling them directly. +

-

- The easy way to achieve this behavior is to make the - configuration file a conffile. This is - appropriate only if it is possible to distribute a default - version that will work for most installations, although - some system administrators may choose to modify it. This - implies that the default version will be part of the - package distribution, and must not be modified by the - maintainer scripts during installation (or at any other - time). -

+

+ By default, invoke-rc.d will pass any + action requests (start, stop, reload, restart...) to the + /etc/init.d script, filtering out requests + to start or restart a service out of its intended + runlevels. +

-

- In order to ensure that local changes are preserved - correctly, no package may contain or make hard links to - conffiles. -

- Rationale: There are two problems with hard links. - The first is that some editors break the link while - editing one of the files, so that the two files may - unwittingly become unlinked and different. The second - is that dpkg might break the hard link - while upgrading conffiles. -

- +

+ Most packages will simply need to change: + /etc/init.d/<package> + <action> in their postinst + and prerm scripts to: + + if command -v invoke-rc.d >/dev/null 2>&1; then + invoke-rc.d package <action> + else + /etc/init.d/package <action> + fi +

- 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 - distribution. If the existence of a file is required for - the package to be sensibly configured it is the - responsibility of the package maintainer to provide - maintainer scripts which correctly create, update and - maintain the file and remove it on purge. (See for more information.) These - scripts must be idempotent (i.e., must work correctly if - dpkg needs to re-run them due to errors - during installation or removal), must cope with all the - variety of ways dpkg can call maintainer - scripts, must not overwrite or otherwise mangle the user's - configuration without asking, must not ask unnecessary - questions (particularly during upgrades), and otherwise be - good citizens. -

+ A package should register its initscript services using + update-rc.d before it tries to invoke them + using invoke-rc.d. Invocation of + unregistered services may fail. +

-

- The scripts are not required to configure every possible - option for the package, but only those necessary to get - the package running on a given system. Ideally the - sysadmin should not have to do any configuration other - than that done (semi-)automatically by the - postinst script. -

+

+ For more information about using + invoke-rc.d, please consult its man page + . +

+ + -

- 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 (depending on whether - they are architecture-independent or not). There should - be symbolic links to them from - /usr/share/doc/package/examples if - they are examples, and should be perfectly ordinary - dpkg-handled files (not - configuration files). -

+ + Boot-time initialization -

- These two styles of configuration file handling must - not be mixed, for that way lies madness: - dpkg will ask about overwriting the file - every time the package is upgraded. +

+ There used to be another directory, /etc/rc.boot, + which contained scripts which were run once per machine + boot. This has been deprecated in favour of links from + /etc/rcS.d to files in /etc/init.d as + described in . Packages must not + place files in /etc/rc.boot.

- Sharing configuration files -

- Packages which specify the same file as a - conffile must be tagged as conflicting - with each other. (This is an instance of the general rule - about not sharing files. Note that neither alternatives - nor diversions are likely to be appropriate in this case; - in particular, dpkg does not handle diverted - conffiles well.) -

+ Example

- The maintainer scripts must not alter a conffile - of any package, including the one the scripts - belong to. + The bind DNS (nameserver) package wants to + make sure that the nameserver is running in multiuser + runlevels, and is properly shut down with the system. It + puts a script in /etc/init.d, naming the script + appropriately bind. As you can see, the script + interprets the argument reload to send the + nameserver a HUP signal (causing it to reload its + configuration); this way the system administrator can say + /etc/init.d/bind reload to reload the name + server. The script has one configurable value, which can + be used to pass parameters to the named program at + startup; this value is read from + /etc/default/bind (see below).

- If two or more packages use the same configuration file - and it is reasonable for both to be installed at the same - time, one of these packages must be defined as - owner of the configuration file, i.e., it will be - the package which handles that file as a configuration - file. Other packages that use the configuration file must - depend on the owning package if they require the - configuration file to operate. If the other package will - use the configuration file if present, but is capable of - operating without it, no dependency need be declared.

+ +#!/bin/sh +# +# Original version by Robert Leslie +# <rob@mars.org>, edited by iwj and cs -

- If it is desirable for two or more related packages to - share a configuration file and for all of the - related packages to be able to modify that configuration - file, then the following should be done: - - -

- One of the related packages (the "owning" package) - will manage the configuration file with maintainer - scripts as described in the previous section. -

- - -

- The owning package should also provide a program - that the other packages may use to modify the - configuration file. -

- - -

- The related packages must use the provided program - to make any desired modifications to the - configuration file. They should either depend on - the core package to guarantee that the configuration - modifier program is available or accept gracefully - that they cannot modify the configuration file if it - is not. (This is in addition to the fact that the - configuration file may not even be present in the - latter scenario.) -

- - -

+test -x /usr/sbin/named || exit 0 -

- Sometimes it's appropriate to create a new package which - provides the basic infrastructure for the other packages - and which manages the shared configuration files. (The - sgml-base package is a good example.) -

- +# Source defaults file. +PARAMS='' +if [ -f /etc/default/bind ]; then + . /etc/default/bind +fi - - User configuration files ("dotfiles") -

- The files in /etc/skel will automatically be - copied into new user accounts by adduser. - No other program should reference the files in - /etc/skel. -

+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 --oknodo \ + --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 -

- Therefore, if a program needs a dotfile to exist in - advance in $HOME to work sensibly, that dotfile - should be installed in /etc/skel and treated as a - configuration file. +exit 0 +

- However, programs that require dotfiles in order to - operate sensibly (dotfiles that they do not create - themselves automatically, that is) are a bad thing. - Furthermore, programs should be configured by the Debian - default installation to behave as closely to the upstream - default behaviour as possible. + Complementing the above init script is a configuration + file /etc/default/bind, which contains + configurable parameters used by the script. This would be + created by the postinst script if it was not + already present, and removed on purge by the + postrm script. + +# Specified parameters to pass to named. See named(8). +# You may uncomment the following line, and edit to taste. +#PARAMS="-u nobody" +

- Therefore, if a program in a Debian package needs to be - configured in some way in order to operate sensibly, that - should be done using a site-wide configuration file placed - in /etc. Only if the program doesn't support a - site-wide default configuration and the package maintainer - doesn't have time to add it may a default per-user file be - placed in /etc/skel. + Another example on which you can base your + /etc/init.d scripts is found in + /etc/init.d/skeleton.

- /etc/skel should be as empty as we can make it. - This is particularly true because there is no easy (or - necessarily desirable) mechanism for ensuring that the - appropriate dotfiles are copied into the accounts of - existing users when a package is installed. + If this package is happy with the default setup from + 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 + + And in its postrm, to remove the links when the + package is purged: + +if [ "$1" = purge ]; then + update-rc.d bind remove >/dev/null +fi +

- Log files -

- Log files should usually be named - /var/log/package.log. If you have many - log files, or need a separate directory for permission - reasons (/var/log is writable only by - root), you should usually create a directory named - /var/log/package and place your log - files there. -

- -

- Log files must be rotated occasionally so that they don't - grow indefinitely; the best way to do this is to drop a log - rotation configuration file into the directory - /etc/logrotate.d and use the facilities provided by - logrotate. -

- The traditional approach to log files has been to set up - ad hoc log rotation schemes using simple shell - scripts and cron. While this approach is highly - customizable, it requires quite a lot of sysadmin work. - Even though the original Debian system helped a little - by automatically installing a system which can be used - as a template, this was deemed not enough. -

- -

- The use of logrotate, a program developed - by Red Hat, is better, as it centralizes log management. - It has both a configuration file - (/etc/logrotate.conf) and a directory where - packages can drop their individual log rotation - configurations (/etc/logrotate.d). -

- - 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 -} - - This rotates all files under /var/log/foo, saves 12 - compressed generations, and forces the daemon to reload its - configuration information after the log rotation. -

- -

- Log files should be removed when the package is - purged (but not when it is only removed). This should be - done by the postrm script when it is called - with the argument purge (see ). -

- - - - Permissions and owners - -

- The rules in this section are guidelines for general use. - If necessary you may deviate from the details below. - However, if you do so you must make sure that what is done - is secure and you should try to be as consistent as possible - with the rest of the system. You should probably also - discuss it on debian-devel first. -

+ Console messages from init.d scripts

- Files should be owned by root.root, and made - writable only by the owner and universally readable (and - executable, if appropriate), that is mode 644 or 755. + This section describes the formats to be used for messages + written to standard output by the /etc/init.d + scripts. The intent is to improve the consistency of + Debian's startup and shutdown look and feel. For this + reason, please look very carefully at the details. We want + the messages to have the same format in terms of wording, + spaces, punctuation and case of letters.

- 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 - should be owned by the group that needs write access to - it. + Here is a list of overall rules that you should use when you + create output messages. They can be useful if you have a + non-standard message that is not covered specifically in the + sections below.

- Setuid and setgid executables should be mode 4755 or 2755 - respectively, and owned by the appropriate user or group. - 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 - reason you should not restrict read or execute permissions - on non-set-id executables. -

+ + + Every message should fit in one line (fewer than 80 + characters), start with a capital letter and end with + a period (.) and line feed ("\n"). + -

- Some setuid programs need to be restricted to particular - sets of users, using file permissions. In this case they - should be owned by the uid to which they are set-id, and by - the group which should be allowed to execute them. They - should have mode 4754; again there is no point in making - them unreadable to those users who must not be allowed to - execute them. -

+ + If you want to express that the computer is working on + something (that is, performing a specific task, not + starting or stopping a program), we use an "ellipsis" + (three dots: ...). Note that we don't insert + spaces before or after the dots. If the task has been + completed we write done. and a line feed. + -

- It is possible to arrange that the system administrator can - reconfigure the package to correspond to their local - security policy by changing the permissions on a binary: - they can do this by using dpkg-statoverride, as - described below. -

- Ordinary files installed by dpkg (as - opposed to conffiles and other similar objects) - normally have their permissions reset to the distributed - permissions when the package is reinstalled. However, - the use of dpkg-statoverride overrides this - default behaviour. If you use this method, you should - remember to describe dpkg-statoverride in - the package documentation; being a relatively new - addition to Debian, it is probably not yet well-known. -

- - Another method you should consider is to create a group for - people allowed to use the program(s) and make any setuid - executables executable only by that group. + + Design your messages as if the computer is telling you + 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. + + just say + +Starting network daemons: nfsd mountd. + + +

- If you need to create a new user or group for your package - there are two possibilities. Firstly, you may need to - make some files in the binary package be owned by this - user or group, or you may need to compile the user or - group id (rather than just the name) into the binary - (though this latter should be avoided if possible, as in - this case you need a statically allocated id).

- -

- If you need a statically allocated id, you must ask for a - user or group id from the base-passwd maintainer, - and must not release the package until you have been - allocated one. Once you have been allocated one you must - either make the package depend on a version of the - base-passwd package with the id present in - /etc/passwd or /etc/group, or arrange for - your package to create the user or group itself with the - correct id (using adduser) in its - preinst or postinst. (Doing it in - the postinst is to be preferred if it is - possible, otherwise a pre-dependency will be needed on the - adduser package.) + There are standard message formats for the following + situations. They should be used by the init.d + scripts.

- On the other hand, the program might be able to determine - the uid or gid from the user or group name at runtime, so - that a dynamically allocated id can be used. In this case - you should choose an appropriate user or group name, - discussing this on debian-devel and checking - with the base system maintainer that it is unique and that - they do not wish you to use a statically allocated id - instead. When this has been checked you must arrange for - your package to create the user or group if necessary using - adduser in the preinst or - postinst script (again, the latter is to be - preferred if it is possible). -

+ + +

When daemons are started

-

- Note that changing the numeric value of an id associated - with a name is very difficult, and involves searching the - file system for all appropriate files. You need to think - carefully whether a static or dynamic id is required, since - changing your mind later will cause problems. -

+

+ 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-n. + + The description should describe the + subsystem the daemon or set of daemons are part of, + while daemon-1 up to daemon-n + denote each daemon's name (typically the file name of + the program). +

- The use of dpkg-statoverride -

- This section is not intended as policy, but as a - description of the use of dpkg-statoverride. -

+

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

-

- dpkg-statoverride is a replacement for the - deprecated suidmanager package. Packages which - previously used suidmanager should have a - Conflicts: suidmanager (<< 0.50) entry (or even - (<< 0.52)), and calls to suidregister - and suidunregister should now be simply removed - from the maintainer scripts. -

+

+ This can be achieved by saying + +echo -n "Starting printer spooler: lpd" +start-stop-daemon --start --quiet --exec /usr/sbin/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 "." + + This makes it possible for the user to see what takes + so long and when the final daemon has been started. + You should be careful where to put spaces: in the + 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. +

+ -

- If a system administrator wishes to have a file (or - directory or other such thing) installed with owner and - permissions different from those in the distributed Debian - package, he can use the dpkg-statoverride - program to instruct dpkg to use the different - settings every time the file is installed. Thus the - package maintainer should distribute the files with their - normal permissions, and leave it for the system - administrator to make any desired changes. For example, a - daemon which is normally required to be setuid root, but - in certain situations could be used without being setuid, - should be installed setuid in the .deb. Then the - local system administrator can change this if they wish. - If there are two standard ways of doing it, the package - maintainer can use debconf to find out the - preference, and call dpkg-statoverride in the - maintainer script if necessary to accommodate the system - administrator's choice. -

+ +

When a system parameter is being set

-

- Given the above, dpkg-statoverride is - essentially a tool for system administrators and would not - normally be needed in the maintainer scripts. There is - one type of situation, though, where calls to - dpkg-statoverride would be needed in the - maintainer scripts, and that involves packages which use - dynamically allocated user or group ids. In such a - situation, something like the following idiom can be very - helpful in the package's postinst, where - sysuser is a dynamically allocated id: - -for i in /usr/bin/foo /usr/sbin/bar -do - if ! dpkg-statoverride --list $i >/dev/null - then - dpkg-statoverride --update --add sysuser root 4755 $i - fi -done - - The corresponding dpkg-statoverride --remove - calls can then be made unconditionally when the package is - purged. -

- +

+ If you have to set up different system parameters + during the system boot, you should use this format: + +Setting parameter to "value". + +

+ +

+ You can use a statement such as the following to get + the quotes right: + +echo "Setting DNS domainname to \"$domainname\"." + +

+ +

+ Note that the same symbol (") is used for the left + and right quotation marks. A grave accent (`) is + not a quote character; neither is an apostrophe + ('). +

+ + + +

When a daemon is stopped or restarted

+ +

+ When you stop or restart a daemon, you should issue a + message identical to the startup message, except that + Starting is replaced with Stopping + or Restarting respectively. +

+ +

+ For example, stopping the printer daemon will like + like this: + +Stopping printer spooler: lpd. + +

+ + + +

When something is executed

+ +

+ There are several examples where you have to run a + program at system startup or shutdown to perform a + specific task, for example, setting the system's clock + using netdate or killing all processes + when the system shuts down. Your message should look + like this: + +Doing something very useful...done. + + You should print the done. immediately after + the job has been completed, so that the user is + informed why she has to wait. You can get this + behavior by saying + +echo -n "Doing something very useful..." +do_something +echo "done." + + in your script. +

+ + + +

When the configuration is reloaded

+ +

+ When a daemon is forced to reload its configuration + files you should use the following format: + +Reloading description configuration...done. + + where description is the same as in the + daemon starting message. +

+ + +

- - - Customized programs + + Cron jobs - - Architecture specification strings +

+ Packages must not modify the configuration file + /etc/crontab, and they must not modify the files in + /var/spool/cron/crontabs.

+ +

+ 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 or more of the following directories: + +/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, + respectively. The exact times are listed in + /etc/crontab.

- If a program needs to specify an architecture specification - string in some place, the following format should be - used: arch-os -

- The following architectures and operating systems are - currently recognised by dpkg-archictecture. - The architecture, arch, is one of - the following: alpha, arm, - hppa, i386, ia64, - m68k, mips, mipsel, - powerpc, s390, sh, - sheb, sparc and sparc64. The - operating system, os, is one of: - linux, gnu, freebsd and - openbsd. Use of gnu in this string is - reserved for the GNU/Hurd operating system. -

- . + All files installed in any of these directories must be + scripts (e.g., shell scripts or Perl scripts) so that they + can easily be modified by the local system administrator. + In addition, they should be treated as configuration + files.

- Note that we don't want to use - arch-debian-linux to apply to the rule - architecture-vendor-os - since this would make our programs incompatible with other - Linux distributions. We also don't use something like - arch-unknown-linux, since the - unknown does not look very good. -

+ If a certain job has to be executed more frequently than + daily, the package should install a file + /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 + /etc/cron.d directory are not handled by + anacron. Thus, you should only use this + directory for jobs which may be skipped if the system is not + running.)

+ +

+ The scripts or crontab entries in these directories should + check if all necessary programs are installed before they + try to execute them. Otherwise, problems will arise when a + package was removed but not purged since configuration files + are kept on the system in this situation.

 - - Daemons + + Menus

- The configuration files /etc/services, - /etc/protocols, and /etc/rpc are managed - by the netbase package and must not be modified - by other packages. + The Debian menu package provides a standard + interface between packages providing applications and + documents, and menu programs (either X window + managers or text-based menu programs such as + pdmenu).

- If a package requires a new entry in one of these files, the - maintainer should get in contact with the - netbase maintainer, who will add the entries - and release a new version of the netbase - package. + All packages that provide applications that need not be + passed any special command line arguments for normal + operation should register a menu entry for those + applications, so that users of the menu package + will automatically get menu entries in their window + managers, as well in shells like pdmenu.

- The configuration file /etc/inetd.conf must not be - modified by the package's scripts except via the - update-inetd script or the - DebianNet.pm Perl module. See their documentation - for details on how to add entries. + Menu entries should follow the current menu policy.

- If a package wants to install an example entry into - /etc/inetd.conf, the entry must be preceded with - exactly one hash character (#). Such lines are - treated as `commented out by user' by the - update-inetd script and are not changed or - activated during package updates. + The menu policy can be found in the menu-policy + files in the debian-policy package. + It is also available from the Debian web mirrors at + . +

+ +

+ Please also refer to the Debian Menu System + documentation that comes with the menu package for + information about how to register your applications and web + documents.

- - Using pseudo-ttys and modifying wtmp, utmp and - lastlog + + Multimedia handlers

- Some programs need to create pseudo-ttys. This should be done - using Unix98 ptys if the C library supports it. The resulting - program must not be installed setuid root, unless that - is required for other functionality. + MIME (Multipurpose Internet Mail Extensions, RFCs 2045-2049) + is a mechanism for encoding files and data streams and + providing meta-information about them, in particular their + type (e.g. audio or video) and format (e.g. PNG, HTML, + MP3).

- The files /var/run/utmp, /var/log/wtmp and - /var/log/lastlog must be installed writeable by - group utmp. Programs which need to modify those - files must be installed setgid utmp. + Registration of MIME type handlers allows programs like mail + user agents and web browsers to invoke these handlers to + view, edit or display MIME types they don't support directly.

- - - Editors and pagers +

+ Packages which provide the ability to view/show/play, + compose, edit or print MIME types should register themselves + as such following the current MIME support policy. +

- Some programs have the ability to launch an editor or pager - program to edit or display a text document. Since there are - lots of different editors and pagers available in the Debian - distribution, the system administrator and each user should - have the possibility to choose his/her preferred editor and - pager. + The MIME support policy can be found in the mime-policy + files in the debian-policy package. + It is also available from the Debian web mirrors at + .

+ + + + Keyboard configuration +

- In addition, every program should choose a good default - editor/pager if none is selected by the user or system - administrator. + To achieve a consistent keyboard configuration so that all + applications interpret a keyboard event the same way, all + programs in the Debian distribution must be configured to + comply with the following guidelines.

- Thus, every program that launches an editor or pager must - use the EDITOR or PAGER environment variable to determine - the editor or pager the user wishes to use. If these - variables are not set, the programs /usr/bin/editor - and /usr/bin/pager should be used, respectively. + The following keys must have the specified interpretations: + + + <-- + delete the character to the left of the cursor + + Delete + delete the character to the right of the cursor + + Control+H + emacs: the help prefix + + + The interpretation of any keyboard events should be + independent of the terminal that is used, be it a virtual + console, an X terminal emulator, an rlogin/telnet session, + etc.

- These two files are managed through the dpkg - `alternatives' mechanism. Thus every package providing an - editor or pager must call the - update-alternatives script to register these - programs. + The following list explains how the different programs + should be set up to achieve this:

- If it is very hard to adapt a program to make use of the - EDITOR or PAGER variables, that program may be configured to - use /usr/bin/sensible-editor and - /usr/bin/sensible-pager as the editor or pager - program respectively. These are two scripts provided in the - Debian base system that check the EDITOR and PAGER variables - and launch the appropriate program, and fall back to - /usr/bin/editor and /usr/bin/pager if the - variable is not set. + + + <-- generates KB_BackSpace in X. + + + + Delete generates KB_Delete in X. + + + + X translations are set up to make + KB_Backspace generate ASCII DEL, and to make + KB_Delete generate ESC [ 3 ~ (this + is the vt220 escape code for the "delete character" + key). This must be done by loading the X resources + using xrdb on all local X displays, not + using the application defaults, so that the + translation resources used correspond to the + xmodmap settings. + + + + The Linux console is configured to make + <-- generate DEL, and Delete + generate ESC [ 3 ~. + + + + X applications are configured so that < + deletes left, and Delete deletes right. Motif + applications already work like this. + + + + Terminals should have stty erase ^? . + + + + The xterm terminfo entry should have ESC + [ 3 ~ for kdch1, just as for + TERM=linux and TERM=vt220. + + + + Emacs is programmed to map KB_Backspace or + the stty erase character to + delete-backward-char, and KB_Delete + or kdch1 to delete-forward-char, and + ^H to help as always. + + + + Other applications use the stty erase + character and kdch1 for the two delete keys, + with ASCII DEL being "delete previous character" and + kdch1 being "delete character under + cursor". + + +

- A program may also use the VISUAL environment variable to - determine the user's choice of editor. If it exists, it - should take precedence over EDITOR. This is in fact what - /usr/bin/sensible-editor does. + This will solve the problem except for the following + cases:

- It is not required for a package to depend on - editor and pager, nor is it required for a - package to provide such virtual packages. -

- The Debian base system already provides an editor and a - pager program, -

- + + + Some terminals have a <-- key that cannot + be made to produce anything except ^H. On + these terminals Emacs help will be unavailable on + ^H (assuming that the stty erase + character takes precedence in Emacs, and has been set + correctly). M-x help or F1 (if + available) can be used instead. + + + + Some operating systems use ^H for stty + erase. However, modern telnet versions and all + rlogin versions propagate stty settings, and + almost all UNIX versions honour stty erase. + Where the stty settings are not propagated + correctly, things can be made to work by using + stty manually. + + + + Some systems (including previous Debian versions) use + xmodmap to arrange for both + <-- and Delete to generate + KB_Delete. We can change the behavior of + their X clients using the same X resources that we use + to do it for our own clients, or configure our clients + using their resources when things are the other way + around. On displays configured like this + Delete will not work, but <-- + will. + + + + Some operating systems have different kdch1 + settings in their terminfo database for + xterm and others. On these systems the + Delete key will not work correctly when you + log in from a system conforming to our policy, but + <-- will. + +

- - Web servers and applications + + Environment variables

- This section describes the locations and URLs that should - be used by all web servers and web applications in the - Debian system. + A program must not depend on environment variables to get + reasonable defaults. (That's because these environment + variables would have to be set in a system-wide + configuration file like /etc/profile, which is not + supported by all shells.)

- - -

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

- + If a program usually depends on environment variables for its + configuration, the program should be changed to fall back to + a reasonable default configuration if these environment + variables are not present. If this cannot be done easily + (e.g., if the source code of a non-free program is not + available), the program must be replaced by a small + "wrapper" shell script which sets the environment variables + if they are not already defined, and calls the original program. +

-

Access to HTML documents

+

+ Here is an example of a wrapper script for this purpose: -

- HTML documents for a package are stored in - /usr/share/doc/package - and can be referred to as - -http://localhost/doc/package/filename - -

-

- The web server should restrict access to the document - tree so that only clients on the same host can read - the documents. If the web server does not support such - access controls, then it should not provide access at - all, or ask about providing access during installation. -

- + +#!/bin/sh +BAR=${BAR:-/var/lib/fubar} +export BAR +exec /usr/lib/foo/foo "$@" + +

-

Web Document Root

+

+ Furthermore, as /etc/profile is a configuration + file of the base-files package, other packages must + not put any environment variables or other commands into that + file. +

+ -

- Web Applications should try to avoid storing files in - the Web Document Root. Instead they should use the - /usr/share/doc/package directory for - documents and register the Web Application via the - menu package. If access to the web document root is - unavoidable then use - -/var/www - - as the Document Root. This might be just a symbolic - link to the location where the system administrator - has put the real document root. -

- + -

+ + Files - - Mail transport, delivery and user agents + + Binaries

- Debian packages which process electronic mail, whether mail - user agents (MUAs) or mail transport agents (MTAs), must - ensure that they are compatible with the configuration - decisions below. Failure to do this may result in lost - mail, broken From: lines, and other serious brain - damage! + Two different packages must not install programs with + different functionality but with the same filenames. (The + case of two programs having the same functionality but + different implementations is handled via "alternatives" or + the "Conflicts" mechanism. See and + respectively.) If this case happens, + one of the programs must be renamed. The maintainers should + report this to the debian-devel mailing list and + try to find a consensus about which program will have to be + renamed. If a consensus cannot be reached, both + programs must be renamed.

- The mail spool is /var/mail and the interface to - send a mail message is /usr/sbin/sendmail (as 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. + By default, when a package is being built, any binaries + created should include debugging information, as well as + being compiled with optimization. You should also turn on + as many reasonable compilation warnings as possible; this + makes life easier for porters, who can then look at build + logs for possible problems. For the C programming language, + this means the following compilation parameters should be + used: + +CC = gcc +CFLAGS = -O2 -g -Wall # sane warning options vary between programs +LDFLAGS = # none +install -s # (or use strip on the files in debian/tmp) +

- All Debian MUAs, MTAs, MDAs and other mailbox accessing - programs (such as IMAP daemons) must lock the mailbox in an - NFS-safe way. This means that fcntl() locking must - be combined with dot locking. To avoid deadlocks, a program - should use fcntl() first and dot locking after - this, or alternatively implement the two locking methods in - a non blocking way -

- If it is not possible to establish both locks, the - system shouldn't wait for the second lock to be - established, but remove the first lock, wait a (random) - time, and start over locking again. -

- . Using the functions maillock and - mailunlock provided by the - liblockfile* -

- You will need to depend on liblockfile1 - (>>1.01) to use these functions. -

- packages is the recommended way to realize this. + Note that by default all installed binaries should be stripped, + either by using the -s flag to + install, or by calling strip on + the binaries after they have been copied into + debian/tmp but before the tree is made into a + package.

- Mailboxes are generally mode 660 - user.mail unless the system - administrator has chosen otherwise. A MUA may remove a - mailbox (unless it has nonstandard permissions) in which - case the MTA or another MUA must recreate it if needed. - Mailboxes must be writable by group mail. + Although binaries in the build tree should be compiled with + debugging information by default, it can often be difficult + to debug programs if they are also subjected to compiler + optimization. For this reason, it is recommended to support + the standardized environment + variable DEB_BUILD_OPTIONS. This variable can + contain several flags to change how a package is compiled + and built.

- The mail spool is 2775 root.mail, and MUAs should - be setgid mail to do the locking mentioned above (and - must obviously avoid accessing other users' mailboxes - using this privilege).

- -

- /etc/aliases is the source file for the system mail - 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 - packages must come with a newaliases program, - even if it does nothing, but older MTA packages did not do - this so programs should not fail if newaliases - cannot be found. Note that because of this, all MTA - packages must have Provides, Conflicts and - Replaces: mail-transport-agent control file - fields. + + noopt + + The presence of this string means that the package + should be compiled with a minimum of optimization. + For C programs, it is best to add -O0 + to CFLAGS (although this is usually the + default). Some programs might fail to build or run at + this level of optimization; it may be necessary to + use -O1, for example. + + nostrip + + This string means that the debugging symbols should + not be stripped from the binary during installation, + so that debugging information may be included in the package. + +

- The convention of writing forward to - address in the mailbox itself is not - supported. Use a .forward file instead.

- -

- The rmail program used by UUCP - for incoming mail should be /usr/sbin/rmail. - Likewise, rsmtp, for receiving - batch-SMTP-over-UUCP, should be /usr/sbin/rsmtp if it - is supported.

+ The following makefile snippet is an example of how one may + implement the build options; you will probably have to + massage this example in order to make it work for your + package. + +CFLAGS = -Wall -g +INSTALL = install +INSTALL_FILE = $(INSTALL) -p -o root -g root -m 644 +INSTALL_PROGRAM = $(INSTALL) -p -o root -g root -m 755 +INSTALL_SCRIPT = $(INSTALL) -p -o root -g root -m 755 +INSTALL_DIR = $(INSTALL) -p -d -o root -g root -m 755 -

- If your package needs to know what hostname to use on (for - example) outgoing news and mail messages which are generated - locally, you should use the file /etc/mailname. It - will contain the portion after the username and @ - (at) sign for email addresses of users on the machine - (followed by a newline). +ifneq (,$(findstring noopt,$(DEB_BUILD_OPTIONS))) +CFLAGS += -O0 +else +CFLAGS += -O2 +endif +ifeq (,$(findstring nostrip,$(DEB_BUILD_OPTIONS))) +INSTALL_PROGRAM += -s +endif +

- Such package should check for the existence of this file - when it is being configured. If it exists, it should be - used without comment, although an MTA's configuration script - may wish to prompt the user even if it finds that this file - exists. If the file does not exist, the package should - prompt the user for the value (preferably using - debconf) and store it in /etc/mailname - as well as using it in the package's 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 could say something like: - -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. + It is up to the package maintainer to decide what + compilation options are best for the package. Certain + binaries (such as computationally-intensive programs) will + function better with certain flags (-O3, for + example); feel free to use them. Please use good judgment + 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 + environment.

- - News system configuration + + + Libraries

- All the configuration files related to the NNTP (news) - servers and clients should be located under - /etc/news.

+ The shared version of a library must be compiled with + -fPIC, and the static version must not be. In other + words, each source unit (*.c, for example, for C files) + will need to be compiled twice. +

- There are some configuration issues that apply to a number - of news clients and server packages on the machine. These - are: + You must specify the gcc option -D_REENTRANT + when building a library (either static or shared) to make + the library compatible with LinuxThreads. +

- - /etc/news/organization -

A string which should appear as the - organization header for all messages posted - by NNTP clients on the machine

 +

+ Although not enforced by the build tools, shared libraries + must be linked against all libraries that they use symbols from + in the same way that binaries are. This ensures the correct + functioning of the shlibs + system and guarantees that all libraries can be safely opened + with dlopen(). Packagers may wish to use the gcc + option -Wl,-z,defs when building a shared library. + Since this option enforces symbol resolution at build time, + a missing library reference will be caught early as a fatal + build error. +

- /etc/news/server -

Contains the FQDN of the upstream NNTP - server, or localhost if the local machine is - an NNTP server.

 - +

+ All installed shared libraries should be stripped with + +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. + You might also want to use the options + --remove-section=.comment and + --remove-section=.note on both shared libraries + and executables, and --strip-debug on static + libraries. + +

- Other global files may be added as required for cross-package news - configuration.

 +

+ Note that under some circumstances it may be useful to + install a shared library unstripped, for example when + building a separate package to support debugging. +

+

+ Shared object files (often .so files) that are not + public libraries, that is, they are not meant to be linked + to by third party executables (binaries of other packages), + should be installed in subdirectories of the + /usr/lib directory. Such files are exempt from the + rules that govern ordinary shared libraries, except that + they must not be installed executable and should be + stripped. + A common example are the so-called "plug-ins", + internal shared objects that are dynamically loaded by + programs using . + +

- - Programs for the X Window System +

+ Packages containing shared libraries that may be linked to + by other packages' binaries, but which for some + compelling reason can not be installed in + /usr/lib directory, may install the shared library + files in subdirectories of the /usr/lib directory, + in which case they should arrange to add that directory in + /etc/ld.so.conf in the package's post-installation + script, and remove it in the package's post-removal script. +

- - Providing X support and package priorities +

+ An ever increasing number of packages are using + libtool to do their linking. The latest GNU + libtools (>= 1.3a) can take advantage of the metadata in the + installed libtool archive files (*.la + files). The main advantage of libtool's + .la files is that it allows libtool to + store and subsequently access metadata with respect to the + libraries it builds. libtool will search for + those files, which contain a lot of useful information about + a library (such as library dependency information for static + linking). Also, they're essential for programs + using libltdl. + Although libtool is fully capable of + linking against shared libraries which don't have + .la files, as it is a mere shell script it can + add considerably to the build time of a + libtool-using package if that shell script + has to derive all this information from first principles + for each library every time it is linked. With the + advent of libtool version 1.4 (and to a + lesser extent libtool version 1.3), the + .la files also store information about + inter-library dependencies which cannot necessarily be + derived after the .la file is deleted. + +

-

- Programs that can be configured with support for the X - Window System must be configured to do so and must declare - any package dependencies necessary to satisfy their - runtime requirements when using the X Window System. If - such a package is of higher priority than the X packages - on which it depends, it is required that either the - X-specific components be split into a separate package, or - that an alternative version of the package, which includes - X support, be provided, or that the package's priority be - lowered. -

- +

+ Packages that use libtool to create shared + libraries should include the .la files in the + -dev package, unless the package relies on + libtool's libltdl library, in which case + the .la files must go in the run-time library + package. +

- - Packages providing an X server +

+ You must make sure that you use only released versions of + shared libraries to build your packages; otherwise other + users will not be able to run your binaries + properly. Producing source packages that depend on + unreleased compilers is also usually a bad + idea. +

+ -

- Packages that provide an X server that, directly or - indirectly, communicates with real input and display - hardware should declare in their control data that they - provide the virtual package xserver. -

- This implements current practice, and provides an - actual policy for usage of the xserver - virtual package which appears in the virtual packages - list. In a nutshell, X servers that interface - directly with the display and input hardware or via - another subsystem (e.g., GGI) should provide - xserver. Things like Xvfb, - Xnest, and Xprt should not. -

- -

- - - Packages providing a terminal emulator + + Shared libraries +

+ This section has moved to . +

+ -

- Packages that provide a terminal emulator for the X Window - System which meet the criteria listed below should declare - in their control data that they provide the virtual - package x-terminal-emulator. They should also - register themselves as an alternative for - /usr/bin/x-terminal-emulator, with a priority of - 20. -

-

- To be an x-terminal-emulator, a program must: - -

- Be able to emulate a DEC VT100 terminal, or a - compatible terminal. -

+ + Scripts -

- Support the command-line option -e - command, which creates a new - terminal window -

- "New terminal window" does not necessarily mean - a new top-level X window directly parented by - the window manager; it could, if the terminal - emulator application were so coded, be a new - "view" in a multiple-document interface (MDI). -

- - and runs the specified command. -

+

+ All command scripts, including the package maintainer + scripts inside the package and used by dpkg, + should have a #! line naming the shell to be used + to interpret them. +

-

- Support the command-line option -T - title, which creates a new terminal - window with the window title title. -

- -

- +

+ In the case of Perl scripts this should be + #!/usr/bin/perl. +

- - Packages providing a window manager +

+ Shell scripts (sh and bash) + should almost certainly start with set -e so that + errors are detected. Every script should use + set -e or check the exit status of every + command. +

-

- Packages that provide a window manager should declare in - their control data that they provide the virtual package - 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.

+

+ The standard shell interpreter /bin/sh can be a + symbolic link to any POSIX compatible shell, if echo + -n does not generate a newline. + Debian policy specifies POSIX behavior for + /bin/sh, but echo -n has widespread + use in the Linux community (in particular including this + policy, the Linux kernel source, many Debian scripts, + etc.). This echo -n mechanism is valid but not + required under POSIX, hence this explicit addition. + Also, rumour has it that this shall be mandated under + the LSB anyway. + + Thus, shell scripts specifying /bin/sh as + interpreter should only use POSIX features. If a script + requires non-POSIX features from the shell interpreter, the + appropriate shell must be specified in the first line of the + script (e.g., #!/bin/bash) and the package must + depend on the package providing the shell (unless the shell + package is marked "Essential", as in the case of + bash). +

- -

- If the window manager supports the Debian menu - system, add 20 points if this support is available - in the package's default configuration (i.e., no - configuration files belonging to the system or user - have to be edited to activate the feature); if - configuration files must be modified, add only 10 - points. -

- - -

- If the window manager complies with , - written by the , add 20 points. -

- +

+ You may wish to restrict your script to POSIX features when + possible so that it may use /bin/sh as its + interpreter. If your script works with dash + (originally called ash), it's probably POSIX + compliant, but if you are in doubt, use + /bin/bash. +

- -

- If the window manager permits the X session to be - restarted using a different window manager - (without killing the X server) in its default - configuration, add 10 points; otherwise add none. -

- - -

- +

+ Perl scripts should check for errors when making any + system calls, including open, print, + close, rename and system. +

- - Packages providing fonts +

+ csh and tcsh should be avoided as + scripting languages. See Csh Programming Considered + Harmful, one of the comp.unix.* FAQs, which + can be found at . + If an upstream package comes with csh scripts + then you must make sure that they start with + #!/bin/csh and make your package depend on the + c-shell virtual package. +

-

- Packages that provide fonts for the X Window - System -

- For the purposes of Debian Policy, a "font for the X - Window System" is one which is accessed via X protocol - requests. Fonts for the Linux console, for PostScript - renderers, or any other purpose, do not fit this - definition. Any tool which makes such fonts available - to the X Window System, however, must abide by this - font policy. -

- - must do a number of things to ensure that they are both - available without modification of the X or font server - configuration, and that they do not corrupt files used by - other font packages to register information about - themselves. - - -

- Fonts of any type supported by the X Window System - must be in a separate binary package from any - executables, libraries, or documentation (except - that specific to the fonts shipped, such as their - license information). If one or more of the fonts - so packaged are necessary for proper operation of - the package with which they are associated the font - package may be Recommended; if the fonts merely - provide an enhancement, a Suggests relationship may - be used. Packages must not Depend on font - packages. -

- This is because the X server may retrieve fonts - from the local filesystem or over the network - from an X font server; the Debian package system - is empowered to deal only with the local - filesystem. -

- -

- +

+ Any scripts which create files in world-writeable + directories (e.g., in /tmp) must use a + mechanism which will fail if a file with the same name + already exists. +

- -

- BDF fonts must be converted to PCF fonts with the - bdftopcf utility (available in the - xutils package, gzipped, and - placed in a directory that corresponds to their - resolution: - -

- 100 dpi fonts must be placed in - /usr/X11R6/lib/X11/fonts/100dpi/. -

+

+ The Debian base system provides the tempfile + and mktemp utilities for use by scripts for + this purpose. +

+ -

- 75 dpi fonts must be placed in - /usr/X11R6/lib/X11/fonts/75dpi/. -

-

- Character-cell fonts, cursor fonts, and other - low-resolution fonts must be placed in - /usr/X11R6/lib/X11/fonts/misc/. -

- -

- + + Symbolic links -

- Speedo fonts must be placed in - /usr/X11R6/lib/X11/fonts/Speedo/. -

+

+ In general, symbolic links within a top-level directory + should be relative, and symbolic links pointing from one + top-level directory into another should be absolute. (A + top-level directory is a sub-directory of the root + directory /.) +

-

- Type 1 fonts must be placed in - /usr/X11R6/lib/X11/fonts/Type1/. If font - metric files are available, they must be placed here - as well. -

+

+ In addition, symbolic links should be specified as short as + possible, i.e., link targets like foo/../bar are + deprecated. +

- -

- Subdirectories of /usr/X11R6/lib/X11/fonts/ - other than those listed above must be neither - created nor used. (The PEX, CID, - and cyrillic directories are excepted for - historical reasons, but installation of files into - these directories remains discouraged.) -

- +

+ Note that when creating a relative link using + ln it is not necessary for the target of the + link to exist relative to the working directory you're + running ln from, nor is it necessary to change + directory to the directory where the link is to be made. + Simply include the string that should appear as the target + of the link (this will be a pathname relative to the + directory in which the link resides) as the first argument + to ln. +

- -

- Font packages may, instead of placing files directly - in the X font directories listed above, provide - symbolic links in that font directory pointing to - the files' actual location in the filesystem. Such - a location must comply with the FHS. -

- +

+ For example, in your Makefile or + debian/rules, you can 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 + +

- -

- Font packages should not contain both 75dpi and - 100dpi versions of a font. If both are available, - they should be provided in separate binary packages - with -75dpi or -100dpi appended to - the names of the packages containing the - corresponding fonts. -

- +

+ A symbolic link pointing to a compressed file should always + have the same file extension as the referenced file. (For + example, if a file foo.gz is referenced by a + symbolic link, the filename of the link has to end with + ".gz" too, as in bar.gz.) +

+ - -

- Fonts destined for the misc subdirectory - should not be included in the same package as 75dpi - or 100dpi fonts; instead, they should be provided in - a separate package with -misc appended to - its name. -

- + + Device files - -

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

+

+ Packages must not include device files in the package file + tree. +

- -

- fonts.alias and fonts.scale - files, if needed, should be provided in the - directory - /etc/X11/fonts/fontdir/package.extension, - where fontdir is the name of the - subdirectory of - /usr/X11R6/lib/X11/fonts/ where the - package's corresponding fonts are stored - (e.g., 75dpi or misc), - package is the name of the package - that provides these fonts, and - extension is either scale - or alias, whichever corresponds to - the file contents. -

- - -

- +

+ If a package needs any special device files that are not + included in the base system, it must call + MAKEDEV in the postinst script, + after notifying the user + This notification could be done via a (low-priority) + debconf message, or an echo (printf) statement. + . +

- -

- Font packages must declare a dependency on - xutils (>> 4.0.3) in their control - data. -

- +

+ Packages must not remove any device files in the + postrm or any other script. This is left to the + system administrator. +

- -

- Font packages that provide one or more - fonts.scale files as described above must - invoke update-fonts-scale on each - directory into which they installed fonts - before invoking - update-fonts-dir on that directory. - This invocation must occur in both the - postinst (for all arguments) and - postrm (for all arguments except - upgrade) scripts. -

- +

+ Debian uses the serial devices + /dev/ttyS*. Programs using the old + /dev/cu* devices should be changed to use + /dev/ttyS*. +

+ + + + Configuration files - -

- Font packages that provide one or more - fonts.alias files as described above must - invoke update-fonts-alias on each - directory into which they installed fonts. This - invocation must occur in both the - postinst (for all arguments) and - postrm (for all arguments except - upgrade) scripts. -

- + + Definitions +

+ + configuration file -

- Font packages must invoke - update-fonts-dir on each directory into - which they installed fonts. This invocation must - occur in both the postinst (for all - arguments) and postrm (for all - arguments except upgrade) scripts. -

+ A file that affects the operation of a program, or + provides site- or host-specific information, or + otherwise customizes the behavior of a program. + Typically, configuration files are intended to be + modified by the system administrator (if needed or + desired) to conform to local policy or to provide + more useful site-specific behavior. + conffile -

- Font packages must not provide alias names for the - fonts they include which collide with alias names - already in use by fonts already packaged. -

+ A file listed in a package's conffiles + file, and is treated specially by dpkg + (see ). + +

- -

- Font packages must not provide fonts with the same - XLFD registry name as another font already packaged. -

- - +

+ The distinction between these two is important; they are + not interchangeable concepts. Almost all + conffiles are configuration files, but many + configuration files are not conffiles. +

+ +

+ Note that a script that embeds configuration information + (such as most of the files in /etc/default and + /etc/cron.{daily,weekly,monthly}) is de-facto a + configuration file and should be treated as such.

- Application defaults files + Location

- 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 manual is also permitted). They must be - registered as conffiles or handled as - configuration files. Packages must not provide the - directory /usr/X11R6/lib/X11/app-defaults/. + Any configuration files created or used by your package + must reside in /etc. If there are several, + consider creating a subdirectory of /etc + named after your package.

- Customization of programs' X resources may also be - supported with the provision of a file with the same name - as that of the package placed in the - /etc/X11/Xresources/ directory, which must - registered as a conffile or handled as a - configuration file. -

- Note that this mechanism is not the same as using - app-defaults; app-defaults are tied to the client - binary on the local filesystem, whereas X resources - are stored in the X server and affect all connecting - clients. -

- - Important: packages that install files into the - /etc/X11/Xresources/ directory must conflict with - xbase (<< 3.3.2.3a-2); if this is not done - it is possible for the installing package to destroy a - previously-existing /etc/X11/Xresources file - which had been customized by the system administrator. + If your package creates or uses configuration files + outside of /etc, and it is not feasible to modify + the package to use /etc directly, put the files + in /etc and create symbolic links to those files + from the location that the package requires.

- Installation directory issues + Behavior

- Packages using the X Window System should not be - configured to install files under the /usr/X11R6/ - directory unless they use imake. The - /usr/X11R6/ directory hierarchy should be - regarded as deprecated for all packages except the X - Window System itself, and those which use the - imake program it provides, in which case the - packages may transition out of the /usr/X11R6/ - directory at the maintainer's discretion. -

- Imake-using programs are exempt because, - as long as they are written correctly, the pathnames - they use to locate resources and install themselves - are derived wholly from the X Window System - configuration. Thus, in the event that the X Window - System moves to /usr/X11R7/, - /usr/X12/, or just plain /usr/, all - that is required for these programs is a recompile - against the corresponding X Window System library - development packages. -

- - Programs that use GNU autoconf and - automake are usually easily configured at - compile time to use /usr/ instead of - /usr/X11R6/, and this should be done whenever - possible. 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. (The use of symbolic links from the - X11R6 directories to other 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 other FHS-compliant - locations. + Configuration file handling must conform to the following + behavior: + + + local changes must be preserved during a package + upgrade, and + + + configuration files must be preserved when the + package is removed, and only deleted when the + package is purged. + +

- - - The OSF/Motif and OpenMotif libraries +

+ The easy way to achieve this behavior is to make the + configuration file a conffile. This is + appropriate only if it is possible to distribute a default + version that will work for most installations, although + some system administrators may choose to modify it. This + implies that the default version will be part of the + package distribution, and must not be modified by the + maintainer scripts during installation (or at any other + time). +

- Programs that require the non-DFSG-compliant OSF/Motif or - OpenMotif libraries -

- OSF/Motif and OpenMotif are collectively referred to as - "Motif" in this policy document. -

+ In order to ensure that local changes are preserved + correctly, no package may contain or make hard links to + conffiles. + Rationale: There are two problems with hard links. + The first is that some editors break the link while + editing one of the files, so that the two files may + unwittingly become unlinked and different. The second + is that dpkg might break the hard link + while upgrading conffiles. - should be compiled against and tested with LessTif (a free - re-implementation of Motif) instead. If the maintainer - judges that the program or programs do not work - sufficiently well with LessTif to be distributed and - supported, but do so when compiled against Motif, then two - versions of the package should be created; one linked - statically against Motif and with -smotif - appended to the package name, and one linked dynamically - against Motif and with -dmotif appended to the - package name. Both Motif-linked versions are dependent - upon non-DFSG-compliant software and thus cannot be - uploaded to the main distribution; if the - software is itself DFSG-compliant it may be uploaded to - the contrib distribution. While known existing - versions of Motif permit unlimited redistribution of - binaries linked against the library (whether statically or - dynamically), it is the package maintainer's - responsibility to determine whether this is permitted by - the license of the copy of Motif in his or her possession. +

+ +

+ 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 + distribution. If the existence of a file is required for + the package to be sensibly configured it is the + responsibility of the package maintainer to provide + maintainer scripts which correctly create, update and + maintain the file and remove it on purge. (See for more information.) These + scripts must be idempotent (i.e., must work correctly if + dpkg needs to re-run them due to errors + during installation or removal), must cope with all the + variety of ways dpkg can call maintainer + scripts, must not overwrite or otherwise mangle the user's + configuration without asking, must not ask unnecessary + questions (particularly during upgrades), and otherwise be + good citizens. +

+ +

+ The scripts are not required to configure every possible + option for the package, but only those necessary to get + the package running on a given system. Ideally the + sysadmin should not 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/package or + /usr/lib/package (depending on whether + they are architecture-independent or not). There should + be symbolic links to them from + /usr/share/doc/package/examples if + they are examples, and should be perfectly ordinary + dpkg-handled files (not + configuration files). +

+ +

+ These two styles of configuration file handling must + not be mixed, for that way lies madness: + dpkg will ask about overwriting the file + every time the package is upgraded.

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

- + + Sharing configuration files - - Emacs lisp programs +

+ Packages which specify the same file as a + conffile must be tagged as conflicting + with each other. (This is an instance of the general rule + about not sharing files. Note that neither alternatives + nor diversions are likely to be appropriate in this case; + in particular, dpkg does not handle diverted + conffiles well.) +

-

- Please refer to the `Debian Emacs Policy' (documented in - debian-emacs-policy.gz of the - emacsen-common package) for details of how to - package emacs lisp programs. -

- +

+ The maintainer scripts must not alter a conffile + of any package, including the one the scripts + belong to. +

- - Games +

+ If two or more packages use the same configuration file + and it is reasonable for both to be installed at the same + time, one of these packages must be defined as + owner of the configuration file, i.e., it will be + the package which handles that file as a configuration + file. Other packages that use the configuration file must + depend on the owning package if they require the + configuration file to operate. If the other package will + use the configuration file if present, but is capable of + operating without it, no dependency need be declared. +

-

- The permissions on /var/games are mode 755, owner - root and group root. -

+

+ If it is desirable for two or more related packages to + share a configuration file and for all of the + related packages to be able to modify that configuration + file, then the following should be done: + + + One of the related packages (the "owning" package) + will manage the configuration file with maintainer + scripts as described in the previous section. + + + The owning package should also provide a program + that the other packages may use to modify the + configuration file. + + + The related packages must use the provided program + to make any desired modifications to the + configuration file. They should either depend on + the core package to guarantee that the configuration + modifier program is available or accept gracefully + that they cannot modify the configuration file if it + is not. (This is in addition to the fact that the + configuration file may not even be present in the + latter scenario.) + + +

-

- Each game decides on its own security policy.

+

+ Sometimes it's appropriate to create a new package which + provides the basic infrastructure for the other packages + and which manages the shared configuration files. (The + sgml-base package is a good example.) +

+ -

- Games which require protected, privileged access to - high-score files, savegames, etc., may be made - set-group-id (mode 2755) and owned by - root.games, and use files and directories with - appropriate permissions (770 root.games, for - example). They must not be made - set-user-id, as this causes security problems. (If - an attacker can subvert any set-user-id game they can - overwrite the executable of any other, causing other players - of these games to run a Trojan horse program. With a - set-group-id game the attacker only gets access to less - important game data, and if they can get at the other - players' accounts at all it will take considerably more - effort.)

+ + User configuration files ("dotfiles") -

- Some packages, for example some fortune cookie programs, are - configured by the upstream authors to install with their - data files or other static information made unreadable so - that they can only be accessed through set-id programs - provided. You should not do this in a Debian package: anyone can - download the .deb file and read the data from it, - so there is no point making the files unreadable. Not - making the files unreadable also means that you don't have - to make so many programs set-id, which reduces the risk of a - security hole.

+

+ The files in /etc/skel will automatically be + copied into new user accounts by adduser. + No other program should reference the files in + /etc/skel. +

-

- As described in the FHS, binaries of games should be - installed in the directory /usr/games. This also - applies to games that use the X Window System. Manual pages - for games (X and non-X games) should be installed in - /usr/share/man/man6.

- - +

+ Therefore, if a program needs a dotfile to exist in + advance in $HOME to work sensibly, that dotfile + should be installed in /etc/skel and treated as a + configuration file. +

- Documentation +

+ However, programs that require dotfiles in order to + operate sensibly are a bad thing, unless they do create + the dotfiles themselves automatically. +

+

+ Furthermore, programs should be configured by the Debian + default installation to behave as closely to the upstream + default behaviour as possible. +

- - Manual pages +

+ Therefore, if a program in a Debian package needs to be + configured in some way in order to operate sensibly, that + should be done using a site-wide configuration file placed + in /etc. Only if the program doesn't support a + site-wide default configuration and the package maintainer + doesn't have time to add it may a default per-user file be + placed in /etc/skel. +

-

- You should install manual pages in nroff source - form, in appropriate places under /usr/share/man. You - should only use sections 1 to 9 (see the FHS for more - details). You must not install a preformatted `cat - page'.

+

+ /etc/skel should be as empty as we can make it. + This is particularly true because there is no easy (or + necessarily desirable) mechanism for ensuring that the + appropriate dotfiles are copied into the accounts of + existing users when a package is installed. +

+ + + + Log files

- Each program, utility, and function should have an - associated manpage included in the same package. It is - suggested that all configuration files also have a manual - page included as well. + Log files should usually be named + /var/log/package.log. If you have many + log files, or need a separate directory for permission + reasons (/var/log is writable only by + root), you should usually create a directory named + /var/log/package and place your log + files there.

- If no manual page is available for a particular program, - utility, function or configuration file and this is reported - as a bug to the Debian Bug Tracking System, a symbolic link - from the requested manual page 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]/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 - (you can report it yourself, if you like). Do not close the - bug report until a proper manpage is available.

- -

- You may forward a complaint about a missing manpage to the - 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 - you should leave the bug in our bug tracking system open - anyway.

- -

- Manual pages should be installed compressed using gzip - -9.

- -

- If one manpage needs to be accessible via several names it - 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 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 - base of the manpage tree (usually - /usr/share/man). If you do not create any links - (whether symlinks, hard links, or .so directives) - in the filesystem to the alternate names of the manpage, - then you should not rely on man finding your - manpage under those names based solely on the information in - the manpage's header. + Log files must be rotated occasionally so that they don't + grow indefinitely; the best way to do this is to drop a log + rotation configuration file into the directory + /etc/logrotate.d and use the facilities provided by + logrotate.

- Supporting this in man often requires - unreasonable processing time to find a manual page or to - report that none exists, and moves knowledge into man's - database that would be better left in the filesystem. - This support is therefore deprecated and will cease to - be present in the future. + The traditional approach to log files has been to set up + ad hoc log rotation schemes using simple shell + scripts and cron. While this approach is highly + customizable, it requires quite a lot of sysadmin work. + Even though the original Debian system helped a little + by automatically installing a system which can be used + as a template, this was deemed not enough.

- -

- - - - Info documents - -

- Info documents should be installed in /usr/share/info. - They should be compressed with gzip -9.

- -

- Your package should call install-info to update - the Info dir file in its postinst - script when called with a configure argument, for - example: - -install-info --quiet --section Development Development \ - /usr/share/info/foobar.info -

- -

- It is a good idea to specify a section for the location of - your program; this is done with the --section - switch. To determine which section to use, you should look - at /usr/share/info/dir on your system and choose the most - relevant (or create a new section if none of the current - sections are relevant). Note that the --section - flag takes two arguments; the first is a regular expression - to match (case-insensitively) against an existing section, - the second is used when creating a new one.

-

- You should remove the entries in the prerm - script when called with a remove argument: +

+ The use of logrotate, a program developed + by Red Hat, is better, as it centralizes log management. + It has both a configuration file + (/etc/logrotate.conf) and a directory where + packages can drop their individual log rotation + configurations (/etc/logrotate.d). +

+ + Here is a good example for a logrotate config + file (for more information see ): -install-info --quiet --remove /usr/share/info/foobar.info -

+/var/log/foo/*.log { +rotate 12 +weekly +compress +postrotate +/etc/init.d/foo force-reload +endscript +} + + This rotates all files under /var/log/foo, saves 12 + compressed generations, and forces the daemon to reload its + configuration information after the log rotation. +

- If install-info cannot find a description entry - in the Info file you must supply one. See for details.

+ Log files should be removed when the package is + purged (but not when it is only removed). This should be + done by the postrm script when it is called + with the argument purge (see ). +

- Additional documentation - -

- Any additional documentation that comes with the package may - be installed at the discretion of the package maintainer. - Text documentation should be installed in the directory - /usr/share/doc/package, where - package is the name of the package, and - compressed with gzip -9 unless it is small.

- -

- If a package comes with large amounts of documentation which - many users of the package will not require you should create - a separate binary package to contain it, so that it does not - take up disk space on the machines of users who do not need - or want it installed.

- -

- It is often a good idea to put text information files - (READMEs, changelogs, and so forth) that come with - the source package in /usr/share/doc/package - in the binary package. However, you don't need to install - the instructions for building and installing the package, of - course!

+ Permissions and owners

- Files in /usr/share/doc should not be referenced by - any program, and the system administrator should be able to - delete them without causing any programs to break. Any files - that are referenced by programs but are also useful as - standalone documentation should be installed under - /usr/share/package/ with symbolic links - from /usr/share/doc/package/. + The rules in this section are guidelines for general use. + If necessary you may deviate from the details below. + However, if you do so you must make sure that what is done + is secure and you should try to be as consistent as possible + with the rest of the system. You should probably also + discuss it on debian-devel first.

- - - - Accessing the documentation -

- Former Debian releases placed all additional documentation - in /usr/doc/package. This has now - changed to /usr/share/doc/package, - and packages must not put documentation in the directory - /usr/doc/package. -

At this phase of the transition, we no longer require a - symbolic link in /usr/doc/. At a later point, - policy shall change to make the symbolic links a bug.

- + Files should be owned by root.root, and made + writable only by the owner and universally readable (and + executable, if appropriate), that is mode 644 or 755.

- - - - Preferred documentation formats

- The unification of Debian documentation is being carried out - via HTML.

+ 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 + should be owned by the group that needs write access to + it. +

- If your package comes with extensive documentation in a - markup format that can be converted to various other formats - you should if possible ship HTML versions in a binary - package, in the directory - /usr/share/doc/appropriate-package or - its subdirectories. -

- The rationale: The important thing here is that HTML - docs should be available in some package, not - necessarily in the main binary package. -

- + Setuid and setgid executables should be mode 4755 or 2755 + respectively, and owned by the appropriate user or group. + 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 + reason you should not restrict read or execute permissions + on non-set-id executables.

- Other formats such as PostScript may be provided at the - package maintainer's discretion. + Some setuid programs need to be restricted to particular + sets of users, using file permissions. In this case they + should be owned by the uid to which they are set-id, and by + the group which should be allowed to execute them. They + should have mode 4754; again there is no point in making + them unreadable to those users who must not be allowed to + execute them.

- - - - Copyright information

- Every package must be accompanied by a verbatim copy of its - copyright and distribution license in the file - /usr/share/doc/package/copyright. This - file must neither be compressed nor be a symbolic link. + It is possible to arrange that the system administrator can + reconfigure the package to correspond to their local + security policy by changing the permissions on a binary: + they can do this by using dpkg-statoverride, as + described below. + Ordinary files installed by dpkg (as + opposed to conffiles and other similar objects) + normally have their permissions reset to the distributed + permissions when the package is reinstalled. However, + the use of dpkg-statoverride overrides this + default behaviour. If you use this method, you should + remember to describe dpkg-statoverride in + the package documentation; being a relatively new + addition to Debian, it is probably not yet well-known. + + Another method you should consider is to create a group for + people allowed to use the program(s) and make any setuid + executables executable only by that group.

- In addition, the copyright file must say where the upstream - sources (if any) were obtained, and should explain briefly what - modifications were made in the Debian version of the package - compared to the upstream one. It should name the original - authors of the package and the Debian maintainer(s) who were - involved with its creation.

+ If you need to create a new user or group for your package + there are two possibilities. Firstly, you may need to + make some files in the binary package be owned by this + user or group, or you may need to compile the user or + group id (rather than just the name) into the binary + (though this latter should be avoided if possible, as in + this case you need a statically allocated id).

- A copy of the file which will be installed in - /usr/share/doc/package/copyright should - be in debian/copyright in the source package. + If you need a statically allocated id, you must ask for a + user or group id from the base-passwd maintainer, + and must not release the package until you have been + allocated one. Once you have been allocated one you must + either make the package depend on a version of the + base-passwd package with the id present in + /etc/passwd or /etc/group, or arrange for + your package to create the user or group itself with the + correct id (using adduser) in its + preinst or postinst. (Doing it in + the postinst is to be preferred if it is + possible, otherwise a pre-dependency will be needed on the + adduser package.)

- /usr/share/doc/package may be a symbolic - link to another directory in /usr/share/doc only if - the two packages both come from the same source and the - first package Depends on the second. These rules are - important because copyrights must be extractable by - mechanical means. + On the other hand, the program might be able to determine + the uid or gid from the user or group name at runtime, so + that a dynamically allocated id can be used. In this case + you should choose an appropriate user or group name, + discussing this on debian-devel and checking + with the adduser in the preinst or + postinst script (again, the latter is to be + preferred if it is possible).

- Packages distributed under the UCB BSD license, the Artistic - license, the GNU GPL, and the GNU LGPL should refer to the - files /usr/share/common-licenses/BSD, - /usr/share/common-licenses/Artistic, - /usr/share/common-licenses/GPL, and - /usr/share/common-licenses/LGPL respectively, - rather than quoting them in the copyright file. + Note that changing the numeric value of an id associated + with a name is very difficult, and involves searching the + file system for all appropriate files. You need to think + carefully whether a static or dynamic id is required, since + changing your mind later will cause problems.

-

- You should not use the copyright file as a general README - file. If your package has such a file it should be - installed in /usr/share/doc/package/README or - README.Debian or some other appropriate place.

+ The use of dpkg-statoverride +

+ This section is not intended as policy, but as a + description of the use of dpkg-statoverride. +

+ +

+ dpkg-statoverride is a replacement for the + deprecated suidmanager package. Packages which + previously used suidmanager should have a + Conflicts: suidmanager (<< 0.50) entry (or even + (<< 0.52)), and calls to suidregister + and suidunregister should now be simply removed + from the maintainer scripts. +

+ +

+ If a system administrator wishes to have a file (or + directory or other such thing) installed with owner and + permissions different from those in the distributed Debian + package, he can use the dpkg-statoverride + program to instruct dpkg to use the different + settings every time the file is installed. Thus the + package maintainer should distribute the files with their + normal permissions, and leave it for the system + administrator to make any desired changes. For example, a + daemon which is normally required to be setuid root, but + in certain situations could be used without being setuid, + should be installed setuid in the .deb. Then the + local system administrator can change this if they wish. + If there are two standard ways of doing it, the package + maintainer can use debconf to find out the + preference, and call dpkg-statoverride in the + maintainer script if necessary to accommodate the system + administrator's choice. +

+ +

+ Given the above, dpkg-statoverride is + essentially a tool for system administrators and would not + normally be needed in the maintainer scripts. There is + one type of situation, though, where calls to + dpkg-statoverride would be needed in the + maintainer scripts, and that involves packages which use + dynamically allocated user or group ids. In such a + situation, something like the following idiom can be very + helpful in the package's postinst, where + sysuser is a dynamically allocated id: + +for i in /usr/bin/foo /usr/sbin/bar +do + if ! dpkg-statoverride --list $i >/dev/null + then + dpkg-statoverride --update --add sysuser root 4755 $i + fi +done + + The corresponding dpkg-statoverride --remove + calls can then be made unconditionally when the package is + purged. +

+ + - - Examples -

- 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 - for the benefit of the system administrator and users as - documentation only. Architecture-specific example files - should be installed in a directory - /usr/lib/package/examples with symbolic - links to them from - /usr/share/doc/package/examples, or the - latter directory itself may be a symbolic link to the - former. -

- + + Customized programs - - Changelog files + + Architecture specification strings

- Packages that are not Debian-native must contain a - compressed copy of the debian/changelog file from - the Debian source tree in - /usr/share/doc/package with the name - changelog.Debian.gz. If an upstream changelog is - available, it should be accessible as - /usr/share/doc/package/changelog.gz in - plain text. If the upstream changelog is distributed in - HTML, it should be made available in that form as - /usr/share/doc/package/changelog.html.gz - and a plain text changelog.gz should be generated - from it using, for example, lynx -dump -nolist. If - the upstream changelog files do not already conform to this - naming convention, then this may be achieved either by - renaming the files, or by adding a symbolic link, at the - maintainer's discretion. -

- Rationale: People should not have to look in places for - upstream changelogs merely because they are given - different names or are distributed in HTML format. -

- + If a program needs to specify an architecture specification + string in some place, the following format should be + used: arch-os + The following architectures and operating systems are + currently recognised by dpkg-architecture. + The architecture, arch, is one of + the following: alpha, arm, + hppa, i386, ia64, + m68k, mips, mipsel, + powerpc, s390, sh, + sheb, sparc and sparc64. The + operating system, os, is one of: + linux, gnu, freebsd and + openbsd. Use of gnu in this string is + reserved for the GNU/Hurd operating system. + .

- /usr/share/doc/package may be a symbolic - link to another directory in /usr/share/doc only if - the two packages both come from the same source and the - first package Depends on the second. + Note that we don't want to use + arch-debian-linux to apply to the rule + architecture-vendor-os + since this would make our programs incompatible with other + Linux distributions. We also don't use something like + arch-unknown-linux, since the + unknown does not look very good.

+ + + Daemons

- All of these files should be installed compressed using - gzip -9, as they will become large with time even - if they start out small. + The configuration files /etc/services, + /etc/protocols, and /etc/rpc are managed + by the netbase package and must not be modified + by other packages.

- If the package has only one changelog which is used both as - the Debian changelog and the upstream one because there is - no separate upstream maintainer then that changelog should - usually be installed as - /usr/share/doc/package/changelog.gz; if - there is a separate upstream maintainer, but no upstream - changelog, then the Debian changelog should still be called - changelog.Debian.gz.

- - - - - Introduction and scope of these appendices - -

- These appendices are taken essentially verbatim from the - now-deprecated Packaging Manual, version 3.2.1.0. They are - the chapters which are likely to be of use to package - maintainers and which have not already been included in the - policy document itself. Most of these sections are very likely - not relevant to policy; they should be treated as - documentation for the packaging system. Please note that these - appendices are included for convenience, and for historical - reasons: they used to be part of policy package, and they have - not yet been incorporated into dpkg documentation. However, - they still have value, and hence they are presented here. -

-

- They have not yet been checked to ensure that they are - compatible with the contents of policy, and if there are any - contradictions, the version in the main policy document takes - precedence. The remaining chapters of the old Packaging - Manual have also not been read in detail to ensure that there - are not parts which have been left out. Both of these will be - done in due course. -

- -

- dpkg is a suite of programs for creating binary - package files and installing and removing them on Unix - systems. -

- dpkg is targetted primarily at Debian - GNU/Linux, but may work on or be ported to other - systems. -

- -

- -

- The binary packages are designed for the management of - installed executable programs (usually compiled binaries) and - their associated data, though source code examples and - documentation are provided as part of some packages.

- -

- This manual describes the technical aspects of creating Debian - binary packages (.deb files). It documents the - behaviour of the package management programs - dpkg, dselect et al. and the way - they interact with packages.

- -

- It also documents the interaction between - dselect's core and the access method scripts it - uses to actually install the selected packages, and describes - how to create a new access method.

- -

- This manual does not go into detail about the options and - usage of the package building and installation tools. It - should therefore be read in conjuction with those programs' - manpages. -

- -

- The utility programs which are provided with dpkg - for managing various system configuration and similar issues, - such as update-rc.d and - install-info, are not described in detail here - - please see their manpages. -

- -

- It does not describe the policy requirements imposed - on Debian packages, such as the permissions on files and - directories, documentation requirements, upload procedure, and - so on. You should see the Debian packaging policy manual for - these details. (Many of them will probably turn out to be - helpful even if you don't plan to upload your package and make - it available as part of the distribution.) -

- -

- It is assumed that the reader is reasonably familiar with the - dpkg System Administrators' manual. - Unfortunately this manual does not yet exist. -

- -

- The Debian version of the FSF's GNU hello program is provided - as an example for people wishing to create Debian - packages. The Debian debmake package is - recommended as a very helpful tool in creating and maintaining - Debian packages. However, while the tools and examples are - helpful, they do not replace the need to read and follow the - Policy and Programmer's Manual.

- - - Binary packages (from old - Packaging Manual) - - -

- The binary package has two main sections. The first part - consists of various control information files and scripts used - by dpkg when installing and removing. See . -

- -

- The second part is an archive containing the files and - directories to be installed. -

- -

- In the future binary packages may also contain other - components, such as checksums and digital signatures. The - format for the archive is described in full in the - deb(5) manpage. -

- - - Creating package files - - dpkg-deb - + If a package requires a new entry in one of these files, the + maintainer should get in contact with the + netbase maintainer, who will add the entries + and release a new version of the netbase + package. +

- All manipulation of binary package files is done by - dpkg-deb; it's the only program that has - knowledge of the format. (dpkg-deb may be - invoked by calling dpkg, as dpkg - will spot that the options requested are appropriate to - dpkg-deb and invoke that instead with the same - arguments.) + The configuration file /etc/inetd.conf must not be + modified by the package's scripts except via the + update-inetd script or the + DebianNet.pm Perl module. See their documentation + for details on how to add entries.

- In order to create a binary package you must make a - directory tree which contains all the files and directories - you want to have in the filesystem data part of the package. - In Debian-format source packages this directory is usually - debian/tmp, relative to the top of the package's - source tree. + If a package wants to install an example entry into + /etc/inetd.conf, the entry must be preceded with + exactly one hash character (#). Such lines are + treated as "commented out by user" by the + update-inetd script and are not changed or + activated during package updates.

+ + + + Using pseudo-ttys and modifying wtmp, utmp and + lastlog

- They should have the locations (relative to the root of the - directory tree you're constructing) ownerships and - permissions which you want them to have on the system when - they are installed. + Some programs need to create pseudo-ttys. This should be done + using Unix98 ptys if the C library supports it. The resulting + program must not be installed setuid root, unless that + is required for other functionality.

- With current versions of dpkg the uid/username - and gid/groupname mappings for the users and groups being - used should be the same on the system where the package is - built and the one where it is installed. + The files /var/run/utmp, /var/log/wtmp and + /var/log/lastlog must be installed writeable by + group utmp. Programs which need to modify those + files must be installed setgid utmp.

+ + + + Editors and pagers

- You need to add one special directory to the root of the - miniature filesystem tree you're creating: - DEBIAN. It should contain the control - information files, notably the binary package control file - (see ). + Some programs have the ability to launch an editor or pager + program to edit or display a text document. Since there are + lots of different editors and pagers available in the Debian + distribution, the system administrator and each user should + have the possibility to choose his/her preferred editor and + pager.

- The DEBIAN directory will not appear in the - filesystem archive of the package, and so won't be installed - by dpkg when the package is installed. + In addition, every program should choose a good default + editor/pager if none is selected by the user or system + administrator.

- When you've prepared the package, you should invoke: - - dpkg --build directory - + Thus, every program that launches an editor or pager must + use the EDITOR or PAGER environment variable to determine + the editor or pager the user wishes to use. If these + variables are not set, the programs /usr/bin/editor + and /usr/bin/pager should be used, respectively.

- This will build the package in - directory.deb. (dpkg knows - that --build is a dpkg-deb option, so - it invokes dpkg-deb with the same arguments to - build the package.) + These two files are managed through the dpkg + "alternatives" mechanism. Thus every package providing an + editor or pager must call the + update-alternatives script to register these + programs.

- See the manpage for details of how - to examine the contents of this newly-created file. You may find the - output of following commands enlightening: - - dpkg-deb --info filename.deb - dpkg-deb --contents filename.deb - dpkg --contents filename.deb - - To view the copyright file for a package you could use this command: - - dpkg --fsys-tarfile filename.deb | tar xof usr/share/doc/\*copyright | less - + If it is very hard to adapt a program to make use of the + EDITOR or PAGER variables, that program may be configured to + use /usr/bin/sensible-editor and + /usr/bin/sensible-pager as the editor or pager + program respectively. These are two scripts provided in the + Debian base system that check the EDITOR and PAGER variables + and launch the appropriate program, and fall back to + /usr/bin/editor and /usr/bin/pager if the + variable is not set.

- - - - - Package control information files -

- The control information portion of a binary package is a - collection of files with names known to dpkg. - It will treat the contents of these files specially - some - of them contain information used by dpkg when - installing or removing the package; others are scripts which - the package maintainer wants dpkg to run. + A program may also use the VISUAL environment variable to + determine the user's choice of editor. If it exists, it + should take precedence over EDITOR. This is in fact what + /usr/bin/sensible-editor does.

- It is possible to put other files in the package control - area, but this is not generally a good idea (though they - will largely be ignored). + It is not required for a package to depend on + editor and pager, nor is it required for a + package to provide such virtual packages. + The Debian base system already provides an editor and a + pager program. +

+ + + + Web servers and applications

- Here is a brief list of the control info files supported by - dpkg and a summary of what they're used for. + This section describes the locations and URLs that should + be used by all web servers and web applications in the + Debian system.

- - control + - -

- This is the key description file used by - dpkg. It specifies the package's name - and version, gives its description for the user, - states its relationships with other packages, and so - forth. See . -

- -

- It is usually generated automatically from information - in the source package by the - dpkg-gencontrol program, and with - assistance from dpkg-shlibdeps. See .

+ Cgi-bin executable files are installed in the + directory + +/usr/lib/cgi-bin/cgi-bin-name + + and should be referred to as + +http://localhost/cgi-bin/cgi-bin-name + - postinst, preinst, postrm, - prerm - +

Access to HTML documents

- These are exectuable files (usually scripts) which - dpkg runs during installation, upgrade - and removal of packages. They allow the package to - deal with matters which are particular to that package - or require more complicated processing than that - provided by dpkg. Details of when and - how they are called are in . -

- -

- It is very important to make these scripts - idempotent. - -

- 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. + HTML documents for a package are stored in + /usr/share/doc/package + and can be referred to as + +http://localhost/doc/package/filename +

- The maintainer scripts are guaranteed to run with a - controlling terminal and can interact with the user. - If they need to prompt for passwords, do full-screen - interaction or something similar you should do these - things to and from /dev/tty, since - dpkg will at some point redirect scripts' - standard input and output so that it can log the - installation process. Likewise, because these scripts - may be executed with standard output redirected into a - pipe for logging purposes, Perl scripts should set - unbuffered output by setting $|=1 so that the - output is printed immediately rather than being - buffered. + The web server should restrict access to the document + tree so that only clients on the same host can read + the documents. If the web server does not support such + access controls, then it should not provide access at + all, or ask about providing access during installation.

- -

- Each script should return a zero exit status for - success, or a nonzero one for failure.

 - conffiles - +

Web Document Root

- This file contains a list of configuration files which - are to be handled automatically by dpkg - (see ). Note that not necessarily - every configuration file should be listed here.

+ Web Applications should try to avoid storing files in + the Web Document Root. Instead they should use the + /usr/share/doc/package directory for + documents and register the Web Application via the + menu package. If access to the web document root is + unavoidable then use + +/var/www + + as the Document Root. This might be just a symbolic + link to the location where the system administrator + has put the real document root. +

- shlibs - - + +

+ -

- This file contains a list of the shared libraries - supplied by the package, with dependency details for - each. This is used by dpkg-shlibdeps - when it determines what dependencies are required in a - package control file. The shlibs file format - is described on . -

- - + + Mail transport, delivery and user agents + +

+ Debian packages which process electronic mail, whether mail + user agents (MUAs) or mail transport agents (MTAs), must + ensure that they are compatible with the configuration + decisions below. Failure to do this may result in lost + mail, broken From: lines, and other serious brain + damage!

- - - The main control information file: control -

- The most important control information file used by - dpkg when it installs a package is - control. It contains all the package's `vital - statistics'. + The mail spool is /var/mail and the interface to + send a mail message is /usr/sbin/sendmail (as 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.

- The binary package control files of packages built from - Debian sources are made by a special tool, - dpkg-gencontrol, which reads - debian/control and debian/changelog to - find the information it needs. See for - more details. + All Debian MUAs, MTAs, MDAs and other mailbox accessing + programs (such as IMAP daemons) must lock the mailbox in an + NFS-safe way. This means that fcntl() locking must + be combined with dot locking. To avoid deadlocks, a program + should use fcntl() first and dot locking after + this, or alternatively implement the two locking methods in + a non blocking way + If it is not possible to establish both locks, the + system shouldn't wait for the second lock to be + established, but remove the first lock, wait a (random) + time, and start over locking again. + . Using the functions maillock and + mailunlock provided by the + liblockfile* + You will need to depend on liblockfile1 (>>1.01) + to use these functions. + packages is the recommended way to realize this.

- The fields in binary package control files are: - - -

Package (mandatory)

- - -

Version (mandatory)

- -

Architecture - (mandatory) - -

- This field should appear in all packages, though - dpkg doesn't require it yet so that - old packages can still be installed. -

- -

- - -

Depends, - Provides et al.

- - -

Essential

- - -

Maintainer

- - -

Section, - Priority

- - -

Source

- - -

Description

- - -

- Installed-Size -

- - + Mailboxes are generally mode 660 + user.mail unless the system + administrator has chosen otherwise. A MUA may remove a + mailbox (unless it has nonstandard permissions) in which + case the MTA or another MUA must recreate it if needed. + Mailboxes must be writable by group mail. +

+ +

+ The mail spool is 2775 root.mail, and MUAs should + be setgid mail to do the locking mentioned above (and + must obviously avoid accessing other users' mailboxes + using this privilege).

+ +

+ /etc/aliases is the source file for the system mail + 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 + packages must come with a newaliases program, + even if it does nothing, but older MTA packages did not do + this so programs should not fail if newaliases + cannot be found. Note that because of this, all MTA + packages must have Provides, Conflicts and + Replaces: mail-transport-agent control file + fields. +

- A description of the syntax of control files and the purpose - of these fields is available in . + The convention of writing forward to + address in the mailbox itself is not + supported. Use a .forward file instead.

+ +

+ The rmail program used by UUCP + for incoming mail should be /usr/sbin/rmail. + Likewise, rsmtp, for receiving + batch-SMTP-over-UUCP, should be /usr/sbin/rsmtp if it + is supported.

+ +

+ If your package needs to know what hostname to use on (for + example) outgoing news and mail messages which are generated + locally, you should use the file /etc/mailname. It + will contain the portion after the username and @ + (at) sign for email addresses of users on the machine + (followed by a newline).

- - - Time Stamps

- Maintainers are encouraged to 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 - by knowing the age of the file, for example, you could - recognize that some documentation is very old by looking - at the modification time, so it would be nice if the - modification time of the upstream source would be - preserved. -

- + Such package should check for the existence of this file + when it is being configured. If it exists, it should be + used without comment, although an MTA's configuration script + may wish to prompt the user even if it finds that this file + exists. If the file does not exist, the package should + prompt the user for the value (preferably using + debconf) and store it in /etc/mailname + as well as using it in the package's 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 could say something like: + +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.

- - - Source packages (from old Packaging Manual) + + News system configuration -

- The Debian binary packages in the distribution are generated - from Debian sources, which are in a special format to assist - the easy and automatic building of binaries. -

+

+ All the configuration files related to the NNTP (news) + servers and clients should be located under + /etc/news.

-

- There was a previous version of the Debian source format, - which is now being phased out. Instructions for converting an - old-style package are given in the Debian policy manual. -

+

+ There are some configuration issues that apply to a number + of news clients and server packages on the machine. These + are: - - Tools for processing source packages + + /etc/news/organization + + A string which should appear as the + organization header for all messages posted + by NNTP clients on the machine + -

- Various tools are provided for manipulating source packages; - they pack and unpack sources and help build of binary - packages and help manage the distribution of new versions. -

+ /etc/news/server + + Contains the FQDN of the upstream NNTP + server, or localhost if the local machine is + an NNTP server. + + -

- They are introduced and typical uses described here; see - for full - documentation about their arguments and operation. + Other global files may be added as required for cross-package news + configuration.

+ -

- For examples of how to construct a Debian source package, - and how to use those utilities that are used by Debian - source packages, please see the hello example - package. -

+ + + Programs for the X Window System - - dpkg-source - packs and unpacks Debian source - packages - + Providing X support and package priorities

- This program is frequently used by hand, and is also - called from package-independent automated building scripts - such as dpkg-buildpackage. + Programs that can be configured with support for the X + Window System must be configured to do so and must declare + any package dependencies necessary to satisfy their + runtime requirements when using the X Window System. If + such a package is of higher priority than the X packages + on which it depends, it is required that either the + X-specific components be split into a separate package, or + that an alternative version of the package, which includes + X support, be provided, or that the package's priority be + lowered.

+ + + + Packages providing an X server

- To unpack a package it is typically invoked with - - dpkg-source -x .../path/to/filename.dsc - + Packages that provide an X server that, directly or + indirectly, communicates with real input and display + hardware should declare in their control data that they + provide the virtual package xserver. + This implements current practice, and provides an + actual policy for usage of the xserver + virtual package which appears in the virtual packages + list. In a nutshell, X servers that interface + directly with the display and input hardware or via + another subsystem (e.g., GGI) should provide + xserver. Things like Xvfb, + Xnest, and Xprt should not. +

+ -

- with the filename.tar.gz and - filename.diff.gz (if applicable) in - the same directory. It unpacks into - package-version, and if - applicable - package-version.orig, in - the current directory. -

+ + Packages providing a terminal emulator

- To create a packed source archive it is typically invoked: - - dpkg-source -b package-version - + Packages that provide a terminal emulator for the X Window + System which meet the criteria listed below should declare + in their control data that they provide the virtual + package x-terminal-emulator. They should also + register themselves as an alternative for + /usr/bin/x-terminal-emulator, with a priority of + 20.

- This will create the .dsc, .tar.gz and - .diff.gz (if appropriate) in the current - directory. dpkg-source does not clean the - source tree first - this must be done separately if it is - required. -

+ To be an x-terminal-emulator, a program must: + + + Be able to emulate a DEC VT100 terminal, or a + compatible terminal. + -

- See also .

- + + Support the command-line option -e + command, which creates a new + terminal window + "New terminal window" does not necessarily mean + a new top-level X window directly parented by + the window manager; it could, if the terminal + emulator application were so coded, be a new + "view" in a multiple-document interface (MDI). + + and runs the specified command, + interpreting the entirity of the rest of the command + line as a command to pass straight to exec, in the + manner that xterm does. + + + Support the command-line option -T + title, which creates a new terminal + window with the window title title. + + +

+ - - dpkg-buildpackage - overall package-building - control script - - -

- dpkg-buildpackage is a script which invokes - dpkg-source, the debian/rules - targets clean, build and - binary, dpkg-genchanges and - pgp to build a signed source and binary - package upload. -

+ Packages providing a window manager

- It is usually invoked by hand from the top level of the - built or unbuilt source directory. It may be invoked with - no arguments; useful arguments include: - - -uc, -us - -

- Do not PGP-sign the .changes file or the - source package .dsc file, respectively.

- - -ppgp-command + Packages that provide a window manager should declare in + their control data that they provide the virtual package + x-window-manager. They should also register + themselves as an alternative for + /usr/bin/x-window-manager, with a priority + calculated as follows: + -

- Invoke pgp-command instead of finding - pgp on the PATH. - pgp-command must behave just like - pgp.

+ Start with a priority of 20. - -rroot-command + -

- When root privilege is required, invoke the command - root-command. root-command - should invoke its first argument as a command, from - the PATH if necessary, and pass its - second and subsequent arguments to the command it - calls. If no root-command is supplied - then dpkg-buildpackage will take no - special action to gain root privilege, so that for - most packages it will have to be invoked as root to - start with.

+ If the window manager supports the Debian menu + system, add 20 points if this support is available + in the package's default configuration (i.e., no + configuration files belonging to the system or user + have to be edited to activate the feature); if + configuration files must be modified, add only 10 + points. +

- -b, -B + + + If the window manager complies with , + written by the , add 40 points. + + -

- Two types of binary-only build and upload - see - . -

+ If the window manager permits the X session to be + restarted using a different window manager + (without killing the X server) in its default + configuration, add 10 points; otherwise add none. - +

- - dpkg-gencontrol - generates binary package - control files - + Packages providing fonts

- This program is usually called from debian/rules - (see ) in the top level of the source - tree. -

+ Packages that provide fonts for the X Window + System + For the purposes of Debian Policy, a "font for the X + Window System" is one which is accessed via X protocol + requests. Fonts for the Linux console, for PostScript + renderers, or any other purpose, do not fit this + definition. Any tool which makes such fonts available + to the X Window System, however, must abide by this + font policy. + + must do a number of things to ensure that they are both + available without modification of the X or font server + configuration, and that they do not corrupt files used by + other font packages to register information about + themselves. + + + Fonts of any type supported by the X Window System + must be in a separate binary package from any + executables, libraries, or documentation (except + that specific to the fonts shipped, such as their + license information). If one or more of the fonts + so packaged are necessary for proper operation of + the package with which they are associated the font + package may be Recommended; if the fonts merely + provide an enhancement, a Suggests relationship may + be used. Packages must not Depend on font + packages. + This is because the X server may retrieve fonts + from the local filesystem or over the network + from an X font server; the Debian package system + is empowered to deal only with the local + filesystem. + + -

- This is usually done just before the files and directories in the - temporary directory tree where the package is being built have their - permissions and ownerships set and the package is constructed using - dpkg-deb/ - -

- This is so that the control file which is produced has - the right permissions -

- . -

+ + BDF fonts must be converted to PCF fonts with the + bdftopcf utility (available in the + xutils package, gzipped, and + placed in a directory that corresponds to their + resolution: + + + 100 dpi fonts must be placed in + /usr/X11R6/lib/X11/fonts/100dpi/. + -

- dpkg-gencontrol must be called after all the - files which are to go into the package have been placed in - the temporary build directory, so that its calculation of - the installed size of a package is correct. -

+ + 75 dpi fonts must be placed in + /usr/X11R6/lib/X11/fonts/75dpi/. + -

- It is also necessary for dpkg-gencontrol to - be run after dpkg-shlibdeps so that the - variable substitutions created by - dpkg-shlibdeps in debian/substvars - are available. -

+ + Character-cell fonts, cursor fonts, and other + low-resolution fonts must be placed in + /usr/X11R6/lib/X11/fonts/misc/. + + + -

- For a package which generates only one binary package, and - which builds it in debian/tmp relative to the top - of the source package, it is usually sufficient to call - dpkg-gencontrol. -

+ + Speedo fonts must be placed in + /usr/X11R6/lib/X11/fonts/Speedo/. + -

- Sources which build several binaries will typically need - something like: - - dpkg-gencontrol -Pdebian/tmp-pkg -ppackage - The -P tells - dpkg-gencontrol that the package is being - built in a non-default directory, and the -p - tells it which package's control file should be generated. -

+ + Type 1 fonts must be placed in + /usr/X11R6/lib/X11/fonts/Type1/. If font + metric files are available, they must be placed here + as well. + -

- dpkg-gencontrol also adds information to the - list of files in debian/files, for the benefit of - (for example) a future invocation of - dpkg-genchanges.

- + + Subdirectories of /usr/X11R6/lib/X11/fonts/ + other than those listed above must be neither + created nor used. (The PEX, CID, + and cyrillic directories are excepted for + historical reasons, but installation of files into + these directories remains discouraged.) + - - - dpkg-shlibdeps - calculates shared library - dependencies - + + Font packages may, instead of placing files directly + in the X font directories listed above, provide + symbolic links in that font directory pointing to + the files' actual location in the filesystem. Such + a location must comply with the FHS. + -

- This program is usually called from debian/rules - just before dpkg-gencontrol (see ), in the top level of the source tree. -

+ + Font packages should not contain both 75dpi and + 100dpi versions of a font. If both are available, + they should be provided in separate binary packages + with -75dpi or -100dpi appended to + the names of the packages containing the + corresponding fonts. + -

- Its arguments are executables. - -

- In a forthcoming dpkg version, - dpkg-shlibdeps would be required to be - called on shared libraries as well. -

-

- They may be specified either in the locations in the - source tree where they are created or in the locations - in the temporary build tree where they are installed - prior to binary package creation. -

- for which shared library dependencies should - be included in the binary package's control file. -

+ + Fonts destined for the misc subdirectory + should not be included in the same package as 75dpi + or 100dpi fonts; instead, they should be provided in + a separate package with -misc appended to + its name. + -

- If some of the found shared libraries should only - warrant a Recommends or Suggests, or if - some warrant a Pre-Depends, this can be achieved - by using the -ddependency-field option - before those executable(s). (Each -d option - takes effect until the next -d.) -

+ + 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. + + + + fonts.alias and fonts.scale + files, if needed, should be provided in the + directory + /etc/X11/fonts/fontdir/package.extension, + where fontdir is the name of the + subdirectory of + /usr/X11R6/lib/X11/fonts/ where the + package's corresponding fonts are stored + (e.g., 75dpi or misc), + package is the name of the package + that provides these fonts, and + extension is either scale + or alias, whichever corresponds to + the file contents. + + + + + + Font packages must declare a dependency on + xutils (>> 4.0.3) in their control + data. + + + + Font packages that provide one or more + fonts.scale files as described above must + invoke update-fonts-scale on each + directory into which they installed fonts + before invoking + update-fonts-dir on that directory. + This invocation must occur in both the + postinst (for all arguments) and + postrm (for all arguments except + upgrade) scripts. + + + + Font packages that provide one or more + fonts.alias files as described above must + invoke update-fonts-alias on each + directory into which they installed fonts. This + invocation must occur in both the + postinst (for all arguments) and + postrm (for all arguments except + upgrade) scripts. + -

- dpkg-shlibdeps does not directly cause the - output control file to be modified. Instead by default it - adds to the debian/substvars file variable - settings like shlibs:Depends. These variable - settings must be referenced in dependency fields in the - appropriate per-binary-package sections of the source - control file. -

+ + Font packages must invoke + update-fonts-dir on each directory into + which they installed fonts. This invocation must + occur in both the postinst (for all + arguments) and postrm (for all + arguments except upgrade) scripts. + -

- For example, the procps package generates two - kinds of binaries, simple C binaries like ps - which require a predependency and full-screen ncurses - binaries like top which require only a - recommendation. It can say in its debian/rules: - - dpkg-shlibdeps -dPre-Depends ps -dRecommends top - - and then in its main control file debian/control: - - ... - Package: procps - Pre-Depends: ${shlibs:Pre-Depends} - Recommends: ${shlibs:Recommends} - ... - -

+ + Font packages must not provide alias names for the + fonts they include which collide with alias names + already in use by fonts already packaged. + -

- Sources which produce several binary packages with - different shared library dependency requirements can use - the -pvarnameprefix option to override - the default shlibs: prefix (one invocation of - dpkg-shlibdeps per setting of this option). - They can thus produce several sets of dependency - variables, each of the form - varnameprefix:dependencyfield, - which can be referred to in the appropriate parts of the - binary package control files. + + Font packages must not provide fonts with the same + XLFD registry name as another font already packaged. + +

- - - dpkg-distaddfile - adds a file to - debian/files - + Application defaults files

- Some packages' uploads need to include files other than - the source and binary package files. + 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 manual is also permitted). They must be + registered as conffiles or handled as + configuration files. Packages must not provide the + directory /usr/X11R6/lib/X11/app-defaults/.

- dpkg-distaddfile adds a file to the - debian/files file so that it will be included in - the .changes file when - dpkg-genchanges is run. + Customization of programs' X resources may also be + supported with the provision of a file with the same name + as that of the package placed in the + /etc/X11/Xresources/ directory, which must + registered as a conffile or handled as a + configuration file. + Note that this mechanism is not the same as using + app-defaults; app-defaults are tied to the client + binary on the local filesystem, whereas X resources + are stored in the X server and affect all connecting + clients. + + Important: packages that install files into the + /etc/X11/Xresources/ directory must conflict with + xbase (<< 3.3.2.3a-2); if this is not done + it is possible for the installing package to destroy a + previously-existing /etc/X11/Xresources file + which had been customized by the system administrator.

+ -

- It is usually invoked from the binary target of - debian/rules: - - dpkg-distaddfile filename section priority - - The filename is relative to the directory where - dpkg-genchanges will expect to find it - this - is usually the directory above the top level of the source - tree. The debian/rules target should put the - file there just before or just after calling - dpkg-distaddfile. -

+ + Installation directory issues

- The section and priority are passed - unchanged into the resulting .changes file. See - . + Packages using the X Window System should not be + configured to install files under the /usr/X11R6/ + directory unless they use imake. The + /usr/X11R6/ directory hierarchy should be + regarded as deprecated for all packages except the X + Window System itself, and those which use the + imake program it provides, in which case the + packages may transition out of the /usr/X11R6/ + directory at the maintainer's discretion. + Imake-using programs are exempt because, + as long as they are written correctly, the pathnames + they use to locate resources and install themselves + are derived wholly from the X Window System + configuration. Thus, in the event that the X Window + System moves to /usr/X11R7/, + /usr/X12/, or just plain /usr/, all + that is required for these programs is a recompile + against the corresponding X Window System library + development packages. +

- - - - dpkg-genchanges - generates a .changes upload - control file -

- This program is usually called by package-independent - automatic building scripts such as - dpkg-buildpackage, but it may also be called - by hand. + Programs that use GNU autoconf and + automake are usually easily configured at + compile time to use /usr/ instead of + /usr/X11R6/, and this should be done whenever + possible. 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.

- It is usually called in the top level of a built source - tree, and when invoked with no arguments will print out a - straightforward .changes file based on the - information in the source package's changelog and control - file and the binary and source packages which should have - been built. + 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. (The use of symbolic links from the + X11R6 directories to other FHS-compliant + locations is encouraged if the program is not easily + configured to look elsewhere for its files.)

- - - - dpkg-parsechangelog - produces parsed representation of - a changelog -

- This program is used internally by - dpkg-source et al. It may also occasionally - be useful in debian/rules and elsewhere. It - parses a changelog, debian/changelog by default, - and prints a control-file format representation of the - information in it to standard output. + 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 other FHS-compliant + locations.

- dpkg-architecture - - information about the build and host system - - -

- This program can be used manually, but is also invoked by - dpkg-buildpackage or debian/rules to set - to set environment or make variables which specify the build and - host architecture for the package building process. -

- - - - The Debianised source tree - - -

- The source archive scheme described later is intended to - allow a Debianised source tree with some associated control - information to be reproduced and transported easily. The - Debianised source tree is a version of the original program - with certain files added for the benefit of the - Debianisation process, and with any other changes required - made to the rest of the source code and installation - scripts. -

- -

- The extra files created for Debian are in the subdirectory - debian of the top level of the Debianised source - tree. They are described below. -

- - debian/rules - the main building - script - - -

- This file is an executable makefile, and contains the - package-specific recipies for compiling the package and - building binary package(s) out of the source. -

+ + The OSF/Motif and OpenMotif libraries

- It must start with the line #!/usr/bin/make -f, - so that it can be invoked by saying its name rather than - invoking make explicitly. + Programs that require the non-DFSG-compliant OSF/Motif or + OpenMotif libraries + OSF/Motif and OpenMotif are collectively referred to as + "Motif" in this policy document. + + should be compiled against and tested with LessTif (a free + re-implementation of Motif) instead. If the maintainer + judges that the program or programs do not work + sufficiently well with LessTif to be distributed and + supported, but do so when compiled against Motif, then two + versions of the package should be created; one linked + statically against Motif and with -smotif + appended to the package name, and one linked dynamically + against Motif and with -dmotif appended to the + package name.

- Since an interactive debian/rules script makes it - impossible to autocompile that package and also makes it - hard for other people to reproduce the same binary - package, all required targets have to be - non-interactive. At a minimul, required targets are the - ones called by dpkg-buildpackage, namely, - clean, binary, binary-arch, and - build. It also follows that any target that these - targets depend on must also be non-interactive. + Both Motif-linked versions are dependent + upon non-DFSG-compliant software and thus cannot be + uploaded to the main distribution; if the + software is itself DFSG-compliant it may be uploaded to + the contrib distribution. While known existing + versions of Motif permit unlimited redistribution of + binaries linked against the library (whether statically or + dynamically), it is the package maintainer's + responsibility to determine whether this is permitted by + the license of the copy of Motif in his or her possession.

+ + -

- The targets which are required to be present are: - - 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. -

- -

- A package may also provide both of the targets - build-arch and build-indep. The - build-arch target, if provided, should - perform all non-interactive configuration and - compilation required for producing all - architecture-dependant binary packages (those packages - for which the body of the Architecture field - in debian/control is not all). - Similarly, the build-indep target, if - provided, should perform all non-interactive - configuration and compilation required for producing - all architecture-independent binary packages (those - packages for which the body of the - Architecture field in debian/control - is all). The build target should - depend on those of the targets build-arch and - build-indep that are provided in the rules - file. -

- -

- If one or both of the targets build-arch and - build-indep are not provided, then invoking - debian/rules with one of the not-provided - targets as arguments should produce a exit status code - of 2. Usually this is provided automatically by make - if the target is missing. -

- -

- For some packages, notably ones where the same - source tree is compiled in different ways to produce - two binary packages, the build target does - not make much sense. For these packages it is good - enough to provide two (or more) targets - (build-a and build-b or whatever) - for each of the ways of building the package, and a - build target that does nothing. The - binary target will have to build the - package in each of the possible ways and make the - binary package out of each. -

- -

- The targets build, build-arch - and build-indep target must not do - anything that might require root privilege. -

- -

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

+ + Perl programs and modules -

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

- +

+ Perl programs and modules should follow the current Perl policy. +

- binary, binary-arch, - binary-indep - - -

- The binary target should 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 - architecture, and binary-indep builds - those which are not. -

+

+ The Perl policy can be found in the perl-policy + files in the debian-policy package. + It is also available from the Debian web mirrors at + . +

+ -

- binary should usually be a target with - no commands which simply depends on - binary-arch and - binary-indep. -

+ + Emacs lisp programs -

- Both binary-* targets 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), - using dpkg-gencontrol to make their - control files and dpkg-deb to build - them and place them in the parent of the top level - directory. -

+

+ Please refer to the "Debian Emacs Policy" for details of how to + package emacs lisp programs. +

-

- 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, but should always - succeed. -

+

+ The Emacs policy is available in + debian-emacs-policy.gz of the + emacsen-common package. + It is also available from the Debian web mirrors at + . +

+ -

- describes how to construct - binary packages. -

+ + Games -

- The binary targets must be invoked as - root. -

- +

+ The permissions on /var/games are mode 755, owner + root and group root. +

- clean - +

+ Each game decides on its own security policy.

-

- This should 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 is required - to be non-interactive. -

+

+ Games which require protected, privileged access to + high-score files, savegames, etc., may be made + set-group-id (mode 2755) and owned by + root.games, and use files and directories with + appropriate permissions (770 root.games, for + example). They must not be made + set-user-id, as this causes security problems. (If + an attacker can subvert any set-user-id game they can + overwrite the executable of any other, causing other players + of these games to run a Trojan horse program. With a + set-group-id game the attacker only gets access to less + important game data, and if they can get at the other + players' accounts at all it will take considerably more + effort.)

-

- If a build file is touched at the end - of the build target, as suggested - above, it must be removed as the first thing that - clean does, so that running - build again after an interrupted - clean doesn't think that everything is - already done. -

+

+ Some packages, for example some fortune cookie programs, are + configured by the upstream authors to install with their + data files or other static information made unreadable so + that they can only be accessed through set-id programs + provided. You should not do this in a Debian package: anyone can + download the .deb file and read the data from it, + so there is no point making the files unreadable. Not + making the files unreadable also means that you don't have + to make so many programs set-id, which reduces the risk of a + security hole.

-

- The clean target must be invoked as - root if binary has been invoked since - the last clean, or if - build has been invoked as root (since - build may create directories, for - example). -

- +

+ As described in the FHS, binaries of games should be + installed in the directory /usr/games. This also + applies to games that use the X Window System. Manual pages + for games (X and non-X games) should be installed in + /usr/share/man/man6.

+ + - get-orig-source (optional) - -

- This target fetches the most recent version of the - original source package from a canonical archive - site (via FTP or WWW, for example), does any - necessary rearrangement to turn it into the original - source tarfile format described below, and leaves it - in the current directory. -

+ + Documentation -

- This target may be invoked in any directory, and - should take care to clean up any temporary files it - may have left. -

+ + Manual pages -

- This target is optional, but providing it if - possible is a good idea. -

- - +

+ You should install manual pages in nroff source + form, in appropriate places under /usr/share/man. + You should only use sections 1 to 9 (see the FHS for more + details). You must not install a preformatted "cat page". +

-

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

+

+ Each program, utility, and function should have an + associated manual page included in the same package. It is + suggested that all configuration files also have a manual + page included as well. Manual pages for protocols and other + auxiliary things are optional. +

+

+ If no manual page is available, this is considered as a bug + and should be reported to the Debian Bug Tracking System (the + maintainer of the package is allowed to write this bug report + themselves, if they so desire). Do not close the bug report + until a proper man page is available. + It is not very hard to write a man page. See the + , + , the examples + created by debmake or dh_make, + the helper programs help2man, or the + directory /usr/share/doc/man-db/examples. + +

-

- Additional targets may exist in debian/rules, - either as published or undocumented interfaces or for the - package's internal use. -

+

+ You may forward a complaint about a missing man page to the + 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 man page to be 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. +

-

- The architecture we build on and build for is determined by make - variables via dpkg-architecture (see ). 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: - - -

DEB_*_ARCH (the Debian architecture)

- - -

DEB_*_GNU_TYPE (the GNU style architecture - specification string)

- - -

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

- - -

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

- -

+

+ Manual pages should be installed compressed using gzip -9. +

-

- where * is either BUILD for specification of - the build machine or HOST for specification of the machine - we build for. -

+

+ If one man page needs to be accessible via several names it + 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 links in the manual page directories, nor put + absolute filenames in .so directives. The filename + in a .so in a man page should be relative to the + base of the man page tree (usually + /usr/share/man). If you do not create any links + (whether symlinks, hard links, or .so directives) + in the filesystem to the alternate names of the man page, + then you should not rely on man finding your + man page under those names based solely on the information in + the man page's header. + Supporting this in man often requires + unreasonable processing time to find a manual page or to + report that none exists, and moves knowledge into man's + database that would be better left in the filesystem. + This support is therefore deprecated and will cease to + be present in the future. + +

+ -

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

+ + Info documents -

- It is important to understand that the DEB_*_ARCH - string does only determine which Debian architecture we - build on resp. for. It should not be used to get the CPU - or System information, the GNU style variables should be - used for that. -

- +

+ Info documents should be installed in /usr/share/info. + They should be compressed with gzip -9. +

+

+ Your package should call install-info to update + the Info dir file in its postinst + script when called with a configure argument, for + example: + +install-info --quiet --section Development Development \ + /usr/share/info/foobar.info +

- debian/control - +

+ It is a good idea to specify a section for the location of + your program; this is done with the --section + switch. To determine which section to use, you should look + at /usr/share/info/dir on your system and choose the most + relevant (or create a new section if none of the current + sections are relevant). Note that the --section + flag takes two arguments; the first is a regular expression + to match (case-insensitively) against an existing section, + the second is used when creating a new one.

-

- This file contains version-independent details about the - source package and about the binary packages it creates. -

+

+ You should remove the entries in the prerm + script when called with a remove argument: + +install-info --quiet --remove /usr/share/info/foobar.info +

-

- It is a series of sets of control fields, each - syntactically similar to a binary package control file. - The sets are separated by one or more blank lines. The - first set is information about the source package in - general; each subsequent set describes one binary package - that the source tree builds. -

+

+ If install-info cannot find a description entry + in the Info file you must supply one. See for details.

+ -

- The syntax and semantics of the fields are described below - in . -

+ + Additional documentation -

- The general (binary-package-independent) fields are: - - -

Source (mandatory)

- - -

Maintainer

- - -

- Section and - Priority - (classification, mandatory) -

- - -

- Build-Depends et - al. (source package interrelationships) -

- - -

- Standards-Version -

- - +

+ Any additional documentation that comes with the package may + be installed at the discretion of the package maintainer. + Text documentation should be installed in the directory + /usr/share/doc/package, where + package is the name of the package, and + compressed with gzip -9 unless it is small. +

-

- The per-binary-package fields are: - - -

Package (mandatory)

- - -

- Architecture - (mandatory)

- - -

Description

- - -

- Section and - Priority (classification)

- - -

Essential

- - -

- Depends et - al. (binary package interrelationships) -

- - +

+ If a package comes with large amounts of documentation which + many users of the package will not require you should create + a separate binary package to contain it, so that it does not + take up disk space on the machines of users who do not need + or want it installed.

-

- These fields are used by dpkg-gencontrol to - generate control files for binary packages (see below), by - dpkg-genchanges to generate the - .changes file to accompany the upload, and by - dpkg-source when it creates the .dsc - source control file as part of a source archive. -

+

+ It is often a good idea to put text information files + (READMEs, changelogs, and so forth) that come with + the source package in /usr/share/doc/package + in the binary package. However, you don't need to install + the instructions for building and installing the package, of + course!

-

- The fields here may contain variable references - their - values will be substituted by - dpkg-gencontrol, dpkg-genchanges - or dpkg-source when they generate output - control files. See for details. -

+

+ Packages must not require the existence of any files in + /usr/share/doc/ in order to function + + The system administrator should be able to + delete files in /usr/share/doc/ without causing + any programs to break. + . + Any files that are referenced by programs but are also + useful as standalone documentation should be installed under + /usr/share/package/ with symbolic links from + /usr/share/doc/package. +

-

User-defined fields - +

+ /usr/share/doc/package may be a symbolic + link to another directory in /usr/share/doc only if + the two packages both come from the same source and the + first package Depends on the second. +

-

- Additional user-defined fields may be added to the - source package control file. Such fields will be - ignored, and not copied to (for example) binary or - source package control files or upload control files. -

+

+ Former Debian releases placed all additional documentation + in /usr/doc/package. This has been + changed to /usr/share/doc/package, + and packages must not put documentation in the directory + /usr/doc/package. + At this phase of the transition, we no longer require a + symbolic link in /usr/doc/. At a later point, + policy shall change to make the symbolic links a bug. + +

+ -

- If you wish to add additional unsupported fields to - these output files you should use the mechanism - described here. -

+ + Preferred documentation formats -

- Fields in the main source control information file with - names starting X, followed by one or more of - the letters BCS and a hyphen -, will - be copied to the output files. Only the part of the - field name after the hyphen will be used in the output - file. Where the letter B is used the field - will appear in binary package control files, where the - letter S is used in source package control - files and where C is used in upload control - (.changes) files. -

+

+ The unification of Debian documentation is being carried out + via HTML.

-

- For example, if the main source information control file - contains the field - - XBS-Comment: I stand between the candle and the star. - - then the binary and source package control files will contain the - field - - Comment: I stand between the candle and the star. - -

- +

+ If your package comes with extensive documentation in a + markup format that can be converted to various other formats + you should if possible ship HTML versions in a binary + package, in the directory + /usr/share/doc/appropriate-package or + its subdirectories. + The rationale: The important thing here is that HTML + docs should be available in some package, not + necessarily in the main binary package. + +

- +

+ Other formats such as PostScript may be provided at the + package maintainer's discretion. +

+ - debian/changelog - + + Copyright information -

- This file records the changes to the Debian-specific parts of the - package - -

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

- . -

+

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

-

- It has a special format which allows the package building - tools to discover which version of the package is being - built and find out other release-specific information. -

+

+ In addition, the copyright file must say where the upstream + sources (if any) were obtained. It should name the original + authors of the package and the Debian maintainer(s) who were + involved with its creation.

-

- That format is a series of entries like this: - - package (version) distribution(s); urgency=urgency +

+ A copy of the file which will be installed in + /usr/share/doc/package/copyright should + be in debian/copyright in the source package. +

- * change details - more change details - * even more change details +

+ /usr/share/doc/package may be a symbolic + link to another directory in /usr/share/doc only if + the two packages both come from the same source and the + first package Depends on the second. These rules are + important because copyrights must be extractable by + mechanical means. +

- -- maintainer name and email address date - -

+

+ Packages distributed under the UCB BSD license, the Artistic + license, the GNU GPL, and the GNU LGPL should refer to the + files /usr/share/common-licenses/BSD, + /usr/share/common-licenses/Artistic, + /usr/share/common-licenses/GPL, and + /usr/share/common-licenses/LGPL respectively, + rather than quoting them in the copyright file. +

-

- package and version are the source - package name and version number. -

+

+ You should not use the copyright file as a general README + file. If your package has such a file it should be + installed in /usr/share/doc/package/README or + README.Debian or some other appropriate place.

+ -

- distribution(s) lists the distributions where - this version should be installed when it is uploaded - it - is copied to the Distribution field in the - .changes file. See . -

+ + Examples -

- urgency is the value for the Urgency - field in the .changes file for the upload. See - . It is not possible to specify an - urgency containing commas; commas are used to separate - keyword=value settings in - the dpkg changelog format (though there is - currently only one useful keyword, - urgency). -

+

+ 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 + for the benefit of the system administrator and users as + documentation only. Architecture-specific example files + should be installed in a directory + /usr/lib/package/examples with symbolic + links to them from + /usr/share/doc/package/examples, or the + latter directory itself may be a symbolic link to the + former. +

-

- The change details may in fact be any series of lines - starting with at least two spaces, but conventionally each - change starts with an asterisk and a separating space and - continuation lines are indented so as to bring them in - line with the start of the text above. Blank lines may be - used here to separate groups of changes, if desired. -

+

+ If the purpose of a package is to provide examples, then the + example files may be installed into + /usr/share/doc/package. +

+ -

- The maintainer name and email address should 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. -

+ + Changelog files -

- The date should be in RFC822 format - -

- This is generated by the 822-date - program. -

- ; it should include the timezone specified - numerically, with the timezone name or abbreviation - optionally present as a comment. -

+

+ Packages that are not Debian-native must contain a + compressed copy of the debian/changelog file from + the Debian source tree in + /usr/share/doc/package with the name + changelog.Debian.gz. +

-

- The first `title' line with the package name should start - at the left hand margin; the `trailer' line with the - maintainer and date details should be preceded by exactly - one space. The maintainer details and the date must be - separated by exactly two spaces. -

+

+ If an upstream changelog is available, it should be accessible as + /usr/share/doc/package/changelog.gz in + plain text. If the upstream changelog is distributed in + HTML, it should be made available in that form as + /usr/share/doc/package/changelog.html.gz + and a plain text changelog.gz should be generated + from it using, for example, lynx -dump -nolist. If + the upstream changelog files do not already conform to this + naming convention, then this may be achieved either by + renaming the files, or by adding a symbolic link, at the + maintainer's discretion. + Rationale: People should not have to look in places for + upstream changelogs merely because they are given + different names or are distributed in HTML format. + +

-

- An Emacs mode for editing this format is available: it is - called debian-changelog-mode. You can have this - mode selected automatically when you edit a Debian - changelog by adding a local variables clause to the end of - the changelog. -

+

+ All of these files should be installed compressed using + gzip -9, as they will become large with time even + if they start out small. +

- Defining alternative changelog formats - +

+ If the package has only one changelog which is used both as + the Debian changelog and the upstream one because there is + no separate upstream maintainer then that changelog should + usually be installed as + /usr/share/doc/package/changelog.gz; if + there is a separate upstream maintainer, but no upstream + changelog, then the Debian changelog should still be called + changelog.Debian.gz. +

-

- It is possible to use a different format to the standard - one, by providing a parser for the format you wish to - use. -

+

+ For details about the format and contents of the Debian + changelog file, please see . +

+ + -

- In order to have dpkg-parsechangelog run your - parser, you must include a line within the last 40 lines - of your file matching the Perl regular expression: - \schangelog-format:\s+([0-9a-z]+)\W The part in - parentheses should be the name of the format. For - example, you might say: - - @@@ changelog-format: joebloggs @@@ - - Changelog format names are non-empty strings of alphanumerics. -

+ + Introduction and scope of these appendices -

- If such a line exists then dpkg-parsechangelog - will look for the parser as - /usr/lib/dpkg/parsechangelog/format-name - or - /usr/local/lib/dpkg/parsechangelog/format-name; - it is an error for it not to find it, or for it not to - be an executable program. The default changelog format - is dpkg, and a parser for it is provided with - the dpkg package. -

+

+ These appendices are taken essentially verbatim from the + now-deprecated Packaging Manual, version 3.2.1.0. They are + the chapters which are likely to be of use to package + maintainers and which have not already been included in the + policy document itself. Most of these sections are very likely + not relevant to policy; they should be treated as + documentation for the packaging system. Please note that these + appendices are included for convenience, and for historical + reasons: they used to be part of policy package, and they have + not yet been incorporated into dpkg documentation. However, + they still have value, and hence they are presented here. +

-

- The parser will be invoked with the changelog open on - standard input at the start of the file. It should read - the file (it may seek if it wishes) to determine the - information required and return the parsed information - to standard output in the form of a series of control - fields in the standard format. By default it should - return information about only the most recent version in - the changelog; it should accept a - -vversion option to return changes - information from all versions present strictly - after version, and it should then be an - error for version not to be present in the - changelog. -

+

+ They have not yet been checked to ensure that they are + compatible with the contents of policy, and if there are any + contradictions, the version in the main policy document takes + precedence. The remaining chapters of the old Packaging + Manual have also not been read in detail to ensure that there + are not parts which have been left out. Both of these will be + done in due course. +

-

- The fields are: - - -

Source

- - -

Version (mandatory)

- - -

- Distribution - (mandatory) -

- - -

Urgency (mandatory)

- - -

- Maintainer - (mandatory) -

- - -

Date

- - -

- Changes - (mandatory) -

- - +

+ Certain parts of the Packaging manual were integrated into the + Policy Manual proper, and removed from the appendices. Links + have been placed from the old locations to the new ones. +

-

- If several versions are being returned (due to the use - of -v), the urgency value should be of the - highest urgency code listed at the start of any of the - versions requested followed by the concatenated - (space-separated) comments from all the versions - requested; the maintainer, version, distribution and - date should always be from the most recent version. -

+

+ dpkg is a suite of programs for creating binary + package files and installing and removing them on Unix + systems. + dpkg is targetted primarily at Debian + GNU/Linux, but may work on or be ported to other + systems. + +

-

- For the format of the Changes field see . -

+

+ The binary packages are designed for the management of + installed executable programs (usually compiled binaries) and + their associated data, though source code examples and + documentation are provided as part of some packages.

-

- If the changelog format which is being parsed always or - almost always leaves a blank line between individual - change notes these blank lines should be stripped out, - so as to make the resulting output compact. -

+

+ This manual describes the technical aspects of creating Debian + binary packages (.deb files). It documents the + behaviour of the package management programs + dpkg, dselect et al. and the way + they interact with packages.

-

- If the changelog format does not contain date or package - name information this information should be omitted from - the output. The parser should not attempt to synthesise - it or find it from other sources. -

+

+ It also documents the interaction between + dselect's core and the access method scripts it + uses to actually install the selected packages, and describes + how to create a new access method.

-

- If the changelog does not have the expected format the - parser should exit with a nonzero exit status, rather - than trying to muddle through and possibly generating - incorrect output. -

+

+ This manual does not go into detail about the options and + usage of the package building and installation tools. It + should therefore be read in conjuction with those programs' + man pages. +

-

- A changelog parser may not interact with the user at - all.

- +

+ The utility programs which are provided with dpkg + for managing various system configuration and similar issues, + such as update-rc.d and + install-info, are not described in detail here - + please see their man pages. +

- debian/substvars - and variable substitutions - +

+ It is assumed that the reader is reasonably familiar with the + dpkg System Administrators' manual. + Unfortunately this manual does not yet exist. +

-

- When dpkg-gencontrol, - dpkg-genchanges and dpkg-source - generate control files they do 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/rules using the -V option to the - source packaging commands, and certain predefined - variables are available. -

+

+ The Debian version of the FSF's GNU hello program is provided + as an example for people wishing to create Debian + packages. The Debian debmake package is + recommended as a very helpful tool in creating and maintaining + Debian packages. However, while the tools and examples are + helpful, they do not replace the need to read and follow the + Policy and Programmer's Manual.

+ -

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

+ + Binary packages (from old Packaging Manual) -

- See for full - details about source variable substitutions, including the - format of debian/substvars.

- +

+ The binary package has two main sections. The first part + consists of various control information files and scripts used + by dpkg when installing and removing. See . +

- debian/files - +

+ The second part is an archive containing the files and + directories to be installed. +

-

- This file is not a permanent part of the source tree; it - is used while building packages to record which files are - being generated. dpkg-genchanges uses it - when it generates a .changes file. -

+

+ In the future binary packages may also contain other + components, such as checksums and digital signatures. The + format for the archive is described in full in the + deb(5) man page. +

-

- It should not exist in a shipped source package, and so it - (and any backup files or temporary files such as - files.new - -

- files.new is used as a temporary file by - dpkg-gencontrol and - dpkg-distaddfile - they write a new - version of files here before renaming it, - to avoid leaving a corrupted copy if an error - occurs -

- ) should be removed by the - clean target. It may also be wise to - ensure a fresh start by emptying or removing it at the - start of the binary target. -

-

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

+ Creating package files - + dpkg-deb + -

- If a package upload includes files besides the source - package and any binary packages whose control files were - made with dpkg-gencontrol then they should be - placed in the parent of the package's top-level directory - and dpkg-distaddfile should be called to add - the file to the list in debian/files.

- +

+ All manipulation of binary package files is done by + dpkg-deb; it's the only program that has + knowledge of the format. (dpkg-deb may be + invoked by calling dpkg, as dpkg + will spot that the options requested are appropriate to + dpkg-deb and invoke that instead with the same + arguments.) +

- debian/tmp - +

+ In order to create a binary package you must make a + directory tree which contains all the files and directories + you want to have in the filesystem data part of the package. + In Debian-format source packages this directory is usually + debian/tmp, relative to the top of the package's + source tree. +

-

- This is the canonical temporary location for the - construction of binary packages by the binary - target. The directory tmp serves as the root of - the filesystem tree as it is being constructed (for - example, by using the package's upstream makefiles install - targets and redirecting the output there), and it also - contains the DEBIAN subdirectory. See . -

+

+ They should have the locations (relative to the root of the + directory tree you're constructing) ownerships and + permissions which you want them to have on the system when + they are installed. +

-

- If several binary packages are generated from the same - source tree it is usual to use several - debian/tmpsomething directories, for - example tmp-a or tmp-doc. -

+

+ With current versions of dpkg the uid/username + and gid/groupname mappings for the users and groups being + used should be the same on the system where the package is + built and the one where it is installed. +

-

- Whatever tmp directories are created and used by - binary must of course be removed by the - clean target.

 - +

+ You need to add one special directory to the root of the + miniature filesystem tree you're creating: + DEBIAN. It should contain the control + information files, notably the binary package control file + (see ). +

+

+ The DEBIAN directory will not appear in the + filesystem archive of the package, and so won't be installed + by dpkg when the package is installed. +

- Source packages as archives - +

+ When you've prepared the package, you should invoke: + + dpkg --build directory + +

- As it exists on the FTP site, a Debian source package - consists of three related files. You must have the right - versions of all three to be able to use them. + This will build the package in + directory.deb. (dpkg knows + that --build is a dpkg-deb option, so + it invokes dpkg-deb with the same arguments to + build the package.)

- - Debian source control file - .dsc - + See the man page for details of how + to examine the contents of this newly-created file. You may find the + output of following commands enlightening: + + dpkg-deb --info filename.deb + dpkg-deb --contents filename.deb + dpkg --contents filename.deb + + To view the copyright file for a package you could use this command: + + dpkg --fsys-tarfile filename.deb | tar xO ./usr/share/doc/\*/copyright | pager + +

+ -

- This file contains a series of fields, identified and - separated just like the fields in the control file of - a binary package. The fields are listed below; their - syntax is described above, in . - - -

Source

- - -

Version

- - -

Maintainer

- - -

Binary

- - -

Architecture

- - -

- Build-Depends et - al. (source package interrelationships) -

- - -

- Standards-Version

- - -

Files

- - + + Package control information files + +

+ The control information portion of a binary package is a + collection of files with names known to dpkg. + It will treat the contents of these files specially - some + of them contain information used by dpkg when + installing or removing the package; others are scripts which + the package maintainer wants dpkg to run. +

-

- The source package control file is generated by - dpkg-source when it builds the source - archive, from other files in the source package, - described above. When unpacking it is checked against - the files and directories in the other parts of the - source package, as described below.

- +

+ It is possible to put other files in the package control + area, but this is not generally a good idea (though they + will largely be ignored). +

- - Original source archive - - - package_upstream-version.orig.tar.gz - - +

+ Here is a brief list of the control info files supported by + dpkg and a summary of what they're used for. +

+

+ + control +

+ This is the key description file used by + dpkg. It specifies the package's name + and version, gives its description for the user, + states its relationships with other packages, and so + forth. See and + . +

- This is a compressed (with gzip -9) - tar file containing the source code from - the upstream authors of the program. The tarfile - unpacks into a directory - package-upstream-version.orig, - and does not contain files anywhere other than in - there or in its subdirectories.

+ It is usually generated automatically from information + in the source package by the + dpkg-gencontrol program, and with + assistance from dpkg-shlibdeps. + See . +

- - Debianisation diff - - - package_upstream_version-revision.diff.gz - + postinst, preinst, postrm, + prerm -

- This is a unified context diff (diff -u) - giving the changes which are required to turn the - original source into the Debian source. These changes - may only include editing and creating plain files. - The permissions of files, the targets of symbolic - links and the characteristics of special files or - pipes may not be changed and no files may be removed - or renamed. + These are exectuable files (usually scripts) which + dpkg runs during installation, upgrade + and removal of packages. They allow the package to + deal with matters which are particular to that package + or require more complicated processing than that + provided by dpkg. Details of when and + how they are called are in .

- All the directories in the diff must exist, except the - debian subdirectory of the top of the source - tree, which will be created by - dpkg-source if necessary when unpacking. + It is very important to make these scripts idempotent. + See .

- The dpkg-source program will - automatically make the debian/rules file - executable (see below).

 + The maintainer scripts are guaranteed to run with a + controlling terminal and can interact with the user. + See . +

+ + + conffiles + + + This file contains a list of configuration files which + are to be handled automatically by dpkg + (see ). Note that not necessarily + every configuration file should be listed here. + + + shlibs + + + This file contains a list of the shared libraries + supplied by the package, with dependency details for + each. This is used by dpkg-shlibdeps + when it determines what dependencies are required in a + package control file. The shlibs file format + is described on . + +

+ + The main control information file: control

- If there is no original source code - for example, if the - package is specially prepared for Debian or the Debian - maintainer is the same as the upstream maintainer - the - format is slightly different: then there is no diff, and the - tarfile is named - package_version.tar.gz and - contains a directory - package-version. + The most important control information file used by + dpkg when it installs a package is + control. It contains all the package's "vital + statistics". +

+ +

+ The binary package control files of packages built from + Debian sources are made by a special tool, + dpkg-gencontrol, which reads + debian/control and debian/changelog to + find the information it needs. See for + more details. +

+ +

+ The fields in binary package control files are listed in + . +

+ +

+ A description of the syntax of control files and the purpose + of the fields is available in .

- Unpacking a Debian source package without - dpkg-source - + + Time Stamps

- dpkg-source -x is the recommended way to unpack a - Debian source package. However, if it is not available it - is possible to unpack a Debian source archive as follows: - - -

- Untar the tarfile, which will create a .orig - directory.

- - -

Rename the .orig directory to - package-version.

- - -

- Create the subdirectory debian at the top of - the source tree.

- -

Apply the diff using patch -p0.

- -

Untar the tarfile again if you want a copy of the original - source code alongside the Debianised version.

- - + See . +

+ + + + + Source packages (from old Packaging Manual) + +

+ The Debian binary packages in the distribution are generated + from Debian sources, which are in a special format to assist + the easy and automatic building of binaries. +

+ + + Tools for processing source packages

- It is not possible to generate a valid Debian source archive - without using dpkg-source. In particular, - attempting to use diff directly to generate the - .diff.gz file will not work. + Various tools are provided for manipulating source packages; + they pack and unpack sources and help build of binary + packages and help manage the distribution of new versions. +

+ +

+ They are introduced and typical uses described here; see + for full + documentation about their arguments and operation. +

+ +

+ For examples of how to construct a Debian source package, + and how to use those utilities that are used by Debian + source packages, please see the hello example + package.

- Restrictions on objects in source packages + + + dpkg-source - packs and unpacks Debian source + packages

- The source package may not contain any hard links - -

- This is not currently detected when building source - packages, but only when extracting - them. -

- - -

- Hard links may be permitted at some point in the - future, but would require a fair amount of - work. -

- , device special files, sockets or setuid or - setgid files. - -

- Setgid directories are allowed. -

- + This program is frequently used by hand, and is also + called from package-independent automated building scripts + such as dpkg-buildpackage.

- The source packaging tools manage the changes between the - original and Debianised source using diff and - patch. Turning the original source tree as - included in the .orig.tar.gz into the debianised - source must not involve any changes which cannot be - handled by these tools. Problematic changes which cause - dpkg-source to halt with an error when - building the source package are: - -

Adding or removing symbolic links, sockets or pipes.

- -

Changing the targets of symbolic links.

+ To unpack a package it is typically invoked with + + dpkg-source -x .../path/to/filename.dsc + +

+ +

+ with the filename.tar.gz and + filename.diff.gz (if applicable) in + the same directory. It unpacks into + package-version, and if + applicable + package-version.orig, in + the current directory. +

+ +

+ To create a packed source archive it is typically invoked: + + dpkg-source -b package-version + +

+ +

+ This will create the .dsc, .tar.gz and + .diff.gz (if appropriate) in the current + directory. dpkg-source does not clean the + source tree first - this must be done separately if it is + required. +

+ +

+ See also .

+ + + + + + dpkg-buildpackage - overall package-building + control script + + +

+ dpkg-buildpackage is a script which invokes + dpkg-source, the debian/rules + targets clean, build and + binary, dpkg-genchanges and + gpg (or pgp) to build a signed + source and binary package upload. +

+ +

+ It is usually invoked by hand from the top level of the + built or unbuilt source directory. It may be invoked with + no arguments; useful arguments include: + + -uc, -us + +

+ Do not sign the .changes file or the + source package .dsc file, respectively.

-

Creating directories, other than debian.

+ -psign-command + +

+ Invoke sign-command instead of finding + gpg or pgp on the PATH. + sign-command must behave just like + gpg or pgp.

 -

Changes to the contents of binary files.

 - Changes which cause dpkg-source to - print a warning but continue anyway are: - + -rroot-command

- Removing files, directories or symlinks. - -

- Renaming a file is not treated specially - it is - seen as the removal of the old file (which - generates a warning, but is otherwise ignored), - and the creation of the new - one.

- -

+ When root privilege is required, invoke the command + root-command. root-command + should invoke its first argument as a command, from + the PATH if necessary, and pass its + second and subsequent arguments to the command it + calls. If no root-command is supplied + then dpkg-buildpackage will take no + special action to gain root privilege, so that for + most packages it will have to be invoked as root to + start with.

 + -b, -B

- Changed text files which are missing the usual final - newline (either in the original or the modified - source tree). + Two types of binary-only build and upload - see + .

- - Changes which are not represented, but which are not detected by - dpkg-source, are: - -

Changing the permissions of files (other than - debian/rules) and directories.

 - -

- -

- The debian directory and debian/rules - are handled specially by dpkg-source - before - applying the changes it will create the debian - directory, and afterwards it will make - debian/rules world-exectuable. +

- - - - Control files and their - fields (from old Packaging Manual) - - -

- Many of the tools in the dpkg 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 - format. -

- - Syntax of control files - - -

- A file consists of one or more paragraphs of fields. The - paragraphs are separated by blank lines. Some control files - only allow one paragraph; others allow several, in which - case each paragraph often refers to a different package. -

- -

- Each paragraph is a series of fields and values; each field - consists of a name, followed by a colon and the value. It - ends at the end of the line. Horizontal whitespace (spaces - and tabs) may occur before or after the value and is ignored - there; it is conventional to put a single space after the - colon. -

- -

- Some fields' values may span several lines; in this case - each continuation line must start with a space or - tab. Any trailing spaces or tabs at the end of individual - lines of a field value are ignored. -

- -

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

- -

- Field names are not case-sensitive, but it is usual to - capitalise the field names using mixed case as shown below. -

- -

- Blank lines, or lines consisting only of spaces and tabs, - are not allowed within field values or between fields - that - would mean a new paragraph. -

-

- 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 conjuction with the details - below and the list of fields for the particular file.

- + + + dpkg-gencontrol - generates binary package + control files + - List of fields - +

+ This program is usually called from debian/rules + (see ) in the top level of the source + tree. +

- Package - +

+ This is usually done just before the files and directories in the + temporary directory tree where the package is being built have their + permissions and ownerships set and the package is constructed using + dpkg-deb/ + + This is so that the control file which is produced has + the right permissions + . +

- The name of the binary package. Package names consist of - the alphanumerics and + - . - (plus, minus and full stop). - -

- The characters @ : = - % _ (at, colon, equals, percent - and underscore) used to be legal and are still - accepted when found in a package file, but may not be - used in new packages -

- + dpkg-gencontrol must be called after all the + files which are to go into the package have been placed in + the temporary build directory, so that its calculation of + the installed size of a package is correct.

- They must be at least two characters and must start with - an alphanumeric. In current versions of dpkg they are - sort of case-sensitive

This is a - bug.

; use lowercase package names unless - the package you're building (or referring to, in other - fields) is already using uppercase.

- + It is also necessary for dpkg-gencontrol to + be run after dpkg-shlibdeps so that the + variable substitutions created by + dpkg-shlibdeps in debian/substvars + are available. +

- Version - +

+ For a package which generates only one binary package, and + which builds it in debian/tmp relative to the top + of the source package, it is usually sufficient to call + dpkg-gencontrol. +

- This lists the source or binary package's version number - - see . + Sources which build several binaries will typically need + something like: + + dpkg-gencontrol -Pdebian/tmp-pkg -ppackage + The -P tells + dpkg-gencontrol that the package is being + built in a non-default directory, and the -p + tells it which package's control file should be generated.

+

+ dpkg-gencontrol also adds information to the + list of files in debian/files, for the benefit of + (for example) a future invocation of + dpkg-genchanges.

 - Architecture + + + dpkg-shlibdeps - calculates shared library + dependencies

- This is the architecture string; it is a single word for - the Debian architecture. + This program is usually called from debian/rules + just before dpkg-gencontrol (see ), in the top level of the source tree.

- dpkg will check the declared architecture of - a binary package against its own compiled-in value before - it installs it. + Its arguments are executables. + +

+ In a forthcoming dpkg version, + dpkg-shlibdeps would be required to be + called on shared libraries as well. +

+

+ They may be specified either in the locations in the + source tree where they are created or in the locations + in the temporary build tree where they are installed + prior to binary package creation. +

+ for which shared library dependencies should + be included in the binary package's control file.

- The special value all indicates that the package - is architecture-independent. + If some of the found shared libraries should only + warrant a Recommends or Suggests, or if + some warrant a Pre-Depends, this can be achieved + by using the -ddependency-field option + before those executable(s). (Each -d option + takes effect until the next -d.)

- In the main debian/control file in the source - package, or in the source package control file - .dsc, a list of architectures (separated by - spaces) is also allowed, as is the special value - any. A list indicates that the source will build - an architecture-dependent package, and will only work - correctly on the listed architectures. any - indicates that though the source package isn't dependent - on any particular architecture and should compile fine on - any one, the binary package(s) produced are not - architecture-independent but will instead be specific to - whatever the current build architecture is. + dpkg-shlibdeps does not directly cause the + output control file to be modified. Instead by default it + adds to the debian/substvars file variable + settings like shlibs:Depends. These variable + settings must be referenced in dependency fields in the + appropriate per-binary-package sections of the source + control file.

- In a .changes file the Architecture - field lists the architecture(s) of the package(s) - currently being uploaded. This will be a list; if the - source for the package is being uploaded too the special - entry source is also present. + For example, a package that generates an essential part + which requires dependencies, and optional parts that + which only require a recommendation, would separate those + two sets of dependencies into two different fields. + At the time of writing, an example for this was the + + It can say in its debian/rules: + + dpkg-shlibdeps -dDepends program anotherprogram ... \ + -dRecommends optionalpart anotheroptionalpart + + and then in its main control file debian/control: + + ... + Depends: ${shlibs:Pre-Depends} + Recommends: ${shlibs:Recommends} + ... +

- See for information how to get the - architecture for the build process. + Sources which produce several binary packages with + different shared library dependency requirements can use + the -pvarnameprefix option to override + the default shlibs: prefix (one invocation of + dpkg-shlibdeps per setting of this option). + They can thus produce several sets of dependency + variables, each of the form + varnameprefix:dependencyfield, + which can be referred to in the appropriate parts of the + binary package control files.

- Maintainer + + + + dpkg-distaddfile - adds a file to + debian/files

- The package maintainer's name and email address. The name - should come first, then the email address inside angle - brackets <> (in RFC822 format). + Some packages' uploads need to include files other than + the source and binary package files.

- If the maintainer's name contains a full stop then the - whole field will not work directly as an email address due - to a misfeature in the syntax specified in RFC822; a - program using this field as an address must check for this - and correct the problem if necessary (for example by - putting the name in round brackets and moving it to the - end, and bringing the email address forward). + dpkg-distaddfile adds a file to the + debian/files file so that it will be included in + the .changes file when + dpkg-genchanges is run.

- In a .changes file or parsed changelog data this - contains the name and email address of the person - responsible for the particular version in question - this - may not be the package's usual maintainer. + It is usually invoked from the binary target of + debian/rules: + + dpkg-distaddfile filename section priority + + The filename is relative to the directory where + dpkg-genchanges will expect to find it - this + is usually the directory above the top level of the source + tree. The debian/rules target should put the + file there just before or just after calling + dpkg-distaddfile.

- This field is usually optional in as far as the - dpkg are concerned, but its absence when - building packages usually generates a warning.

+ The section and priority are passed + unchanged into the resulting .changes file. +

- Source - -

- This field identifies the source package name. -

+ + + dpkg-genchanges - generates a .changes + upload control file +

- In a main source control information or a - .changes or .dsc file or parsed - changelog data this may contain only the name of the - source package. + This program is usually called by package-independent + automatic building scripts such as + dpkg-buildpackage, but it may also be called + by hand.

- In the control file of a binary package (or in a - Packages file) it may be followed by a version - number in parentheses. - -

- It is usual to leave a space after the package name if - a version number is specified. -

- This version number may be omitted (and is, by - dpkg-gencontrol) if it has the same value as - the Version field of the binary package in - question. The field itself may be omitted from a binary - package control file when the source package has the same - name and version as the binary package. + It is usually called in the top level of a built source + tree, and when invoked with no arguments will print out a + straightforward .changes file based on the + information in the source package's changelog and control + file and the binary and source packages which should have + been built.

- Package interrelationship fields: - Depends, Pre-Depends, - Recommends Suggests, Conflicts, - Provides, Replaces + + + + dpkg-parsechangelog - produces parsed + representation of a changelog

- These fields describe the package's relationships with - other packages. Their syntax and semantics are described - in .

+ This program is used internally by + dpkg-source et al. It may also occasionally + be useful in debian/rules and elsewhere. It + parses a changelog, debian/changelog by default, + and prints a control-file format representation of the + information in it to standard output. +

- Description - + + + dpkg-architecture - information about the build and + host system + -

- In a binary package Packages file or main source - control file this field contains a description of the - binary package, in a special format. See for details. -

+

+ This program can be used manually, but is also invoked by + dpkg-buildpackage or debian/rules to set + to set environment or make variables which specify the build and + host architecture for the package building process. +

+ + -

- In a .changes file it contains a summary of the - descriptions for the packages being uploaded. The part of - the field before the first newline is empty; thereafter - each line has the name of a binary package and the summary - description line from that binary package. Each line is - indented by one space.

- + + The Debianised source tree - Essential - +

+ The source archive scheme described later is intended to + allow a Debianised source tree with some associated control + information to be reproduced and transported easily. The + Debianised source tree is a version of the original program + with certain files added for the benefit of the + Debianisation process, and with any other changes required + made to the rest of the source code and installation + scripts. +

-

- This is a boolean field which may occur only in the - control file of a binary package (or in the - Packages file) or in a per-package fields - paragraph of a main source control data file. -

+

+ The extra files created for Debian are in the subdirectory + debian of the top level of the Debianised source + tree. They are described below. +

+ + + debian/rules - the main building script

- If set to yes then dpkg and - dselect will refuse to remove the package - (though it can be upgraded and/or replaced). The other - possible value is no, which is the same as not - having the field at all.

+ See . +

- Section and - Priority - -

- These two fields classify the package. The - Priority represents how important that it is that - the user have it installed; the Section - represents an application area into which the package has - been classified. -

+ + debian/changelog

- When they appear in the debian/control file these - fields give values for the section and priority subfields - of the Files field of the .changes file, - and give defaults for the section and priority of the - binary packages. + See .

- The section and priority are represented, though not as - separate fields, in the information for each file in the - -Filefield of a - .changes file. The section value in a - .changes file is used to decide where to install - a package in the FTP archive. + It is recommended that the entire changelog be encoded in the + + encoding of + . +

+ Support for Unicode, and specifically UTF-8, is + steadily increasing among popular applications in + Debian. For example, in unstable, GNOME 2 has + excellent support (almost level 2) in almost all its + applications; the big remaining one is gnome-terminal, + of which one requires development versions in order to + support UTF-8 (available in Debian experimental now if + you want to play). I think that by the time sarge is + released, UTF-8 support will start to hit critical + mass.

+

+ I think it is fairly obvious that we need to + eventually transition to UTF-8 for our package + infrastructure; it is really the only sane charset in + an international environment. Now, we can't switch to + using UTF-8 for package control fields and the like + until dpkg has better support, but one thing we can + start doing today is requesting that Debian changelogs + are UTF-8 encoded. At some point in time, we can start + requiring them to do so. +

+

+ Checking for non-UTF8 characters in a changelog is + trivial. Dump the file through + iconv -f utf-8 -t ucs-4 + discard the output, and check the return + value. If there are any characters in the stream + which are invalid UTF-8 sequences, iconv will exit + with an error code; and this will be the case for the + vast majority of other character sets. +

+

-

- These fields are not used by by dpkg proper, - but by dselect when it sorts packages and - selects defaults. See the Debian policy manual for the - priorities in use and the criteria for selecting the - priority for a Debian package, and look at the Debian FTP - archive for a list of currently in-use priorities. -

+ Defining alternative changelog formats + -

- These fields may appear in binary package control files, - in which case they provide a default value in case the - Packages files are missing the information. - dpkg and dselect will only use - the value from a .deb file if they have no other - information; a value listed in a Packages file - will always take precedence. By default - dpkg-gencontrol does not include the section - and priority in the control file of a binary package - use - the -isp, -is or -ip options to - achieve this effect.

- +

+ It is possible to use a different format to the standard + one, by providing a parser for the format you wish to + use. +

- Binary - +

+ In order to have dpkg-parsechangelog run your + parser, you must include a line within the last 40 lines + of your file matching the Perl regular expression: + \schangelog-format:\s+([0-9a-z]+)\W The part in + parentheses should be the name of the format. For + example, you might say: + + @@@ changelog-format: joebloggs @@@ + + Changelog format names are non-empty strings of alphanumerics. +

-

- This field is a list of binary packages. -

+

+ If such a line exists then dpkg-parsechangelog + will look for the parser as + /usr/lib/dpkg/parsechangelog/format-name + or + /usr/local/lib/dpkg/parsechangelog/format-name; + it is an error for it not to find it, or for it not to + be an executable program. The default changelog format + is dpkg, and a parser for it is provided with + the dpkg package. +

-

- When it appears in the .dsc file it is the list - of binary packages which a source package can produce. It - does not necessarily produce all of these binary packages - for every architecture. The source control file doesn't - contain details of which architectures are appropriate for - which of the binary packages. -

+

+ The parser will be invoked with the changelog open on + standard input at the start of the file. It should read + the file (it may seek if it wishes) to determine the + information required and return the parsed information + to standard output in the form of a series of control + fields in the standard format. By default it should + return information about only the most recent version in + the changelog; it should accept a + -vversion option to return changes + information from all versions present strictly + after version, and it should then be an + error for version not to be present in the + changelog. +

-

- When it appears in a .changes file it lists the - names of the binary packages actually being uploaded. -

+

+ The fields are: + + Source + Version (mandatory) + Distribution (mandatory) + Urgency (mandatory) + Maintainer (mandatory) + Date + Changes (mandatory) + +

-

- The syntax is a list of binary packages separated by - commas. - -

- A space after each comma is conventional. -

- Currently the packages must be separated using - only spaces in the .changes file.

- +

+ If several versions are being returned (due to the use + of -v), the urgency value should be of the + highest urgency code listed at the start of any of the + versions requested followed by the concatenated + (space-separated) comments from all the versions + requested; the maintainer, version, distribution and + date should always be from the most recent version. +

- Installed-Size - +

+ For the format of the Changes field see + . +

-

- This field appears in the control files of binary - packages, and in the Packages files. It gives - the total amount of disk space required to install the - named package. -

+

+ If the changelog format which is being parsed always or + almost always leaves a blank line between individual + change notes these blank lines should be stripped out, + so as to make the resulting output compact. +

-

- The disk space is represented in kilobytes as a simple - decimal number.

+

+ If the changelog format does not contain date or package + name information this information should be omitted from + the output. The parser should not attempt to synthesise + it or find it from other sources. +

+ +

+ If the changelog does not have the expected format the + parser should exit with a nonzero exit status, rather + than trying to muddle through and possibly generating + incorrect output. +

+ +

+ A changelog parser may not interact with the user at + all. +

+ - Files - + + debian/substvars and variable substitutions

- This field contains a list of files with information about - each one. The exact information and syntax varies with - the context. In all cases the the part of the field - contents on the same line as the field name is empty. The - remainder of the field is one line per file, each line - being indented by one space and containing a number of - sub-fields separated by spaces. + See .

-

- In the .dsc (Debian source control) file each - line contains the MD5 checksum, size and filename of the - tarfile and (if applicable) diff file which make up the - remainder of the source package. - -

- That is, the parts which are not the - .dsc. -

- The exact forms of the filenames are described - in . -

+ -

- In the .changes file this contains one line per - file being uploaded. Each line contains the MD5 checksum, - size, section and priority and the filename. The section - and priority are the values of the corresponding fields in - the main source control file - see . If no section or priority is - specified then - should be used, though section - and priority values must be specified for new packages to - be installed properly. -

+ + debian/files

- The special value byhand for the section in a - .changes file indicates that the file in question - is not an ordinary package file and must by installed by - hand by the distribution maintainers. If the section is - byhand the priority should be -. + See .

- -

- If a new Debian revision of a package is being shipped and - no new original source archive is being distributed the - .dsc must still contain the Files field - entry for the original source archive - package-upstream-version.orig.tar.gz, - but the .changes file should leave it out. In - this case the original source archive on the distribution - site must match exactly, byte-for-byte, the original - source archive which was used to generate the - .dsc file and diff which are being uploaded.

 - - Standards-Version + debian/tmp

- The most recent version of the standards (the - dpkg programmers' and policy manuals and - associated texts) with which the package complies. This - is updated manually when editing the source package to - conform to newer standards; it can sometimes be used to - tell when a package needs attention. + This is the canonical temporary location for the + construction of binary packages by the binary + target. The directory tmp serves as the root of + the filesystem tree as it is being constructed (for + example, by using the package's upstream makefiles install + targets and redirecting the output there), and it also + contains the DEBIAN subdirectory. See . +

+ +

+ If several binary packages are generated from the same + source tree it is usual to use several + debian/tmpsomething directories, for + example tmp-a or tmp-doc.

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

- + Whatever tmp directories are created and used by + binary must of course be removed by the + clean target.

 + - Distribution - + Source packages as archives + -

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

+

+ As it exists on the FTP site, a Debian source package + consists of three related files. You must have the right + versions of all three to be able to use them. +

-

- Current distribution values are: +

- stable + Debian source control file - .dsc -

- This is the current `released' version of Debian - GNU/Linux. A new version is released approximately - every 3 months after the development code has - been frozen for a month of testing. 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). -

+ This file is a control file used by dpkg-source + to extract a source package. + See . - unstable + + Original source archive - + + package_upstream-version.orig.tar.gz + + +

- This distribution value refers to the - developmental part of the Debian distribution - tree. New packages, new upstream versions of packages - and bug fixes go into the unstable directory - tree. Download from this distribution at your own - risk.

+ This is a compressed (with gzip -9) + tar file containing the source code from + the upstream authors of the program. +

- contrib + + Debianisation diff - + + package_upstream_version-revision.diff.gz + + +

- The packages with this distribution value do not meet - the criteria for inclusion in the main Debian - distribution as defined by the Policy Manual, but meet - the criteria for the contrib - Distribution. There is currently no distinction - between stable and unstable packages in the - contrib or non-free - distributions. Use your best judgement in downloading - from this Distribution.

- + This is a unified context diff (diff -u) + giving the changes which are required to turn the + original source into the Debian source. These changes + may only include editing and creating plain files. + The permissions of files, the targets of symbolic + links and the characteristics of special files or + pipes may not be changed and no files may be removed + or renamed. +

- non-free -

- Like the packages in the contrib seciton, - the packages in non-free do not meet the - criteria for inclusion in the main Debian distribution - as defined by the Policy Manual. Again, use your best - judgement in downloading from this Distribution.

+ All the directories in the diff must exist, except the + debian subdirectory of the top of the source + tree, which will be created by + dpkg-source if necessary when unpacking. +

- experimental -

- The packages with this distribution value are deemed - by their maintainers to be high risk. Oftentimes they - represent early beta or developmental packages from - various sources that the maintainers want people to - try, but are not ready to be a part of the other parts - of the Debian distribution tree. Download at your own - risk.

- + The dpkg-source program will + automatically make the debian/rules file + executable (see below).

 + +

+ +

+ If there is no original source code - for example, if the + package is specially prepared for Debian or the Debian + maintainer is the same as the upstream maintainer - the + format is slightly different: then there is no diff, and the + tarfile is named + package_version.tar.gz, + and preferably contains a directory named + package-version. +

+ + + + Unpacking a Debian source package without dpkg-source - frozen +

+ dpkg-source -x is the recommended way to unpack a + Debian source package. However, if it is not available it + is possible to unpack a Debian source archive as follows: + + +

+ Untar the tarfile, which will create a .orig + directory.

+ + +

Rename the .orig directory to + package-version.

+ -

- From time to time, (currently, every 3 months) the - unstable distribution enters a state of - `code-freeze' in anticipation of release as a - stable version. During this period of testing - (usually 4 weeks) only fixes for existing or - newly-discovered bugs will be allowed. -

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

- +

+ Create the subdirectory debian at the top of + the source tree.

+ +

Apply the diff using patch -p0.

+ +

Untar the tarfile again if you want a copy of the original + source code alongside the Debianised version.

+ + - Urgency - +

+ It is not possible to generate a valid Debian source archive + without using dpkg-source. In particular, + attempting to use diff directly to generate the + .diff.gz file will not work. +

+ + + Restrictions on objects in source packages

- This is a description of how important it is to upgrade to - this version from previous ones. It consists of a single - keyword usually taking one of the values LOW, - MEDIUM or HIGH) followed by an optional - commentary (separated by a space) which is usually in - parentheses. For example: - - Urgency: LOW (HIGH for diversions users) - + The source package may not contain any hard links + + This is not currently detected when building source + packages, but only when extracting + them. + + + Hard links may be permitted at some point in the + future, but would require a fair amount of + work. + , device special files, sockets or setuid or + setgid files. + + Setgid directories are allowed. +

- This field appears in the .changes file and in - parsed changelogs; its value appears as the value of the - urgency attribute in a dpkg-style - changelog (see ). + The source packaging tools manage the changes between the + original and Debianised source using diff and + patch. Turning the original source tree as + included in the .orig.tar.gz into the debianised + source must not involve any changes which cannot be + handled by these tools. Problematic changes which cause + dpkg-source to halt with an error when + building the source package are: + +

Adding or removing symbolic links, sockets or pipes.

+ +

Changing the targets of symbolic links.

+ +

Creating directories, other than debian.

+ +

Changes to the contents of binary files.

 + Changes which cause dpkg-source to + print a warning but continue anyway are: + + +

+ Removing files, directories or symlinks. + + Renaming a file is not treated specially - it is + seen as the removal of the old file (which + generates a warning, but is otherwise ignored), + and the creation of the new one. + +

+ + +

+ Changed text files which are missing the usual final + newline (either in the original or the modified + source tree). +

+ + + Changes which are not represented, but which are not detected by + dpkg-source, are: + +

Changing the permissions of files (other than + debian/rules) and directories.

 +

- Urgency keywords are not case-sensitive.

+ The debian directory and debian/rules + are handled specially by dpkg-source - before + applying the changes it will create the debian + directory, and afterwards it will make + debian/rules world-exectuable. +

+ + - Date - - -

- In .changes files and parsed changelogs, this - gives the date the package was built or last edited.

- + + Control files and their fields (from old Packaging Manual) - Format - +

+ Many of the tools in the dpkg 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 + format. +

-

- This field occurs in .changes files, and - specifies a format revision for the file. The format - described here is version 1.5. The syntax of the - format value is the same as that of a package version - number except that no epoch or Debian revision is allowed - - see .

- + + Syntax of control files - Changes - +

+ See . +

-

- In a .changes file or parsed changelog this field - contains the human-readable changes data, describing the - differences between the last version and the current one. -

+

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

+ -

- There should be nothing in this field before the first - newline; all the subsequent lines must be indented by at - least one space; blank lines must be represented by a line - consiting only of a space and a full stop. -

+ + List of fields -

- Each version's change information should be preceded by a - `title' line giving at least the version, distribution(s) - and urgency, in a human-readable way. -

+

+ See . +

-

- If data from several versions is being returned the entry - for the most recent version should be returned first, and - entries should be separated by the representation of a - blank line (the `title' line may also be followed by the - representation of blank line).

- +

+ This section now contains only the fields that didn't belong + to the Policy manual. +

- Filename and - MSDOS-Filename - + + Filename and MSDOS-Filename

These fields in Packages files give the @@ -10255,11 +9650,12 @@ install-info --quiet --remove /usr/share/info/foobar.info distribution directories, relative to the root of the Debian hierarchy. If the package has been split into several parts the parts are all listed in order, separated - by spaces.

+ by spaces. +

- Size and MD5sum - + + Size and MD5sum

These fields in Packages files give the size (in @@ -10267,11 +9663,12 @@ install-info --quiet --remove /usr/share/info/foobar.info file(s) which make(s) up a binary package in the distribution. If the package is split into several parts the values for the parts are listed in order, separated by - spaces.

+ spaces. +

- Status - + + Status

This field in dpkg's status file records @@ -10279,66 +9676,68 @@ install-info --quiet --remove /usr/share/info/foobar.info left alone, whether it is broken (requiring reinstallation) or not and what its current state on the system is. Each of these pieces of information is a - single word.

+ single word. +

- Config-Version - + + Config-Version

If a package is not installed or not configured, this field in dpkg's status file records the last version of the package which was successfully - configured.

+ configured. +

- Conffiles - + + Conffiles

This field in dpkg's status file contains information about the automatically-managed configuration files held by a package. This field should not - appear anywhere in a package!

+ appear anywhere in a package! +

- Obsolete fields - + + Obsolete fields

These are still recognised by dpkg but should not appear anywhere any more. + Revision Package-Revision Package_Revision -

The Debian revision part of the package version was at one point in a separate control file field. This - field went through several names.

+ field went through several names. Recommended -

Old name for Recommends

- + Old name for Recommends. Optional -

Old name for Suggests.

- + Old name for Suggests. + Class -

Old name for Priority.

- + Old name for Priority. +

+ - Configuration file handling - (from old Packaging Manual) - + + Configuration file handling (from old Packaging Manual)

dpkg can do a certain amount of automatic @@ -10526,7 +9925,7 @@ install-info --quiet --remove /usr/share/info/foobar.info

- See the manpage for details.

@@ -10603,3 +10002,4 @@ install-info --quiet --remove /usr/share/info/foobar.info +