Michael Alan Dorman
Richard Braakman
Philip Hands
Manoj Srivastava
@@ -85,21 +37,22 @@ warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details. -
+ +
A copy of the GNU General Public License is available as
- /usr/share/common-licences/GPL in the Debian GNU/Linux
- distribution or on the World Wide Web at
+
This manual describes the policy requirements for the Debian GNU/Linux distribution. This includes the structure and - contents of the Debian archive, several design issues of the + contents of the Debian archive and several design issues of the operating system, as well as technical requirements that each package must satisfy to be included in the distribution. -
+ +- This manual does not describe the technical - mechanisms involved in package creation, installation, and - removal. This information can be found in the Debian - Packaging Manual and the Debian System - Administrators' Manual. -
+ This manual also describes Debian policy as it relates to + creating Debian packages. It is not a tutorial on how to build + packages, nor is it exhaustive where it comes to describing + the behavior of the packaging system. Instead, this manual + attempts to define the interface to the package management + system that the developers have to be conversant with.+ The footnotes present in this manual are + 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. +
+- This document assumes familiarity with these other two - manuals. Unfortunately, the System Administrators' - Manual does not exist yet. + In the normative part of this manual, + the words must, should and + may, and the adjectives required, + recommended and optional, are used to + distinguish the significance of the various guidelines in + this policy document. Packages that do not conform to the + guidelines denoted by must (or required) + will generally not be considered acceptable for the Debian + distribution. Non-conformance with guidelines denoted by + should (or recommended) will generally be + considered a bug, but will not necessarily render a package + unsuitable for distribution. Guidelines denoted by + may (or optional) are truly optional and + adherence is left to the maintainer's discretion. +
+ +
+ These classifications are roughly equivalent to the bug
+ severities serious (for must or
+ required directive violations), minor,
+ normal or important
+ (for should or recommended directive
+ violations) and wishlist (for optional
+ items).
+
Much of the information presented in this manual will be useful even when building a package which is to be - distributed in some other way or is for local use. + distributed in some other way or is intended for local use + only.
- The current version of this document is always accessible from the
- Debian FTP server at
-
- 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
+
+ The
- As the Debian GNU/Linux system is continuously evolving this - manual is changed from time to time. -
+ 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
- While the authors of this document tried hard not to include
- any typos or other errors these still occur. If you discover
- an error in this manual or if you want to tell us any
- comments, suggestions, or critics please send an email to
+ While the authors of this document have tried hard to avoid
+ typos and other errors, these do still occur. If you discover
+ an error in this manual or if you want to give any
+ comments, suggestions, or criticisms please send an email to
the Debian Policy List,
+ Please do not try to reach the individual authors or maintainers + of the Policy Manual regarding changes to the Policy. +
++ 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
+
The Debian GNU/Linux system is maintained and distributed as a - collection of packages. Since there are so many of them (over - 2600) they are split into sections and priorities to - simplify handling of them. + collection of packages. Since there are so many of + them (currently well over 6000), they are split into + sections and given priorities to simplify + the handling of them.
+The effort of the Debian project is to build a free operating system, but not every package we want to make accessible is - free in our sense (see Debian Free Software + free in our sense (see the Debian Free Software Guidelines, below), or may be imported/exported without restrictions. Thus, the archive is split into the sections - main, non-us, non-free, and - contrib.
+ based on their licenses and other restrictions. + + +
+ The aims of this are:
+
+
+
+
- The main section forms the Debian GNU/Linux - distribution.
+ The main and the non-US/main sections + together form the Debian GNU/Linux distribution. + +- Packages in the other sections are not considered as part of - the Debian distribution, though we support their use, and we + Packages in the other sections are not considered to be part + of the Debian distribution, although we support their use and provide infrastructure for them (such as our bug-tracking system and mailing lists). This Debian Policy Manual applies - to these packages as well.
+ to these packages as well. + + +
+ The Debian Free Software Guidelines (DFSG) form our
+ definition of "free software". These are:
+
+ Every package in main and non-US/main + must comply with the DFSG (Debian Free Software + Guidelines). +
+ +
+ In addition, the packages in main
+
+
+
+ Similarly, the packages in non-US/main
+
+
+
+ Every package in contrib and + non-US/contrib must comply with the DFSG. +
+ +
+ In addition, the packages in contrib and
+ non-US/contrib
+
+
+
+ Furthermore, packages in contrib must not require + a package in a non-US section for compilation or + execution. +
+ +
+ Examples of packages which would be included in
+ contrib or non-US/contrib are:
+
+
+
+ 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
+
+
+
+ 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 + 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. +
+
- The aims of this policy are:
+ Every package must be accompanied by a verbatim copy of
+ its copyright and distribution license in the file
+
+ We reserve the right to restrict files from being included
+ anywhere in our archives if
We want to make as much software available as we
- can. We want to encourage everyone to write free software. We want 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 (DFSG) is our
- definition of `free' software.
-
- 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.
-
- The program must include source code, and must allow
- distribution in source code as well as compiled form.
-
- 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.
-
- The license may restrict source-code from being
- distributed in modified form only if the
- license allows the distribution of ``patch files''
- with the source code for the purpose of modifying the
- program at build time. The license must explicitly
- permit distribution of software built from modified
- source code. The license may require derived works to
- carry a different name or version number from the
- original software. (This is a compromise. The Debian
- group encourages all authors to not restrict any
- files, source or binary, from being modified.)
-
- The license must not discriminate against any person
- or group of persons.
-
- 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.
-
- 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.
-
- The rights attached to the program must not depend on
- the program's being part of a Debian system. If the
- program is extracted from Debian and used or
- distributed without Debian but otherwise within the
- terms of the program's license, all parties to whom
- the program is redistributed must have the same
- rights as those that are granted in conjunction with
- the Debian system.
-
- 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.
-
- The ``GPL,'' ``BSD,'' and ``Artistic'' licenses are
- examples of licenses that we consider free.
-
+ Packages whose copyright permission notices (or patent + problems) do not even allow redistribution of binaries + only, and where no special permission has been obtained, + must not be placed on the Debian FTP site and its mirrors + at all. +
+ ++ Note that under international copyright law (this applies + in the United States, too), no distribution or + modification of a work is allowed without an explicit + notice saying so. Therefore a program without a copyright + notice is copyrighted and you may not do anything + to it without risking being sued! Likewise if a program + has a copyright notice but no statement saying what is + permitted then nothing is permitted. +
+ ++ Many authors are unaware of the problems that restrictive + copyrights (or lack of copyright notices) can cause for + the users of their supposedly-free software. It is often + worthwhile contacting such authors diplomatically to ask + them to modify their license terms. However, this can be a + politically difficult thing to do and you should ask for + advice on the debian-legal mailing list first, as + explained below. +
+ +
+ When in doubt about a copyright, send mail to
+
- Every package in "main" must comply with the DFSG (Debian - Free Software Guidelines).
+ The packages in the sections main, + contrib and non-free are grouped further + into subsections to simplify handling. +
- In addition, the packages in "main"
+ 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:
- must not require a package outside of "main" for
- compilation or execution (thus, the package may not
- declare a "Depends" or "Recommends" relationship on a
- non-main package),
-
- must not be so buggy that we refuse to support them,
-
- must meet all policy requirements presented in this
- manual.
-
+ 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. +
+- Every package in "contrib" must comply with the DFSG. + Each package should have a priority value, which is + 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.
- Examples of packages which would be included in "contrib" are
-
- free packages which require "contrib", "non-free", or
- "non-US" packages or packages which are not in our
- archive at all for compilation or execution,
-
- wrapper packages or other sorts of free accessories for
- non-free programs,
-
- packages which we don't want to support because they are too
- buggy, and
-
- packages which fail to meet some other policy requirements in
- a serious way.
-
+ The following priority levels are recognised by the
+ Debian package management tools.
+
+ (In a sense everything that isn't required is
+ optional, but that's not what is meant here.) This is
+ all the software that you might reasonably want to
+ install if you didn't know what it was and don't have
+ specialized requirements. This is a much larger system
+ and includes the X Window System, a full TeX
+ distribution, and many applications. Note that
+ optional packages should not conflict with each other.
+
+
- `Non-free' contains packages which are not compliant with - the DFSG or which are encumbered by patents or other legal - issues that make their distribution problematic.
+- All packages in `non-free' must be electronically - distributable across international borders. + Packages must not depend on packages with lower priority + values (excluding build-time dependencies). In order to + ensure this, the priorities of one or more packages may need + to be adjusted.
-- Some programs with cryptographic program code must be stored - on the "non-us" server because of export restrictions of the - U.S.
+
+ The Debian GNU/Linux distribution is based on the Debian
+ package management system, called
- This applies only to packages which contain cryptographic - code. A package containing a program with an interface to a - cryptographic program or a program that's dynamically linked - against a cryptographic library can be distributed if it is - capable of running without the cryptography library or - program. + Every package must have a name that's unique within the Debian + archive.
- -- Every package must be accompanied by a verbatim copy of its - copyright and distribution license in the file - /usr/share/doc/<package-name>/copyright (see for details).
+ 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. + +
- 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.
-
-
+ Every package has a version number recorded in its
+ Version control file field, described in
+ .
- Programs whose authors encourage the user to make donations - are fine for the main distribution, provided that the - authors do not claim that not donating is immoral, - unethical, illegal or something similar; otherwise they must - go in contrib (or non-free, if even distribution is - restricted by such statements).
+ 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. +- Packages whose copyright permission notices (or patent - problems) do not allow redistribution even of only binaries, - and where no special permission has been obtained, cannot be - placed on the Debian FTP site and its mirrors at all.
+ If an upstream package has problematic version numbers they + should be converted to a sane form for use in the + Version field. + + ++ 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. +
+- 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.
+ 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. +- 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 is a - politically difficult thing to do and you should ask for - advice on debian-devel first.
+ 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. +
- When in doubt, send mail to
-
- The packages in the main, contrib, and - non-free sections are grouped further into - subsections to simplify handling of them.
+ If the maintainer of a package quits from the Debian + project, "Debian QA Group" +- The section for each package is specified in the package's - control record. However, the maintainer of the - Debian archive may override this selection to assure the - consistency of the Debian distribution.
+ 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 . +- Please check the current Debian distribution to see which - sections are available.
- -- Each package is given a certain priority value, - which is included in the package's control - record. This information is used in the Debian package - management tool to separate high-priority packages from - less-important packages.
- + 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 following priority levels are supported by the
- Debian package management system,
- required packages are necessary for the
- proper functioning of the system. You must not remove
- these packages or your system may become totally
- broken and you may not even be able to use
-
- Important programs, including those which one would
- expect to find on any Unix-like system. If the
- expectation is that an experienced Unix person who
- found it missing would say `What the F*!@<+ is
- going on, where is
- These packages provide a reasonably small but not too
- limited character-mode system. This is what will
- install by default if the user doesn't select anything
- else. It doesn't include many large applications, but
- it does include Emacs (this is more of a piece of
- infrastructure than an application) and a reasonable
- subset of TeX and LaTeX (if this is possible without
- X).
- (In a sense everything is optional that isn't
- required, but that's not what is meant here.) This is
- all the software that you might reasonably want to
- install if you didn't know what it was or don't have
- specialized requirements. This is a much larger system
- and includes the X Window System, a full TeX
- distribution, and many applications.
- This contains packages that conflict with others with
- higher priorities, or are only likely to be useful if
- you already know what they are or have specialized
- requirements.
-
- Packages may not depend on packages with lower priority - values. If this does happen, one of the priority values - will have to be adapted. + 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 Debian GNU/Linux distribution is based on the Debian
- package management system, called
- Every package must have a name that's unique within the Debian - archive.
- -- Package names may only consist of lower case letters, digits (0-9), - plus (+) or minus (-) signs, and periods (.).
- + +- The package name is part of the file name of the - .deb file and is included in the control field - information. + The single line synopsis should be kept brief - certainly + under 80 characters.
-- Every package must have exactly one maintainer at a - time. This person is responsible that the license of the - package's software complies with the policy of the - distribution this package is included in.
- -- The maintainer must be specified in the - Maintainer control field with the correct name - and a working email address for the Debian maintainer of - the package. If one person maintains several packages - he/she should try to avoid having different forms of their - name and email address in different Maintainer - fields.
- -- If the maintainer of a package quits from the Debian - project the Debian QA Group takes over the maintainership - of the package until someone else volunteers for that - task. These packages are called orphaned - packages. -
-- Every Debian package must have an extended description - stored in the appropriate field of the control record.
- -- The description must be written so that it tells the user - what they need to know to decide whether to install the - package. This description should not just be copied from - the blurb for the program. Instructions for configuring - or using the package must not be included -- that is what - installation scripts, manual pages, Info files, etc. are - for. Copyright statements and other administrivia must - not be included -- that is what the copyright file is - for.
-- Every package has to specify the dependency information - about other packages, that are required for the first to - work correctly.
- -- For example, for any shared libraries required by - dynamically-linked executable binary in a package a - dependency entry has to be provided.
- -- It is not necessary for other packages to declare any - dependencies they have on other packages which are marked - Essential (see below).
- -- Sometimes, a package requires another package to be - installed and configured before it can be - installed. In this case, you'll have to specify a - Pre-Depends entry for the package.
- -- You must 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.
- Sometimes, there are several packages doing more-or-less - the same job. In this case, it's useful to define a - virtual package who's name describes the function - the packages have. (The virtual packages just exist - logically, not physically--that's why they are called - virtual.) The packages with this particular - function will then provide the virtual - package. Thus, any other package requiring that function - can simply depend on the virtual package without having to - specify all possible packages individually.
- -- All packages must use virtual package names where - appropriate, and arrange to create new ones if necessary. - They must not use virtual package names (except privately, - amongst a cooperating group of packages) unless they have - been agreed upon and appear in the list of virtual package - names.
- -
- The latest version of the authoritative list of virtual
- package names can be found on
-
- The packages included in the base section have a - special function. They form a minimum subset of the Debian - GNU/Linux system that is installed before everything else - on a new system. Thus, only very few packages are allowed - to go into the base section to keep the required - disk usage very small.
- -- Most of these packages should have the priority value - required or at least important, and many - of them will be tagged essential (see below).
- -- You must not place any packages into the base - section before this has been discussed on the - debian-devel mailing list and a consensus about - doing that has been reached.
- 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 can not easily be removed (you'll
- have to specify an extra force option to
-
- You must not tag any packages essential before - this has been discussed on the debian-devel - mailing and a consensus about doing that has been - reached.
- The package installation scripts must avoid producing
- output which it is unnecessary for the user to see and
- should rely on
- 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), 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
- Any necessary prompting should almost always be confined
- to the post-installation script, and should be protected
- with a conditional so that unnecessary prompting doesn't
- happen if a package's installation fails and the
-
- 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.
- -
- Do not use
- In order for
- You should specify the most recent version of the - packaging standards with which your package complies in - the source package's Standards-Version field.
- -- This value will be used to file bug reports automatically - if your package becomes too much out of date.
- -- The value corresponds to a version of the Debian manuals, - as can be found on the title page or page headers and - footers (depending on the format).
- -- The version number has four components--major and minor - 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 - which do not change the meaning are made, or changes which - do not affect the contents of packages.
+ +
- For package maintainers, only the first 3 digits of the
- manual version are significant in representing the
- Standards-Version, and either these 3 digits or
- the complete 4 digits can be specified--that's up to the
- maintainer.
-
- In the past, people specified 4 digits in the
- Standards-Version field, like `2.3.0.0'. Since any
- `patch-level changes' don't introduce new policy, it
- was thought it would be better to relax policy and
- only require that the first 3 digits are specified. (4
- digits can still be used if someone wants to do so.)
-
- 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 may update the - Standards-Version source package field and - release it.
- If changes to the source code are made that are generally - applicable please try to get them included in the upstream - version of the package by supplying the upstream authors - with the changes in whatever form they prefer.
- -
- If you need to configure the package differently for
- Debian or for Linux, and the upstream source doesn't
- provide a way to configure it the way you need to, please
- add such configuration facilities (for example, a new
-
- Please make sure that the
- If you need to edit a
- Document your changes and updates to the source package - properly in the debian/changelog file.
- -- A copy of the file which will be installed in - /usr/share/doc/package/copyright should be - in debian/copyright.
- -
- In non-experimental packages you may only use a format for
- debian/changelog which is supported by the most
- recent released version of
- When
- 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 must include a separate set -e - command at the start of every makefile command that's - actually one of these miniature shell scripts.
- The include file
- Debian packages should be ported to include
-
- The location of all installed files and directories must
- comply (with some exceptions
- In an as yet unreleased version of the standard, the
- location of the mail spool and state information
- directories has changed; and we propose to follow the
- latter, since that would mean that we do not have to
- move things around again when the new version of the
- FHS comes around). The changes are, amongst others,
- s%/var/mail%/var/spool/mail% and
- s%/var/state%/var/lib%
- As mandated by the FHS no package should place any
- files in /usr/local, either by putting them in
- the file system archive to be unpacked by
- However, the package should create empty directories below - /usr/local so that the system administrator knows - where to place site-specific files. These directories - should be removed on package removal if they are - empty.
- -- Note, that this applies only to directories below - /usr/local, not in - /usr/local. The directory /usr/local - itself may only contain the sub-directories listed in - FHS, section 4.6. However, you may create directories - below them as you wish. You may not remove any of the - directories listed in 4.6, even if you created them.
- -
- Since /usr/local may be mounted read-only from a
- remote server, these directories have to be created and
- removed by the postinst and prerm
- maintainer scripts. These scripts must not fail if either
- of these operations fail. (In the future, it will be
- possible to tell
- For example, the
- If you do create a directory in /usr/local for - local additions to a package, you must ensure that - settings in /usr/local take precedence over the - equivalents in /usr.
- -- The /usr/local directory itself and all the subdirectories - created by the package should have permissions 2775 (group-writable - and set-group-id) and be owned by root.staff.
+ +- The Debian system can be configured to use either plain or - shadow passwords.
- -- Some user ids (UIDs) and group ids (GIDs) are reserved - globally for use by certain packages. Because some packages - need to include files which are owned by these users or - groups, or need the ids compiled into binaries, these ids - must be used on any Debian system only for the purpose for - which they are allocated. This is a serious restriction, and - we should avoid getting in the way of local administration - policies. In particular, many sites allocate users and/or - local system groups starting at 100.
- -- Apart from this we should have dynamically allocated ids, - which should by default be arranged in some sensible - order--but the behavior should be configurable.
- -- No package except base-passwd may modify - /etc/passwd, /etc/shadow, or - /etc/group.
- -
- The UID and GID ranges are as follows:
-
- Globally allocated by the Debian project, must be the
- same on every Debian system. These ids will appear in
- the passwd and group files of all
- Debian systems, new ids in this range being added
- automatically as the base-passwd package is
- updated.
- Packages which need a single statically allocated uid
- or gid should use one of these; their maintainers
- should ask the base-passwd maintainer for
- ids.
- 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.
- Dynamically allocated user accounts. By default
- Reserved.
- Globally allocated by the Debian project, but only
- created on demand. The ids are allocated centrally and
- statically, but the actual accounts are only created
- on users' systems on demand.
- These ids are for packages which are obscure or which
- require many statically-allocated ids. These packages
- should check for and create the accounts in
- /etc/passwd or /etc/group (using
- Reserved. User `nobody.'
- (uid_t)(-1) == (gid_t)(-1). NOT TO BE USED,
- because it is the error return sentinel value.
+ Every package must specify the dependency information + about other packages that are required for the first to + work correctly. +
+ ++ For example, a dependency entry must be provided for any + shared libraries required by a dynamically-linked executable + binary in a package. +
+ ++ Packages are not required to declare any dependencies they + have on other packages which are marked Essential + (see below), and should not do so unless they depend on a + particular version of that package. +
+ ++ Sometimes, a package requires another package to be installed + and configured before it can be installed. In this + case, you must specify a Pre-Depends entry for + the package. +
+ ++ You should not specify a Pre-Depends entry for a + package before this has been discussed on the + debian-devel mailing list and a consensus about + doing that has been reached. +
+ ++ The format of the package interrelationship control fields is + described in .
- The /etc/init.d directory contains the scripts
- executed by
-
- These scripts are being referenced by symbolic links in
- the /etc/rcn.d directories. When
- changing runlevels,
-
- The names of the links all have the form
- Smm/script or
- Kmm/script 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.
-
- When
- 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. 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 two-digit number mm is used to decide which
- order to start and stop things in--low-numbered links have
- their scripts run first. For example, the K20
- scripts will be executed before the K30 scripts.
- This is used when a certain service must be started before
- another. For example, the name server
- Packages can and 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 the service, stop the service, stop and restart the service, cause the configuration of the service to be
- reloaded without actually stopping and restarting
- the service, cause the
- configuration to be reloaded if the service supports
- this, otherwise restart the service.
- 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
-
- If a service reloads its configuration automatically (as
- in the case of
- These scripts should not fail obscurely when the
- configuration files remain but the package has been
- removed, as the default in
- A program is provided,
- You should use this script to make changes to - /etc/rcn.d and never include - any /etc/rcn.d symbolic links in the - actual archive.
- -
- By default
- To get the default behavior for your package, put in your
- postinst script
-
- This will use a default sequence number of 20. If it does
- not matter when or in which order the script is run, use
- this default. If it does, then you should talk to the
- maintainer of the
- For more information about using update-rc.d,
- please consult its manpage
- There is another directory, /etc/rc.boot, which - contains scripts which are run once per machine boot. - This facility is provided for initialization of hardware - devices, cleaning up of leftover files, and so forth.
- -
- For example, the
- The files in /etc/rc.boot should not be - links into /etc/init.d--they should be the - scripts themselves.
- -- rc.boot should not be used for starting - general-purpose daemons and similar activities. This - should be done using the rcn.d scheme, - above, so that the services can be started and stopped - cleanly when the runlevel changes or the machine is to be - shut down or rebooted.
- Do not include the
- /etc/rcn.d/* symbolic links in the
- .deb file system archive! This will cause
- problems! You should create them with
-
- Do not include the /etc/rcn.d/* symbolic links in
-
- The
-
- Another example on which to base your /etc/init.d - scripts is in /etc/init.d/skeleton.
- -
- If this package is happy with the default setup from
-
- Packages may not touch the configuration file - /etc/crontab, nor may they 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 if the
- package in one of the following directories:
-
- If a certain job has to be executed more frequently than
- `daily,' the package should install a file
- /etc/cron.d/<package-name> tagged as
- configuration file. This file uses the same syntax as
- /etc/crontab and is processed by
- All files installed in any of these directories have to be - scripts (shell scripts, Perl scripts, etc.) so that they can - easily be modified by the local system administrator. In - addition, they have to be registered as configuration - file.
- -- The scripts in these directories have to 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 the configuration files are - kept on the system in this situation.
- This section describes different formats 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.
- -- Please look very careful at the details. We want to get the - messages to look exactly the same way concerning 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 isn't covered in the sections - 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. + +
-
- Every message should cover one line, start with a
- capital letter and end with a period `.'.
- If you want to express that the computer is working on
- something (performing a specific task, not starting or
- stopping a program), we use an ``ellipsis'', namely
- three dots `...'. Note that we don't insert spaces in
- front of or behind 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
-
-
- The following formats must be used
- + 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 +
- when daemons get started.
- Use this format if your script starts one or more
- daemons. The output should look like this (a single
- line, no leading spaces):
-
- For example, the output of /etc/init.d/lpd would look like:
-
- This can be achieved by saying
- when something needs to be configured.
- If you have to set up different parameters of the
- system upon boot up, you can use this format:
-
- You can use the following echo statement to get the quotes right:
-
- Note that the left quotation mark (`) is different
- from the right ('). when a daemon is stopped.
- When you stop a daemon you should issue a message
- similar to the startup message, except that `Starting'
- is replaced with `Stopping'.
- So stopping the printer daemon will like like this:
- when something is executed.
- There a 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
- via `netdate' or killing all processes when the system
- comes down. Your message should like this:
- when the configuration is reloaded.
- When a daemon is forced to reload its configuration
- files you should use the following format:
- when none of the above rules apply.
- If you have to print a message that doesn't fit into
- the styles described above, you can use something
- appropriate, but please have a look at the overall
- rules listed above.
-
- Menu entries should follow the current menu policy as
- defined in the file
- The Debian menu packages provides a unique
- interface between packages providing applications and
- documents, and menu programs (either X window
- managers or text-based menu programs as
-
- 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 refer to the Debian Menu System document - that comes with the menu package for information - about how to register your applications and web - documents.
- To achieve a consistent keyboard configuration (i.e., all - applications interpret a keyboard event the same way) all - programs in the Debian distribution have to be configured to - comply with the following guidelines.
- -
- Here is a list that contains certain keys and their interpretation:
-
- delete the character to the left of the cursor delete the character to the right of the cursor emacs: the help prefix
- The following list explains how the different programs - should be set up to achieve this:
- + Some packages are tagged essential for a system + using the Essential control file field. + The format of the Essential control field is + described in . + +
- `<--' 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 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 ~ (this is the case at the
- moment).
- X applications are configured so that Backspace
- deletes left, and Delete deletes right. Motif
- applications already work like this. stty erase ^? .
- The `xterm' terminfo entry should have ESC [ 3
- ~ for kdch1, just like 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:
- + 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. + +
-
- 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 via the same X resources that we
- use to do it for our own, or have our clients be
- configured via 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 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.
-
+ 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.
- No program may 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.)
- + 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- If a program should depend on environment variables for its - configuration, the program has to 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 should be replaced by a small - `wrapper' shell script which sets the environment variables - and calls the original program.
- + 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. + +
- Here is an example of a wrapper script for this purpose:
-
-
- Furthermore, as /etc/profile is a configuration
- file of the
- It is not allowed that two packages 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.') - If this case happens, one of the programs has to be - renamed. The maintainers should report this to the - developers' mailing and try to find a consensus about - which package will have to be renamed. If a consensus can - not be reached, both programs must be - renamed.
- -
- Generally the following compilation parameters should be used:
-
- Note that all installed binaries should be stripped,
- either by using the -s flag to
-
- The -g flag is useful on compilation so that you - have available a full set of debugging symbols in your - built source tree, in case anyone should file a bug report - involving (for example) a core dump.
- -- The -N flag should not be used. On a.out systems - it may have been useful for some very small binaries, but - for ELF it has no good effect.
- -- It is up to the package maintainer to decide what - compilation options are best for the package. Certain - binaries (such as computationally-intensive programs) may - 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.
- 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 is compiled twice.
- -- You have to 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
-
- 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. -
- -
- An ever increasing number of packages are using libtool to
- do their linking. The latest GNU libtools (>= 1.3a) can take
- advantage of installed libtool archive files (`*.la'). 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 (e.g. dependency libraries for static
- linking). Also, they're essential for programs using
- libltdl.
+
+
+ The package installation scripts should avoid producing
+ output which it is unnecessary for the user to see and
+ should rely on
- Certainly libtool is fully capable of linking against shared
- libraries which don't have .la files, but being 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-1.4 (and to a
- lesser extent libtool-1.3), the .la files will also store
- information about inter-library dependencies which cannot
- necessarily be derived after the .la file is deleted.
+ Errors which occur during the execution of an installation
+ script must be checked and the installation must not
+ continue after an error.
- Packages that use libtool to create shared libraries must
- include the .la files in the -dev
- packages. This is a good idea in general, and especially
- for static linking issues.
+ Note that in general applies to package
+ maintainer scripts, too.
- Please 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.
+ You should not use
- Packages involving shared libraries should be split up
- into several binary packages.
- For a straightforward library which has a development
- environment and a runtime kit including just shared
- libraries you need to create two packages:
- librarynamesoname
- (soname is the shared object name of the shared
- library--it's the thing that has to match exactly between
- building an executable and running it for the dynamic
- linker to be able run the program; usually the
- soname is the major number of the library) and
- librarynamesoname-dev.
- If you prefer only to support one development version at a
- time you may name the development package
- libraryname-dev; otherwise you may
- wish to use
- Packages which use the shared library should have a
- dependency on the name of the shared library package,
- librarynamesoname. When
- the soname changes you can have both versions
- of the library installed while moving from the old library
- to the new.
- 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 soname in the package name) or if the
- development package is small include them in there.
- If you have several shared libraries built from the same
- source tree you can lump them all together into a single
- shared library package, provided that you change all 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).
- Follow the directions in the Debian Packaging
- Manual for putting the shared library in its package,
- and make sure you include a shlibs control area
- file with details of the dependencies for packages which
- use the library.
- Shared libraries should not be installed
- executable, since
- All command scripts, including the package maintainer
- scripts inside the package and used by
- In the case of Perl scripts this should be
- #!/usr/bin/perl.
- Shell scripts (
- The standard shell interpreter `/bin/sh' may be a
- symbolic link to any POSIX compatible shell. Thus, shell
- scripts specifying `/bin/sh' as interpreter may
- only use POSIX features. If a script requires non-POSIX
- features from the shell interpreter, the appropriate shell
- has to be specified in the first line of the script (e.g.,
- `#!/bin/bash') and the package has to depend on
- the package providing the shell (unless the shell package
- is marked `Essential', e.g., in the case of
-
- Restrict your script to POSIX features when possible so
- that it may use /bin/sh as its interpreter. If
- your script works with
- Perl scripts should check for errors when making any
- system calls, including open, print,
- close, rename and system.
-
- Any scripts which create files in world-writable
- directories (e.g., in /tmp) have to use a
- mechanism which will fail if a file with the same name
- already exists.
- The Debian base distribution provides the
-
- 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 `/'.)
- In addition, symbolic links should be specified as short
- as possible, i.e., link targets like `foo/../bar' are
- deprecated.
- Note that when creating a relative link using
-
- For example, in your
- 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.')
- No package may include device files in the package file
- tree.
- If a package needs any special device files that are not
- included in the base system, it has to call
-
- No package should remove any device files in the
- postrm or any other script. This is left to the
- system administrator.
- Debian uses the serial devices
- /dev/tty*. Programs using the old
- /dev/cu* devices should be changed to use
- /dev/tty*.
+ All packages which supply an instance of a common command
+ name (or, in general, filename) should generally use
+
+ Package maintainer scripts may prompt the user if
+ necessary. Prompting should be done by communicating
+ through a program, such as
- Any configuration files created or used by your package
- should reside in /etc. If there are several you
- should consider creating a subdirectory named after your
- package.
- It is almost certain that any file in /etc that
- is in your package's file system archive should be listed
- in
- Only packages that are tagged conflicting with
- each other may specify the same file as
- conffile. A package may not modify a
- configuration file of another package.
- If two or more packages use the same configuration file,
- one of these packages has to be defined as owner
- of the configuration file, i.e., it has to list the file
- as conffile and has to provide a program that
- modifies the configuration file.
- The other packages have to depend on the owner
- package and use that program to update the configuration
- file.
- Sometimes it's appropriate to build a new package, which
- just provides the basic infrastructure for the
- other packages and which manages the shared configuration
- files. (Check out the
- Files in /etc/skel will automatically be copied
- into new user accounts by
- 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 listed in - conffiles, if it is not generated and modified dynamically - by the package's installation scripts).
- + Packages which use the Debian Configuration management + specification may contain an additional +- However, programs that require dotfiles in order to - operate sensibly (dotfiles that they do not create - themselves automatically, that is) are a bad thing, and - programs should be configured by the Debian default - installation as close to normal as possible.
- + 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- Therefore, if a program in a Debian package needs to be - configured in some way in order to operate sensibly that - configuration should be done in a site-wide global - configuration file elsewhere 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 should a default per-user file be placed in - /etc/skel.
- -- /etc/skel should be as empty as we can make it. - This is particularly true because there is no easy - mechanism for ensuring that the appropriate dotfiles are - copied into the accounts of existing users when a package - is installed.
- -- Ideally the sysadmin should not have to do any - configuration other than that done (semi-)automatically by - the postinst script.
-
+ 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
+
+ Any necessary prompting should almost always be confined
+ to the
- 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. + Source packages should specify the most recent version number + of this policy document with which your package complied + when it was last updated.
- A better scheme is to use logrotate, a GPL'd program - developed by Red Hat, which centralizes log management. It - has both a config file (/etc/logrotate.conf) and a - directory where packages can drop logrotation info - (/etc/logrotate.d). + This information may be used to file bug reports + automatically if your package becomes too much out of date.
- Log files should usually be named - /var/log/package.log. If you have many - log files, or need a separate directory for permissions - reasons (/var/log is writable only by - root), you should usually create a directory named - /var/log/package.
- -
- Make sure that any log files are rotated occasionally so
- that they don't grow indefinitely; the best way to do this
- is to drop a script into the directory
- /etc/logrotate.d and use the facilities provided by
- logrotate. Here is a good example for a logrotate config
- file (for more information see
- Make sure that any log files are removed when the package is - purged (but not when it is only removed), by checking the - argument to the postrm script (see the Debian - Packaging Manual for details).
-
- 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 must try to be as consistent as possible
- with the rest of the system. You should probably also
- discuss it on
- Files should be owned by root.root, and made - writable only by the owner and universally readable (and - executable, if appropriate).
- -- 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.
- -- 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.
- -- 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; there is no point in making - them unreadable to those users who must not be allowed to - execute them.
- -
- Do not arrange that the system administrator can only
- reconfigure the package to correspond to their local
- security policy by changing the permissions on a binary.
- Ordinary files installed by
- 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). In - this case you need a statically allocated id.
- -- You must ask for a user or group id from the base system - maintainer, and must not release the package until you - have been allocated one. Once you have been allocated one - you must make the package depend on a version of the base - system with the id present in /etc/passwd or - /etc/group, or alternatively arrange for your - package to create the user or group itself with the - correct id (using adduser) in its pre- or - post-installation script (the latter is to be preferred if - it is possible).
- -
- On the other hand, the program may able to determine the
- uid or gid from the group name at runtime, so that a
- dynamic id can be used. In this case you must choose an
- appropriate user or group name, discussing this on
-
- 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 a program needs to specify an architecture specification
- string in some place, the following format has to be used:
-
- 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 to other Linux - distributions. Also note, that we don't use - `<arch>-unknown-linux', since the `unknown' does not - look very good.
- The configuration files /etc/services,
- /etc/protocols, and /etc/rpc are managed
- by the
- If a package requires a new entry in one of these files, the
- maintainer has to get in contact with the
-
- The configuration file /etc/inetd.conf may be
- modified by the package's scripts only via the
-
- If a package wants to install an example entry into
- /etc/inetd.conf, the entry has to be preceded with
- exactly one hash character (#). Such lines are treated as
- `commented out by user' by the
- 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. -
- -- The files /var/run/utmp, /var/log/wtmp and - /var/log/lastlog must be installed writeable by - group utmp. Programs who need to modify those files must - be installed install setgid utmp. + explains the technical details.
- 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.
- -- In addition, every program should choose a good default - editor/pager if none is selected by the user or system - administrator.
- -- Thus, every program that launches an editor or pager has to - use the EDITOR or PAGER environment variables to determine - the editor/pager the user wants to get started. If these - variables are not set, the programs `/usr/bin/editor' and - `/usr/bin/pager' have to be used, respectively.
- -- These two files are managed through `alternatives.' That is, - every package providing an editor or pager has to call the - `update-alternatives' script to register these programs.
- -- If it is very hard to adapt a program to make us of the - EDITOR and PAGER variable, that program should be configured - to use `/usr/bin/sensible-editor' and - `/usr/bin/sensible-pager' as editor or pager program, - respectively. These are two scripts provided in the Debian - base system that check the EDITOR and PAGER variables and - launches the appropriate program or falls back to - `/usr/bin/editor' and `/usr/bin/pager', automatically.
- -- Since the Debian base system already provides an editor and - a pager program, there is no need for a package to depend on - `editor' and `pager', nor is it necessary for a package to - provide such virtual packages.
- This section describes the locations and URLs that have to - be used by all web servers and web application in the Debian - system.
- -
- Cgi-bin executable files are installed in the
- directory
- Access to html documents
- Html documents for a package are stored in
- /usr/share/doc/package and can be referred to as
- Web Document Root
- Web Applications should try to avoid storing files in
- the Web Document Root. Instead use the
- /usr/share/doc/<package> directory for documents and
- register the Web Application via the menu package. If
- access to the web-root is unavoidable then use
-
- Debian packages which process electronic mail, whether - mail-user-agents (MUAs) or mail-transport-agents (MTAs), - must make sure 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 mail spool is /var/spool/mail and the interface - to send a mail message is /usr/sbin/sendmail (as - per the FHS). The mail spool is part of the base system - and not part of the MTA package.
- -- All Debian MUAs and MTAs have to use the maillock - and mailunlock functions provided by the - liblockfile packages to lock and unlock mail - boxes. These functions implement a NFS-safe locking - mechanism. (It is ok if MUAs and MTAs don't link against - liblockfile but use a compatible mechanism. Please - compare the mechanisms very carefully!)
- -- Mailboxes are generally 660 user.mail - unless the user 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 mail.mail, and MUAs need to - be setgid mail to do the locking mentioned above (and - obviously need to 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
- The convention of writing forward to - address in the mailbox itself is not - supported. Use a .forward file instead.
- -
- The location for the
- If you need to know what name to use (for example) on - 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).
- -
- A package should check for the existence of this file. If
- it exists it should use it without comment. (An MTA's
- prompting configuration script may wish to prompt the user
- even if it finds this file exists.) If it does not exist it
- should prompt the user for the value 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 says:
-
- All the configuration files related to the NNTP (news) - servers and clients should be located under - /etc/news.
- -
- There are some configuration issues that apply to a number
- of news clients and server packages on the machine. These
- are:
-
- A string which shall appear as the
- organization header for all messages posted
- by NNTP clients on the machine Contains the FQDN of the upstream NNTP
- server, or localhost if the local machine is
- an NNTP server.
- Some programs can be configured with or without support for the X - Window System. Typically, binaries produced with support for X - will need the X shared libraries to run. -
- -- Such programs should be configured with X support, - and should declare a dependency on xlib6g (which - contains X shared libraries). Users who wish to use the - program can install just the relatively small - xfree86-common and xlib6g packages, and do - not need to install the whole of X.
- -- Do not create two versions (one with X support and one - without) of your package.
- -- Application defaults files have to be installed in - the directory /usr/X11R6/lib/X11/app-defaults/. - They are considered as part of the program code. Thus, they - should not be modified and should not be tagged as - conffiles. If the local system administrator wants - to customize X applications globally, a file with the same - name as that of the package should be placed in the - /etc/X11/Xresources/ directory instead. - Important: packages that install files into the - /etc/X11/Xresources/ directory must - declare a conflict with xbase (<< - 3.3.2.3a-2); if this is not done it is possible for the - package to destroy a previously-existing - /etc/X11/Xresources file.
- -- No package should ever install files into the directories - /usr/bin/X11/, /usr/doc/X11/, - /usr/include/X11/, or /usr/lib/X11/; these - directories are actually symbolic links, which dpkg - does not follow when unpacking a package. Instead, use - /usr/X11R6/bin/, /usr/doc/package/ (i.e., - place files with the rest of your package's documentation), - /usr/X11R6/include/, and - /usr/X11R6/lib/. This restriction governs only the - paths used by the package as it is unpacked onto the system; it - is permissible, and even preferable, for files within a package - (shell scripts, for instance) to refer to the - /usr/{bin,include,lib}/X11/ directories rather than - their /usr/X11R6/ counterparts -- this way they do not - have to be modified in the event that the X Window System - packages install their files into a different directory in the - future.
+- If you package a program that requires the (non-free) - OSF/Motif library, you should try to determine whether the - programs works reasonably well with the free - re-implementation of Motif called LessTif. If so, build the - package using the LessTif libraries; it can then go into the - main section of the package repository and become an - official part of the Debian distribution.
- -- If however, the Motif-based program works insufficiently - well with LessTif, you should instead provide "-smotif" and "-dmotif" - versions (appending these identifiers to the name of the - package), which are statically and dynamically linked - against the Motif libraries, respectively. (All known - versions of OSF/Motif permit redistribution of - statically-linked binaries using the library, but check the - license on your copy of Motif to be sure.) This two-package - approach allows users without Motif to use the package, - whereas users with Motif installed can enjoy the advantages - of the dynamically-linked version (a considerable savings in - disk space usage, download time, etc.). Neither "-smotif" - nor "-dmotif" packages can go into the main section; if the - licensing on the package is compatible with the Debian Free - Software Guidelines, it may go into the contrib section; - otherwise it must go into the non-free section. - -
-
- Please refer to the `Debian Emacs Policy' (documented in
- debian-emacs-policy.gz of the
-
- The permissions on /var/lib/games are 755 - root.root.
-- Each game decides on its own security policy.
- + 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. + +- Games which require protected, privileged access to - high-score files, savegames, etc., must 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 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- 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. Do 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.
- + You should make sure that the- 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.
+ If you need to edit a
- You must install manual pages in
- If no manual page is available for a particular program,
- utility or function and this is reported as a bug on
- debian-bugs, a symbolic link from the requested manual page
- to the
- 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.
- + Changes in the Debian version of the package should be + briefly explained in the Debian changelog file ++ Mistakes in changelogs are usually best rectified by making + a new changelog entry rather than "rewriting history" by + editing old changelog entries. +
+ +
+ The format of the
- Manual pages should be installed compressed using gzip - -9.
- + That format is a series of entries like this: + +- 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. Do not create hard - links in the manual page directories, and do not 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).
- Info documents should be installed in /usr/share/info. - They should be compressed with gzip -9.
- + distribution(s) lists the distributions where + this version should be installed when it is uploaded - it + is copied to the Distribution field in the +
- Your package must call
- 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.
- + 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. + +
- You must remove the entries in the pre-removal script:
-
- If
- Any additional documentation that comes with the package can - be installed at the discretion of the package maintainer. - Text documentation should be installed in a directory - /usr/share/doc/package, where - package is the name of the package, and - compressed with gzip -9 unless it is small.
- + The date should be in RFC822 format- 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.
- + 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. + +- 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!
+ For more information on placement of the changelog files + within binary packages, please see . + + +
+ In non-experimental packages you must use a format for
+
+ 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
- The unification of Debian documentation is being carried out - via HTML.
- + When
- If your package comes with extensive documentation in a
- mark up 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, though.
+ Maintainers should preserve the modification times of the
+ upstream source files in a package, as far as is reasonably
+ possible.
- Other formats such as PostScript may be provided at your - option.
- Every package must be accompanied by a verbatim copy of its - copyright and distribution license in the file - /usr/share/doc/<package-name>/copyright. This file must - neither be compressed nor be a symbolic link.
- -- In addition, the copyright file must say where the upstream - sources (if any) were obtained, and explain briefly what - modifications were made in the Debian version of the package - compared to the upstream one. It must name the original - authors of the package and the Debian maintainer(s) who were - involved with its creation.
- -- /usr/share/doc/<package-name> may be a symbolic link to a - directory in /usr/share/doc only if two packages both come from - the same source and the first package has a "Depends" - relationship on the second. These rules are important - because copyrights must be extractable by mechanical - means.
- + +
- 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.
-
- Why "licenses" and not "copyright"? Because
- /usr/doc/copyright used to contain all the
- copyright files, plus the four common licenses GPL,
- LGPL, Artistic and BSD. Now individual copyright files
- for packages are no longer in a common directory. Once
- /usr/doc/copyright is almost empty it makes
- sense to rename "copyright" to "licenses"
-
- Why "common-licenses" and not "licenses"? Because if I - put just "licenses" I'm sure I will receive a bug report - saying "license foo is not included in the licenses - directory. They are not all the licenses, just a few - common ones. I could use /usr/share/doc/common-licenses - but I think this is too long, and, after all, the GPL - does not "document" anything, it is merely a license. + 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.- Do 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.
- 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.
-- This installed file must contain a copy of the - debian/changelog file from your Debian source tree, - and a copy of the upstream changelog file if there is one. - The debian/changelog file should be installed in - /usr/share/doc/package as - changelog.Debian.gz. If the upstream changelog - file is text formatted, it must be accessible as - /usr/share/doc/package/changelog.gz. If - the upstream changelog file is HTML formatted, it must be - accessible as - /usr/share/doc/package/changelog.html.gz. - If the upstream changelog files do not already conform to - this naming convention, then this may be achieved by either - renaming the files or adding a symbolic link at the - packaging developer's discretion.
- -- Both should be installed compressed using gzip -9, - as they will become large with time even if they start out - small.
- + This file must be an executable makefile, and contains the + package-specific recipes for compiling the package and + building binary package(s) from the source. + +- 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.
-
+ Since an interactive
+ The targets are as follows (required unless stated otherwise):
+
+ The build target should perform all the
+ configuration and compilation of the package.
+ If a package has an interactive pre-build
+ configuration routine, the Debianized source package
+ must either be built after this has taken place (so
+ that the binary package can be built without rerunning
+ the configuration) or the configuration routine
+ modified to become non-interactive. (The latter is
+ preferable if there are architecture-specific features
+ detected by the configuration routine.)
+
+ For some packages, notably ones where the same
+ source tree is compiled in different ways to produce
+ two binary packages, the build target
+ does not make much sense. For these packages it is
+ good enough to provide two (or more) targets
+ (build-a and build-b or whatever)
+ for each of the ways of building the package, and a
+ build target that does nothing. The
+ binary target will have to build the
+ package in each of the possible ways and make the
+ binary package out of each.
+
+ The build target must not do anything
+ that might require root privilege.
+
+ The build target may need to run the
+ clean target first - see below.
+
+ When a package has a configuration and build routine
+ which takes a long time, or when the makefiles are
+ poorly designed, or when build needs to
+ run clean first, it is a good idea to
+ touch build when the build process is
+ complete. This will ensure that if debian/rules
+ build is run again it will not rebuild the whole
+ program.
+ 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
+
+ The build-arch and build-indep targets
+ must not do anything that might require root privilege.
+
+ The binary target must be all that is
+ necessary for the user to build the binary package(s)
+ produced from this source package. It is
+ split into two parts:
+ binary may be (and commonly is) a target with
+ no commands which simply depends on
+ binary-arch and binary-indep.
+
+ Both binary-* targets should depend on the
+ build target, or on the appropriate
+ build-arch or build-indep target, if
+ provided, so that the package is built if it has not
+ been already. It should then create the relevant
+ binary package(s), using
+ Both the binary-arch and
+ binary-indep targets must exist.
+ If one of them has nothing to do (which will always be
+ the case if the source generates only a single binary
+ package, whether architecture-dependent or not), it
+ must still exist and must always succeed.
+
+ The binary targets must be invoked as
+ root.
+ This must undo any effects that the build
+ and binary targets may have had, except
+ that it should leave alone any output files created in
+ the parent directory by a run of a binary
+ target.
+
+ If a build file is touched at the end of
+ the build target, as suggested above, it
+ should be removed as the first action that
+ clean performs, so that running
+ build again after an interrupted
+ clean doesn't think that everything is
+ already done.
+
+ The clean target may need to be
+ invoked as root if binary has been
+ invoked since the last clean, or if
+ build has been invoked as root (since
+ build may create directories, for
+ example).
+
+ This target fetches the most recent version of the
+ original source package from a canonical archive site
+ (via FTP or WWW, for example), does any necessary
+ rearrangement to turn it into the original source
+ tar file format described below, and leaves it in the
+ current directory.
+
+ This target may be invoked in any directory, and
+ should take care to clean up any temporary files it
+ may have left.
+
+ This target is optional, but providing it if
+ possible is a good idea.
+
+ The build, binary and + clean targets must be invoked with the current + directory being the package's top-level directory. +
+ + +
+ Additional targets may exist in
+ The architectures we build on and build for are determined
+ by
+
+ where * is either BUILD for specification of
+ the build machine or HOST for specification of the
+ host machine.
+
+ Backward compatibility can be provided in the rules file
+ by setting the needed variables to suitable default
+ values; please refer to the documentation of
+
+ It is important to understand that the DEB_*_ARCH + string only determines which Debian architecture we are + building on or for. It should not be used to get the CPU + or system information; the GNU style variables should be + used for that. +
+ + + +
+ When
+ The
+ See
+ This file is not a permanent part of the source tree; it
+ is used while building packages to record which files are
+ being generated.
+ It should not exist in a shipped source package, and so it
+ (and any backup files or temporary files such as
+
+ When
+ If a package upload includes files besides the source
+ package and any binary packages whose control files were
+ made with
+ 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
+ A control file consists of one or more paragraphs of
+ fields
+ 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:
+
+ 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. +
+ ++ Except where otherwise stated, only a single line of data is + allowed and whitespace is not significant in a field body. + Whitespace must not appear inside names (of packages, + architectures, files or anything else) or version numbers, + or between the characters of multi-character version + relationships. +
+ ++ Field names are not case-sensitive, but it is usual to + capitalize the field names using mixed case as shown below. +
+ ++ Blank lines, or lines consisting only of spaces and tabs, + are not allowed within field values or between fields - that + would mean a new paragraph. +
+ +
+ The
+ The first paragraph of the control file contains information about + the source package in general. The subsequent sets each describe a + binary package that the source tree builds. +
+ +
+ The fields in the general paragraph (the first one, for the source
+ package) are:
+
+
+
+
+ The fields in the binary package paragraphs are:
+
+
+
+
+ The syntax and semantics of the fields are described below. +
+ + + +
+ These fields are used by
+ The fields here may contain variable references - their
+ values will be substituted by
+ The
+ The fields in this file are:
+
+
+
+
+ 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 .
+
+
+
+
+ The source package control file is generated by
+
+ 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:
+
+
+
+
+ This field identifies the source package name. +
+ +
+ In a main source control information, a
+ In the control file of a binary package it may be followed
+ by a version number in parentheses
+ The package maintainer's name and email address. The name + should come first, then the email address inside angle + brackets <> (in RFC822 format). +
+ ++ If the maintainer's name contains a full stop then the + whole field will not work directly as an email address due + to a misfeature in the syntax specified in RFC822; a + program using this field as an address must check for this + and correct the problem if necessary (for example by + putting the name in round brackets and moving it to the + end, and bringing the email address forward). +
++ 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. +
++ This field specifies an application area into which the package + has been classified. See . +
+ +
+ When it appears in the
+ By default,
+ This field represents how important that it is that the user + have the package installed. See . +
+ +
+ When it appears in the
+ By default,
+ The name of the binary package. +
+ ++ Package names must consist only of lower case letters + (a-z), digits (0-9), plus (+) + and minus (-) signs, and periods (.). + They must be at least two characters long and must start + with an alphanumeric character. +
++ This is the architecture string; it is a single word for + the Debian architecture. The special value all + indicates that the package is architecture-independent. +
+ +
+ In the main
+ In a
+ See for information how to get the + architecture for the build process. +
++ This is a boolean field which may occur only in the + control file of a binary package or in a per-package fields + paragraph of a main source control data file. +
+ ++ If set to yes then the package management system + will refuse to remove the package (upgrading and replacing + it is still possible). The other possible value is no, + which is the same as not having the field at all. +
++ These fields describe the package's relationships with + other packages. Their syntax and semantics are described + in .
++ 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.
+ The version number of a package. The format is: + [epoch:]upstream_version[-debian_revision] +
+ +
+ The three components here are:
+
+ This is a single (generally small) unsigned integer. It
+ may be omitted, in which case zero is assumed. If it is
+ omitted then the 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.
+
+ This is the main part of the version number. It is
+ usually the version number of the original ("upstream")
+ package from which the
+ 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
+ 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). +
++ 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: +
+ +
+
+ The lines in the extended description can have these formats: +
+ +
+
+
+ Do not use tab characters. Their effect is not predictable. +
+ ++ See for further information on this. +
+ +
+ In a
+ 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. +
+ +
+ In a
+ You should list all distributions that the
+ package should be installed into.
+
+ More information is available in the Debian Developer's
+ Reference, section "The Debian archive".
+
+ This field includes the date the package was built or last edited. +
+ +
+ The value of this field is usually extracted from the
+
+ 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 . +
+
+ 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:
+
+
+ The value of this field is usually extracted from the
+
+ This field contains the human-readable changes data, describing + the differences between the last version and the current one. +
+ ++ There should be nothing in this field before the first + newline; all the subsequent lines must be indented by at + least one space; blank lines must be represented by a line + consiting only of a space and a full stop. +
+ +
+ The value of this field is usually extracted from the
+
+ Each version's change information should be preceded by a + "title" line giving at least the version, distribution(s) + and urgency, in a human-readable way. +
+ ++ If data from several versions is being returned the entry + for the most recent version should be returned first, and + entries should be separated by the representation of a + blank line (the "title" line may also be followed by the + representation of blank line). +
++ This field is a list of binary packages. +
+ +
+ When it appears in the
+ When it appears in a
+ The syntax is a list of binary packages separated by
+ commas
+ This field appears in the control files of binary
+ packages, and in the
+ The disk space is represented in kilobytes as a simple + decimal number. +
++ This field contains a list of files with information about + each one. The exact information and syntax varies with + the context. In all cases the part of the field + contents on the same line as the field name is empty. The + remainder of the field is one line per file, each line + being indented by one space and containing a number of + sub-fields separated by spaces. +
+ +
+ In the
+ In the
+ 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
+
+ A space-separated list of bug report numbers that the upload + governed by the .changes file closes. +
++ Additional user-defined fields may be added to the + source package control file. Such fields will be + ignored, and not copied to (for example) binary or + source package control files or upload control files. +
+ ++ If you wish to add additional unsupported fields to + these output files you should use the mechanism + described here. +
+ ++ Fields in the main source control information file with + names starting X, followed by one or more of + the letters BCS and a hyphen -, will + be copied to the output files. Only the part of the + field name after the hyphen will be used in the output + file. Where the letter B is used the field + will appear in binary package control files, where the + letter S is used in source package control + files and where C is used in upload control + (.changes) files. +
+ +
+ For example, if the main source information control file
+ contains the field
+
+ It is possible to supply scripts as part of a package which + the package management system will run for you when your + package is installed, upgraded or removed. +
+ +
+ These scripts are the files
+ The package management system looks at the exit status from + these scripts. It is important that they exit with a + non-zero status if there is an error, so that the package + management system can stop its processing. For shell + scripts this means that you almost always need to + use set -e (this is usually true when writing shell + scripts, in fact). It is also important, of course, that + they don't exit with a non-zero status if everything went + well. +
+ ++ When a package is upgraded a combination of the scripts from + the old and new packages is called during the upgrade + procedure. If your scripts are going to be at all + complicated you need to be aware of this, and may need to + check the arguments to your scripts. +
+ +
+ Broadly speaking the
+ 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
+ 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.
+ 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
+ Each script should return a zero exit status for + success, or a nonzero one for failure. +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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.
+
+
+ The new package's files are unpacked, overwriting any
+ that may be on the system already, for example any
+ from the old version of the same package or from
+ another package. Backups of the old files are kept
+ temporarily, and if anything goes wrong the package
+ management system will attempt to put them back as
+ part of the error unwind.
+
+ It is an error for a package to contain files which
+ are on the system in another package, unless
+ Replaces is used (see ).
+
+
+ It is a more serious error for a package to contain a
+ plain file or other kind of non-directory where another
+ package has a directory (again, unless
+ Replaces is used). This error can be
+ overridden if desired using
+ --force-overwrite-dir, but this is not
+ advisable.
+
+ Packages which overwrite each other's files produce
+ behavior which, though deterministic, is hard for the
+ system administrator to understand. It can easily
+ lead to "missing" programs if, for example, a package
+ is installed which overwrites a file from another
+ package, and is then removed again.
+ 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
+
+
+ This is the point of no return - if
+
+ 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.
+
+ When we configure a package (this happens with dpkg
+ --install and dpkg --configure), we first
+ update any conffiles and then call:
+
+ No attempt is made to unwind after errors during + configuration. +
+ +
+ If there is no most recently configured version
+
+ Historical note: Truly ancient (pre-1997) versions of
+
+
+ All the maintainer scripts except the
+ If we aren't purging the package we stop here. Note
+ that packages which have no
+ These fields all have a uniform syntax. They are a list of + package names separated by commas. +
+ ++ In the Depends, Recommends, + Suggests, Pre-Depends, + Build-Depends and Build-Depends-Indep + control file fields of the package, which declare + dependencies on other packages, the package names listed may + also include lists of alternative package names, separated + by vertical bar (pipe) symbols |. In such a case, + if any one of the alternative packages is installed, that + part of the dependency is considered to be satisfied. +
+ ++ All of the fields except for Provides may restrict + their applicability to particular versions of each named + package. This is done in parentheses after each individual + package name; the parentheses should contain a relation from + the list below followed by a version number, in the format + described in . +
+ +
+ 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
+
+ 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
+
+ For example, a list of dependencies might appear as:
+
+ All fields that specify build-time relationships + (Build-Depends, Build-Depends-Indep, + Build-Conflicts and Build-Conflicts-Indep) + may be restricted to a certain set of architectures. This + is indicated in brackets after each individual package name and + the optional version specification. The brackets enclose a + list of Debian architecture names separated by whitespace. + Exclamation marks may be prepended to each of the names. + (It is not permitted for some names to be prepended with + exclamation marks and others not.) If the current Debian + host architecture is not in this list and there are no + exclamation marks in the list, or it is in the list with a + prepended exclamation mark, the package name and the + associated version specification are ignored completely for + the purposes of defining the relationships. +
+ +
+ For example:
+
+ 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). +
++ 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
+ 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:
+
+ 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
+
+ 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.
+
+ This field is like Depends, except that it
+ also forces
+ When a package declaring a pre-dependency is about to
+ be unpacked the pre-dependency can be
+ satisfied if the depended-on package is either fully
+ configured, or even if the depended-on
+ package(s) are only unpacked or half-configured,
+ provided that they have been configured correctly at
+ some point in the past (and not removed or partially
+ removed since). In this case, both the
+ previously-configured and currently unpacked or
+ half-configured versions must satisfy any version
+ clause in the Pre-Depends field.
+
+ When the package declaring a pre-dependency is about
+ to be configured, the pre-dependency will be
+ treated as a normal Depends, that is, it will
+ be considered satisfied only if the depended-on
+ package has been correctly configured.
+
+ Pre-Depends should be used sparingly,
+ preferably only by packages whose premature upgrade or
+ installation would hamper the ability of the system to
+ continue with any upgrade that might be in progress.
+
+ Pre-Depends are also required if the
+
+ 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. +
+
+ When one binary package declares a conflict with another
+ using a Conflicts field,
+ 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
+
+ A package will not cause a conflict merely because its + configuration files are still installed; it must be at least + half-installed. +
+ ++ A special exception is made for packages which declare a + conflict with their own package name, or with a virtual + package which they provide (see below): this does not + prevent their installation, and allows a package to conflict + with others providing a replacement for it. You use this + feature when you want the package in question to be the only + package providing some feature. +
+ +
+ A Conflicts entry should almost never have an
+ "earlier than" version clause. This would prevent
+
+ As well as the names of actual ("concrete") packages, the + package relationship fields Depends, + Recommends, Suggests, Enhances, + Pre-Depends, Conflicts, + Build-Depends, Build-Depends-Indep, + Build-Conflicts and Build-Conflicts-Indep + may mention "virtual packages". +
+ ++ A virtual package is one which appears in the + Provides control file field of another package. + The effect is as if the package(s) which provide a + particular virtual package name had been listed by name + everywhere the virtual package name appears. (See also ) +
+ +
+ 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
+
+ If a dependency or a conflict has a version number attached + then only real packages will be considered to see whether + the relationship is satisfied (or the prohibition violated, + for a conflict) - it is assumed that a real package which + provides the virtual package is not of the "right" version. + So, a Provides field may not contain version + numbers, and the version number of the concrete package + which provides a particular virtual package will not be + looked at when considering a dependency on or conflict with + the virtual package name. +
+ +
+ It is likely that the ability will be added in a future
+ release of
+ 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. +
++ 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. +
+ ++ 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
+ If a package is completely replaced in this way, so that
+
+ Replaces is a one way relationship -- you have to
+ install the replacing package after the replaced
+ package.
+
+ For this usage of Replaces, virtual packages (see + ) are not considered when looking at a + Replaces field - the packages declared as being + replaced must be mentioned by their real names. +
+ ++ Furthermore, this usage of Replaces only takes + effect when both packages are at least partially on the + system at once, so that it can only happen if they do not + conflict or if the conflict has been overridden. +
+ ++ 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:
+
+ Source packages that require certain binary packages to be + installed or absent at the time of building the package + can declare relationships to those binary packages. +
+ ++ This is done using the Build-Depends, + Build-Depends-Indep, Build-Conflicts and + Build-Conflicts-Indep control file fields. +
+ ++ Build-dependencies on "build-essential" binary packages can be + omitted. Please see for more information. +
+ +
+ The dependencies and conflicts they define must be satisfied
+ (as defined earlier for binary packages) in order to invoke
+ the targets in debian/rules, as follows:
+ 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 containing shared libraries must be constructed with + a little care to make sure that the shared library is always + available. This is especially important for packages whose + shared libraries are vitally important, such as the C library + (currently libc6). +
+ ++ Packages involving shared libraries should be split up into + several binary packages. This section mostly deals with how + this separation is to be accomplished; rules for files within + the shared library packages are in instead. +
+ +
+ The run-time shared library needs to be placed in a package called
+
+ If you have several shared libraries built from the same + source tree you may lump them all together into a single + shared library package, provided that you change all of + their sonames at once (so that you don't get filename + clashes if you try to install different versions of the + combined shared libraries package). +
+ +
+ The package should install the shared libraries under
+ their normal names. For example, the
+ Shared libraries should not be installed executable, since + the dynamic linker does not require this and trying to + execute a shared library usually results in a core dump. +
+ +
+ The run-time library package should include the symbolic link that
+
+ Any package installing shared libraries in one of the default
+ library directories of the dynamic linker (which are currently
+
+
+
+ The package must call
+ 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.
+
+ 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 another package for the runtime binaries
+ (this package might typically be named
+
+ The static library (
+ In some cases, it is acceptable for a library to be
+ available in static form only; these cases include:
+
+
+
+ The development files associated to a shared library need to be
+ placed in a package called
+
+ In case several development versions of a library exist, you may
+ need to use
+ The development package should contain a symlink for the associated
+ shared library without a version number. For example, the
+
+ 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. +
+
+ 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
+ Thus, when a package is built which contains any shared
+ libraries, it must provide a
+ In the past, the shared libraries linked to were
+ determined by calling
+ We say that a binary foo directly uses
+ a library libbar if it is explicitly linked
+ with that library (that is, it uses the flag
+ -lbar during the linking stage). Other
+ libraries that are needed by libbar are linked
+ indirectly to foo, and the dynamic
+ linker will load them automatically when it loads
+ libbar. A package should depend on
+ the libraries it directly uses, and the dependencies for
+ those libraries should automatically pull in the other
+ libraries.
+
+ Unfortunately, the
+ 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
+
+ In the following sections, we will first describe where the
+ various shlibs files are to be found, then how to
+ use
+ There are several places where shlibs files are
+ found. The following list gives them in the order in which
+ they are read by
+
+ This lists overrides for this package. Its use is
+ described below (see ).
+
+ This lists global overrides. This list is normally
+ empty. It is maintained by the local system
+ administrator.
+
+ When packages are being built, any
+
+ These are the
+ This file lists any shared libraries whose packages
+ have failed to provide correct
+
+
+ Put a call to
+ This command puts the dependency information into the
+
+ If
+ If you have multiple binary packages, you will need to call
+
+ Each
+ We will explain this by reference to the example of the
+ zlib1g package, which (at the time of writing)
+ installs the shared library
+ library-name is the name of the shared library, + in this case libz. (This must match the name part + of the soname, see below.) +
+ +
+ soname-version-number is the version part of the
+ soname of the library. The soname is the thing that must
+ exactly match for the library to be recognized by the
+ dynamic linker, and is usually of the form
+ name.so.major-version, in our
+ example, libz.so.1.
+ dependencies has the same syntax as a dependency + field in a binary package control file. It should give + details of which packages are required to satisfy a binary + built against the version of the library contained in the + package. See for details. +
+ +
+ In our example, if the first version of the zlib1g
+ package which contained a minor number of at least
+ 1.3 was 1:1.1.3-1, then the
+ shlibs entry for this library could say:
+
+ If your package provides a shared library, you should create
+ a
+ As
+ 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
+ We will assume that you are trying to package a binary
+ foo. When you try running
+
+ As soon as the maintainer of bar1 provides a
+ correct
+ 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
+
+ As mandated by the FHS, packages must not place any
+ files in
+ However, the package may create empty directories below
+
+ Note, that this applies only to directories below
+
+ Since
+ For example, the emacsen-common package could
+ contain something like
+
+ If you do create a directory in
+ However, because
+ The
+ The system-wide mail directory is
+ The Debian system can be configured to use either plain or + shadow passwords. +
+ ++ Some user ids (UIDs) and group ids (GIDs) are reserved + globally for use by certain packages. Because some + packages need to include files which are owned by these + users or groups, or need the ids compiled into binaries, + these ids must be used on any Debian system only for the + purpose for which they are allocated. This is a serious + restriction, and we should avoid getting in the way of + local administration policies. In particular, many sites + allocate users and/or local system groups starting at 100. +
+ ++ Apart from this we should have dynamically allocated ids, + which should by default be arranged in some sensible + order, but the behavior should be configurable. +
+ +
+ Packages other than base-passwd must not modify
+
+ The UID and GID numbers are divided into classes as
+ follows:
+
+ Globally allocated by the Debian project, the same
+ on every Debian system. These ids will appear in
+ the
+ 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.
+
+ 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.
+
+ Dynamically allocated user accounts. By default
+ Reserved.
+ Globally allocated by the Debian project, but only
+ created on demand. The ids are allocated centrally
+ and statically, but the actual accounts are only
+ created on users' systems on demand.
+
+ These ids are for packages which are obscure or
+ which require many statically-allocated ids. These
+ packages should check for and create the accounts in
+ Reserved.
+ User nobody. The corresponding gid refers
+ to the group nogroup.
+
+ (uid_t)(-1) == (gid_t)(-1) must
+ not be used, because it is the error return
+ sentinel value.
+
+ The
+ 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
+
+ These scripts are referenced by symbolic links in the
+
+ The names of the links all have the form
+
+ When
+ 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
+ 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
+ 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. +
+ +
+ 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
+
+ Packages that include daemons for system services should
+ place scripts in cause the configuration of the service to be
+ reloaded without actually stopping and restarting
+ the service,
+ The
+ If a service reloads its configuration automatically (as
+ in the case of
+ The
+ 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
+ Often there are some variables in the
+ To ensure that vital configurable values are always
+ available, the
+ Maintainers should use the abstraction layer provided by
+ the
+ Directly managing the /etc/rc?.d links and directly
+ invoking the
+ The program
+ You must not include any
+ By default
+ To get the default behavior for your package, put in your
+
+ This will use a default sequence number of 20. If it does
+ not matter when or in which order the
+ For more information about using update-rc.d,
+ please consult its manpage
+ The program
+ The use of
+ By default,
+ Most packages will simply need to change:
+
+ A package should register its initscript services using
+
+ For more information about using
+
+ There used to be another directory,
+ The
+
+ Complementing the above init script is a configuration
+ file
+ Another example on which you can base your
+
+ If this package is happy with the default setup from
+
+ This section describes the formats to be used for messages
+ written to standard output by the
+ 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. +
+ +
+
+
+
+ There are standard message formats for the following + situations. They should be used by the init.d + scripts. +
+ +
+ When daemons are started
+ If your script starts one or more daemons, the output
+ should look like this (a single line, no leading
+ spaces):
+
+ For example, the output of
+ This can be achieved by saying
+ When a system parameter is being set
+ If you have to set up different system parameters
+ during the system boot, you should use this format:
+
+ You can use a statement such as the following to get
+ the quotes right:
+
+ 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:
+ 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 When the configuration is reloaded
+ When a daemon is forced to reload its configuration
+ files you should use the following format:
+
+
+
+ Packages must not modify the configuration file
+
+ 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:
+
+ 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
+
+ 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.
+
+ 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
+
+ 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. +
+ ++ Menu entries should follow the current menu policy. +
+ +
+ 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. +
++ 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 invoke these handlers to + view, edit or display MIME types they don't support directly. +
+ ++ 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. +
+ +
+ 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
+
+ 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:
+
+
+ The following list explains how the different programs + should be set up to achieve this: +
+ +
+
+
+
+ This will solve the problem except for the following + cases: +
+ +
+
+
+
+ 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
+ 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:
+
+
+ Furthermore, as
+ 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:
+
+ Note that by default all installed binaries should be stripped,
+ either by using the -s flag to
+
+ 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 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.
+
+ 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. +
++ 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. +
+ ++ You must specify the gcc option -D_REENTRANT + when building a library (either static or shared) to make + the library compatible with LinuxThreads. +
+ +
+ 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
+ All installed shared libraries should be stripped with
+
+ 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
+ Packages containing shared libraries that may be linked to
+ by other packages' binaries, but which for some
+ compelling reason can not be installed in
+
+ An ever increasing number of packages are using
+
+ Packages that use
+ 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. +
++ This section has moved to . +
+
+ All command scripts, including the package maintainer
+ scripts inside the package and used by
+ In the case of Perl scripts this should be + #!/usr/bin/perl. +
+ +
+ Shell scripts (
+ The standard shell interpreter
+ You may wish to restrict your script to POSIX features when
+ possible so that it may use
+ Perl scripts should check for errors when making any + system calls, including open, print, + close, rename and system. +
+ +
+
+ Any scripts which create files in world-writeable
+ directories (e.g., in
+ The Debian base system provides the
+ 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
+ In addition, symbolic links should be specified as short as
+ possible, i.e., link targets like
+ Note that when creating a relative link using
+
+ For example, in your
+ A symbolic link pointing to a compressed file should always
+ have the same file extension as the referenced file. (For
+ example, if a file
+ Packages must not include device files in the package file + tree. +
+ +
+ If a package needs any special device files that are not
+ included in the base system, it must call
+
+ Packages must not remove any device files in the
+
+ Debian uses the serial devices
+
+
+ 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
+ Any configuration files created or used by your package
+ must reside in
+ If your package creates or uses configuration files
+ outside of
+ Configuration file handling must conform to the following
+ behavior:
+
+
+
+ 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). +
+ +
+ In order to ensure that local changes are preserved
+ correctly, no package may contain or make hard links to
+ conffiles.
+ The other way to do it is via the maintainer scripts. In
+ this case, the configuration file must not be listed as a
+ conffile and must not be part of the package
+ 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
+
+ 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
+
+ A common practice is to create a script called
+
+ These two styles of configuration file handling must
+ not be mixed, for that way lies madness:
+
+ 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,
+ The maintainer scripts must not alter a conffile + of any package, including the one the scripts + belong to. +
+ ++ 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. +
+ +
+ 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:
+
+ 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.) +
+
+ The files in
+ Therefore, if a program needs a dotfile to exist in
+ advance in
+ 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. +
+ +
+ 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
+
+ Log files should usually be named
+
+ 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
+
+ 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
+ Log files should be removed when the package is
+ purged (but not when it is only removed). This should be
+ done by the
+ 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
+ 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. +
+ ++ 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. +
+ ++ 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. +
+ ++ 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. +
+ +
+ 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
+ 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
+
+ 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
+ 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. +
+ +
+ This section is not intended as policy, but as a
+ description of the use of
+
+ 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
+ Given the above,
+ If a program needs to specify an architecture specification
+ string in some place, the following format should be
+ used: arch-os
+ 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. +
+
+ The configuration files
+ If a package requires a new entry in one of these files, the
+ maintainer should get in contact with the
+
+ The configuration file
+ If a package wants to install an example entry into
+
+ 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. +
+ +
+ The files
+ 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. +
+ ++ In addition, every program should choose a good default + editor/pager if none is selected by the user or system + administrator. +
+ +
+ 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
+ These two files are managed through the
+ 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
+ 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
+
+ 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.
+ This section describes the locations and URLs that should + be used by all web servers and web applications in the + Debian system. +
+ +
+ Access to HTML documents
+ HTML documents for a package are stored in
+
+ 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.
+ Web Document Root
+ 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
+
+ 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 mail spool is
+ 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
+ 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).
+ +
+
+ The convention of writing forward to + address in the mailbox itself is not + supported. Use a .forward file instead.
+ +
+ The
+ 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
+ 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
+
+ All the configuration files related to the NNTP (news)
+ servers and clients should be located under
+
+ There are some configuration issues that apply to a number
+ of news clients and server packages on the machine. These
+ are:
+
+
+ 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 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.
+ 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
+
+ To be an x-terminal-emulator, a program must:
+
+
+
+ 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
+
+
+ Packages that provide fonts for the X Window
+ System
+
+
+
+
+ Application defaults files must be installed in the
+ directory
+ 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
+
+ Packages using the X Window System should not be
+ configured to install files under the
+ Programs that use GNU
+ The installation of files into subdirectories
+ of
+ Packages must not provide or install files into the directories
+
+ Programs that require the non-DFSG-compliant OSF/Motif or
+ OpenMotif libraries
+ 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. +
++ Perl programs and modules should follow the current Perl policy. +
+ +
+ 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
+
+ Please refer to the "Debian Emacs Policy" for details of how to + package emacs lisp programs. +
+ +
+ The Emacs policy is available in
+
+ The permissions on
+ Each game decides on its own security policy.
+ ++ 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.)
+ +
+ 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
+ As described in the FHS, binaries of games should be
+ installed in the directory
+ You should install manual pages in
+ 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 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
+ Info documents should be installed in
+ Your package should call
+ 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
+ You should remove the entries in the
+ If
+ 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
+
+ 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
+ (
+ Packages must not require the existence of any files in
+
+
+ Former Debian releases placed all additional documentation
+ in
+ The unification of Debian documentation is being carried out + via HTML.
+ +
+ 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
+
+ Other formats such as PostScript may be provided at the + package maintainer's discretion. +
+
+ Every package must be accompanied by a verbatim copy of its
+ copyright and distribution license in the file
+
+ 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.
+ +
+ A copy of the file which will be installed in
+
+
+ Packages distributed under the UCB BSD license, the Artistic
+ license, the GNU GPL, and the GNU LGPL should refer to the
+ files
+ You should not use the copyright file as a general
+ Any examples (configurations, source files, whatever),
+ should be installed in a directory
+
+ If the purpose of a package is to provide examples, then the
+ example files may be installed into
+
+ Packages that are not Debian-native must contain a
+ compressed copy of the
+ If an upstream changelog is available, it should be accessible as
+
+ All of these files should be installed compressed using + gzip -9, as they will become large with time even + if they start out small. +
+ +
+ 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
+
+ For details about the format and contents of the Debian + changelog file, please see . +
++ 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. +
+ ++ 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. +
+ +
+
+ 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 (
+ It also documents the interaction between
+
+ 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
+ It is assumed that the reader is reasonably familiar with the
+
+ The Debian version of the FSF's GNU hello program is provided
+ as an example for people wishing to create Debian
+ packages. The Debian
+ The binary package has two main sections. The first part
+ consists of various control information files and scripts used
+ by
+ 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
+
+ All manipulation of binary package files is done by
+
+ 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
+
+ They should have the locations (relative to the root of the + directory tree you're constructing) ownerships and + permissions which you want them to have on the system when + they are installed. +
+ +
+ With current versions of
+ You need to add one special directory to the root of the
+ miniature filesystem tree you're creating:
+
+ The
+ When you've prepared the package, you should invoke:
+
+ This will build the package in
+
+ See the manpage
+ The control information portion of a binary package is a
+ collection of files with names known to
+ It is possible to put other files in the package control + area, but this is not generally a good idea (though they + will largely be ignored). +
+ +
+ Here is a brief list of the control info files supported by
+
+
+ This is the key description file used by
+
+ It is usually generated automatically from information
+ in the source package by the
+
+ These are exectuable files (usually scripts) which
+
+ It is very important to make these scripts idempotent.
+ See .
+
+ The maintainer scripts are guaranteed to run with a
+ controlling terminal and can interact with the user.
+ See .
+
+ The most important control information file used by
+
+ The binary package control files of packages built from
+ Debian sources are made by a special tool,
+
+ 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 . +
++ See . +
++ 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. +
+ ++ 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 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
+ This program is frequently used by hand, and is also
+ called from package-independent automated building scripts
+ such as
+ To unpack a package it is typically invoked with
+
+ with the
+ To create a packed source archive it is typically invoked:
+
+ This will create the
+ See also .
+
+
+ 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:
+
+ Do not PGP-sign the .changes file or the
+ source package .dsc file, respectively.
+ Invoke pgp-command instead of finding
+ pgp on the
+ When root privilege is required, invoke the command
+ root-command. root-command
+ should invoke its first argument as a command, from
+ the
+ Two types of binary-only build and upload - see
+
+ This program is usually called from
+ 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
+
+
+ It is also necessary for
+ For a package which generates only one binary package, and
+ which builds it in
+ Sources which build several binaries will typically need
+ something like:
+
+
+ This program is usually called from
+ Its arguments are executables.
+
+ In a forthcoming dpkg version,
+
+ 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.
+
+ 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.) +
+ +
+
+ For example, the
+ 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
+
+ Some packages' uploads need to include files other than + the source and binary package files. +
+ +
+
+ It is usually invoked from the binary target of
+
+ The section and priority are passed
+ unchanged into the resulting
+ This program is usually called by package-independent
+ automatic building scripts such as
+
+ It is usually called in the top level of a built source
+ tree, and when invoked with no arguments will print out a
+ straightforward
+ This program is used internally by
+
+ This program can be used manually, but is also invoked by
+ dpkg-buildpackage or
+ 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
+
+ See . +
++ See . +
+ +
+ It is recommended that the entire changelog be encoded in the
+
+ 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
+
+ It is possible to use a different format to the standard + one, by providing a parser for the format you wish to + use. +
+ +
+ 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:
+
+ If such a line exists then dpkg-parsechangelog
+ will look for the parser as
+
+ 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. +
+ +
+ The fields are:
+
+
+
+ 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. +
+ ++ For the format of the Changes field see + . +
+ ++ 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. +
+ ++ 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. +
++ See . +
+ ++ See . +
+
+ This is the canonical temporary location for the
+ construction of binary packages by the binary
+ target. The directory
+ If several binary packages are generated from the same
+ source tree it is usual to use several
+
+ Whatever
+ 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 is a compressed (with gzip -9)
+
+ 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.
+
+ All the directories in the diff must exist, except the
+
+ The
+ 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
+
+ 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 Rename the
+ Create the subdirectory Apply the diff using patch -p0. Untar the tarfile again if you want a copy of the original
+ source code alongside the Debianised version.
+ It is not possible to generate a valid Debian source archive
+ without using
+ The source package may not contain any hard links
+
+ The source packaging tools manage the changes between the
+ original and Debianised source using Adding or removing symbolic links, sockets or pipes. Changing the targets of symbolic links. Creating directories, other than Changes to the contents of binary files.
+ Removing files, directories or symlinks.
+
+ Changed text files which are missing the usual final
+ newline (either in the original or the modified
+ source tree).
+ Changing the permissions of files (other than
+
+
Changes which cause
+
+ Changes which are not represented, but which are not detected by
+
+
+
+ The
+ Many of the tools in the
+ See . +
+ +
+ It is important to note that there are several fields which
+ are optional as far as
+ See . +
+ ++ This section now contains only the fields that didn't belong + to the Policy manual. +
+ ++ These fields in Packages files give the + filename(s) of (the parts of) a package in the + distribution directories, relative to the root of the + Debian hierarchy. If the package has been split into + several parts the parts are all listed in order, separated + by spaces. +
+
+ These fields in
+ This field in
+ If a package is not installed or not configured, this
+ field in
+ This field in
+ These are still recognised by
+
+ Whether this mechanism is appropriate depends on a number of + factors, but basically there are two approaches to any + particular configuration file. +
+ +
+ The easy method is to ship a best-effort configuration in the
+ package, and use
+ The hard method is to build the configuration file from
+ scratch in the
+ A package may contain a control area file called + conffiles. This file should be a list of filenames + of configuration files needing automatic handling, separated + by newlines. The filenames should be absolute pathnames, + and the files referred to should actually exist in the + package. +
+ +
+ When a package is upgraded
+ For each file it checks to see whether the version of the + file included in the package is the same as the one that was + included in the last version of the package (the one that is + being upgraded from); it also compares the version currently + installed on the system with the one shipped with the last + version. +
+ ++ If neither the user nor the package maintainer has changed + the file, it is left alone. If one or the other has changed + their version, then the changed version is preferred - i.e., + if the user edits their file, but the package maintainer + doesn't ship a different version, the user's changes will + stay, silently, but if the maintainer ships a new version + and the user hasn't edited it the new version will be + installed (with an informative message). If both have + changed their version the user is prompted about the problem + and must resolve the differences themselves. +
+ ++ The comparisons are done by calculating the MD5 message + digests of the files, and storing the MD5 of the file as it + was included in the most recent version of the package. +
+ +
+ When a package is installed for the first time
+
+ However, note that
+ Note that a package should not modify a
+
+ For files which contain site-specific information such as
+ the hostname and networking details and so forth, it is
+ better to create the file in the package's
+
+ This will typically involve examining the state of the rest + of the system to determine values and other information, and + may involve prompting the user for some information which + can't be obtained some other way. +
+ ++ When using this method there are a couple of important + issues which should be considered: +
+ ++ If you discover a bug in the program which generates the + configuration file, or if the format of the file changes + from one version to the next, you will have to arrange for + the postinst script to do something sensible - usually this + will mean editing the installed configuration file to remove + the problem or change the syntax. You will have to do this + very carefully, since the user may have changed the file, + perhaps to fix the very problem that your script is trying + to deal with - you will have to detect these situations and + deal with them correctly. +
+ +
+ If you do go down this route it's probably a good idea to
+ make the program that generates the configuration file(s) a
+ separate program in
+ When several packages all provide different versions of the + same program or file it is useful to have the system select a + default, but to allow the system administrator to change it + and have their decisions respected. +
+ +
+ For example, there are several versions of the
+ If all the packages involved cooperate, this can be done with
+
+ Each package provides its own version under its own name, and
+ calls
+ See the manpage
+ If
+ It is possible to have
+ This can be used locally to override a package's version of a + file, or by one package to override another's version (or + provide a wrapper for it). +
+ ++ Before deciding to use a diversion, read to see if you really want a diversion + rather than several alternative versions of a program. +
+ +
+ There is a diversion list, which is read by
+ When a package wishes to divert a file from another, it should
+ call
+ The postrm has to do the reverse:
+
+ Do not attempt to divert a file which is vitally important for
+ the system's operation - when using