X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=policy.sgml;h=ae7149ff130ac8c9b8bc39ccbe62db152ed9a82f;hb=6e1b2d9c86e05355da2081276decbf3ae3fce4c2;hp=0c2470c36c16fb2c932e0efe2f90bd888bfc378d;hpb=9cb86abc7b37aab05866755f2e193a378dc13e25;p=debian%2Fdebian-policy.git
diff --git a/policy.sgml b/policy.sgml
index 0c2470c..ae7149f 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -4,41 +4,11 @@
%versiondata;
]>
Julian Gilbey Manoj Srivastava
@@ -83,17 +41,17 @@
A copy of the GNU General Public License is available as
- /usr/share/common-licenses/GPL in the Debian GNU/Linux
+
This manual also describes Debian policy as it relates to
creating Debian packages. It is not a tutorial on how to build
@@ -116,13 +73,11 @@
the behavior of the packaging system. Instead, this manual
attempts to define the interface to the package management
system that the developers have to be conversant with.
Informally, the criteria used for inclusion is that the
material meet one of the following requirements:
The material presented represents an interface to
the packaging system that is mandated for use, and
is used by, a significant number of packages, and
@@ -133,22 +88,18 @@
compatibility with these interface
definitions. (Control file and changelog file
formats are examples.)
-
If there are a number of technically viable choices
that can be made, but one needs to select one of
these options for inter-operability. The version
number format is one example.
-
+ The appendices to this manual are not necessarily normative, + either. Please see for more information. +
- In this manual, the words must, should and + In the normative part of this manual, + the words must, should and may, and the adjectives required, recommended and optional, are used to distinguish the significance of the various guidelines in @@ -173,6 +129,7 @@ may (or optional) are truly optional and adherence is left to the maintainer's discretion.
+
These classifications are roughly equivalent to the bug
severities serious (for must or
@@ -180,11 +137,13 @@
normal or important
(for should or recommended directive
violations) and wishlist (for optional
- items). Compare RFC 2119. Note, however, that these words are
- used in a different way in this document.
Much of the information presented in this manual will be useful even when building a package which is to be @@ -192,37 +151,73 @@ only.
+
- The current version of this document is always accessible
- from the Debian FTP server
- 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 debian-policy package also includes the file
- upgrading-checklist.txt which indicates policy
+ The
- As the Debian GNU/Linux system is continuously evolving this - manual does so too. -
+ Originally called "Debian GNU/Linux Policy Manual", this + manual was initially written in 1996 by Ian Jackson. + It was revised on November 27th, 1996 by David A. Morris. + Christian Schwarz added new sections on March 15th, 1997, + and reworked/restructured it in April-July 1997. + Christoph Lameter contributed the "Web Standard". + Julian Gilbey largely restructured it in 2001. + + +
+ Since September 1998, the responsibility for the contents of
+ this document lies on the
While the authors of this document have tried hard to avoid
typos and other errors, these do still occur. If you discover
@@ -232,105 +227,137 @@
+ 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 in 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 (currently well over 6000), they are split into + them (currently well over 15000), they are split into sections and given priorities to simplify the handling of them.
+The effort of the Debian project is to build a free operating system, but not every package we want to make accessible is free in our sense (see the Debian Free Software Guidelines, below), or may be imported/exported without - restrictions. Thus, the archive is split into the sections - main, non-free, contrib, - non-US/main, non-US/non-free, and - non-US/contrib. The sections are explained in detail - below. + restrictions. Thus, the archive is split into the distribution + areas or categories based on their licenses and other restrictions.
- The main and the non-US/main sections
- together form the Debian GNU/Linux distribution.
+ The aims of this are:
+
+
+
- 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.
+ The main category forms the + Debian GNU/Linux distribution. + -- The aims of this section are: +
+ Packages in the other distribution areas (contrib, + non-free) 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 allow us to make as much software available as we - can,
-to allow us to encourage everyone to write free - software, and
-to allow us to make it easy for people to produce - CD-ROMs of our system without violating any licenses, - import/export restrictions, or any other laws.
-
- The Debian Free Software Guidelines (DFSG) form our
- definition of `free software'. These are:
+
+ The Debian Free Software Guidelines (DFSG) form our
+ definition of "free software". These are:
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''
+ license allows the distribution of "patch files"
with the source code for the purpose of modifying the
program at build time. The license must explicitly
permit distribution of software built from modified
@@ -339,41 +366,33 @@
original software. (This is a compromise. The Debian
Project 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
@@ -382,373 +401,299 @@
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.
-
- Every package in main and non-US/main - must comply with the DFSG (Debian Free Software - Guidelines).
+ Every package in main must comply with the DFSG + (Debian Free Software Guidelines). +
In addition, the packages in main
must not require a package outside of main
for compilation or execution (thus, the package must
not declare a "Depends", "Recommends", or
"Build-Depends" relationship on a non-main
package),
-
must not be so buggy that we refuse to support them,
and
-
- must meet all policy requirements presented in this
- manual.
-
-
- Similarly, the packages in non-US/main
-
- must not require a package outside of main
- or non-US/main for compilation or
- execution,
-
- must not be so buggy that we refuse to support them,
-
must meet all policy requirements presented in this
manual.
-
-
- Every package in contrib and - non-US/contrib must comply with the DFSG. + Every package in contrib must comply with the DFSG.
- In addition, the packages in contrib and
- non-US/contrib
+ In addition, the packages in contrib
must not be so buggy that we refuse to support them,
and
-
must meet all policy requirements presented in this
manual.
-
- Furthermore, packages in contrib must not require - a package in a non-US section for compilation or - execution. -
Examples of packages which would be included in
- contrib or non-US/contrib are:
+ contrib are:
free packages which require contrib,
non-free packages or packages which are not
in our archive at all for compilation or execution,
and
-
wrapper packages or other sorts of free accessories for
non-free programs.
-
- Packages must be placed in non-free or - non-US/non-free if they are not compliant with - the DFSG or are encumbered by patents or other legal - issues that make their distribution problematic. + Packages must be placed in non-free 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
+ In addition, the packages in non-free
must not be so buggy that we refuse to support them,
and
-
must meet all policy requirements presented in this
- manual that it is possible for them to meet.
+ manual that it is possible for them to meet.
+
- Some programs with cryptographic program code need to be - stored on the non-US server because of United - States export restrictions. Such programs must be - distributed in the appropriate non-US section, - either non-US/main, non-US/contrib or - non-US/non-free. -
-- This applies only to packages which contain cryptographic - code. A package containing a program with an interface to - a cryptographic program or a program that's dynamically - linked against a cryptographic library should not be - distributed via the non-US server if it is - capable of running without the cryptographic library or - program. -
-- Every package must be accompanied by a verbatim copy of - its copyright and distribution license in the file - /usr/share/doc/package/copyright - (see for further details). -
-
- We reserve the right to restrict files from being included
- anywhere in our archives if
-
+
-
+ 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
+
+
+
+
+
- Programs whose authors encourage the user to make - donations are fine for the main distribution, provided - that the authors do not claim that not donating is - immoral, unethical, illegal or something similar; in such - a case they must go in non-free.
++ Programs whose authors encourage the user to make + donations are fine for the main distribution, provided + that the authors do not claim that not donating is + immoral, unethical, illegal or something similar; in such + a case they must go in non-free. +
-- Packages whose copyright permission notices (or patent - problems) do not even allow redistribution of binaries - only, and where no special permission has been obtained, - must not be placed on the Debian FTP site and its mirrors - at all.
++ Packages whose copyright permission notices (or patent + problems) do not even allow redistribution of binaries + only, and where no special permission has been obtained, + must not be placed on the Debian FTP site and its mirrors + at all. +
-- Note that under international copyright law (this applies - in the United States, too), no distribution or - modification of a work is allowed without an explicit - notice saying so. Therefore a program without a copyright - notice is copyrighted and you may not do anything - to it without risking being sued! Likewise if a program - has a copyright notice but no statement saying what is - permitted then nothing is permitted.
++ Note that under international copyright law (this applies + in the United States, too), no distribution or + modification of a work is allowed without an explicit + notice saying so. Therefore a program without a copyright + notice is copyrighted and you may not do anything + to it without risking being sued! Likewise if a program + has a copyright notice but no statement saying what is + permitted then nothing is permitted. +
-- Many authors are unaware of the problems that restrictive - copyrights (or lack of copyright notices) can cause for - the users of their supposedly-free software. It is often - worthwhile contacting such authors diplomatically to ask - them to modify their license terms. However, this can be a - politically difficult thing to do and you should ask for - advice on the debian-legal mailing list first, as - explained below. -
++ Many authors are unaware of the problems that restrictive + copyrights (or lack of copyright notices) can cause for + the users of their supposedly-free software. It is often + worthwhile contacting such authors diplomatically to ask + them to modify their license terms. However, this can be a + politically difficult thing to do and you should ask for + advice on the debian-legal mailing list first, as + explained below. +
-
- When in doubt about a copyright, send mail to
-
+ When in doubt about a copyright, send mail to
+
- The packages in the sections main, - contrib and non-free are grouped further - into subsections to simplify handling. -
+
- The section and subsection for each package should be
- specified in the package's Section control
- record. However, the maintainer of the Debian archive
- may override this selection to ensure the consistency of
- the Debian distribution. The Section field
- should be of the form:
-
- subsection if the package is in the
- main section,
-
- section/subsection if the package is in
- the contrib or non-free section,
- and
-
- non-US, non-US/contrib or
- non-US/non-free if the package is in
- non-US/main, non-US/contrib or
- non-US/non-free respectively.
-
-
-
+ The packages in the categories main, + contrib and non-free are grouped further + into sections to simplify handling. +
-- The Debian archive maintainers provide the authoritative - list of subsections. At present, they are: - admin, base, comm, - contrib, devel, doc, - editors, electronics, games, - graphics, hamradio, - interpreters, libs, mail, - math, misc, net, news, - non-US, non-free, oldlibs, - otherosfs, science, shells, - sound, tex, text, - utils, web, x11. -
- -
+ The category and section 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:
+
+
+
+ The Debian archive maintainers provide the authoritative + list of sections. At present, they are: + admin, comm, + devel, doc, + editors, electronics, embedded, + games, gnome, graphics, + hamradio, interpreters, kde, + libs, libdevel, mail, + math, misc, net, news, + oldlibs, + otherosfs, perl, python, + science, shells, + sound, tex, text, + utils, web, x11. +
+Each package should have a priority value, which is - included in the package's control record. This - information is used by the Debian package management tools - to separate high-priority packages from less-important - packages.
+ included in the package's control record + (see ). + This information is used by the Debian package management tools to + separate high-priority packages from less-important packages. +
- The following priority levels are recognised by the
+ The following priority levels are recognized by the
Debian package management tools.
Packages which are necessary for the proper
- functioning of the system. You must not remove these
- packages or your system may become totally broken and
- you may not even be able to use
Important programs, including those which one would
expect to find on any Unix-like system. If the
expectation is that an experienced Unix person who
- found it missing would say `What on earth is going on,
- where is
This is an important criterion because we are
trying to produce, amongst other things, a free
Unix.
-
These packages provide a reasonably small but not too
limited character-mode system. This is what will be
installed by default if the user doesn't select anything
else. It doesn't include many large applications.
- .
(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
@@ -778,19 +720,17 @@
and includes the X Window System, a full TeX
distribution, and many applications. Note that
optional packages should not conflict with each other.
-
This contains all packages that conflict with others
with required, important, standard or optional
priorities, or are only likely to be useful if you
- already know what they are or have specialised
+ already know what they are or have specialized
requirements.
-
Packages must not depend on packages with lower priority @@ -800,1087 +740,964 @@
+ 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. +
+ ++ The package name is included in the control field + Package, the format of which is described + in . + The package name is also included as a part of the file name + of the .deb file. +
+
- The Debian GNU/Linux distribution is based on the Debian
- package management system, called
+ The package management system imposes an ordering on version + numbers, so that it can tell whether packages are being up- or + downgraded and so that package system front end applications + can tell whether a package it finds available is newer than + the one installed on the system. The version number format + has the most significant parts (as far as comparison is + concerned) at the beginning. +
-+ If an upstream package has problematic version numbers they + should be converted to a sane form for use in the + Version field. +
-- Every package must have a name that's unique within the Debian - archive.
+- Package names must consist of lower case letters - (a-z), digits (0-9), plus (+) - and minus (-) signs, and periods (.). - They must be at least two characters long and must contain - at least one letter. + In general, Debian packages should use the same version + numbers as the upstream sources.
- The package name is part of the file name of the - .deb file and is included in the control field - information. + However, in some cases where the upstream version number is + based on a date (e.g., a development "snapshot" release) the + package management system cannot handle these version + numbers without epochs. For example, dpkg will consider + "96May01" to be greater than "96Dec24".
-- Every package must have a Debian maintainer (the - maintainer may be one person or a group of people - reachable from a common email address, such as a mailing - list). The maintainer is responsible for ensuring that - the package is placed in the appropriate distributions. +
+ To prevent having to use epochs for every new upstream + version, the date based portion of the version number + should be changed to the following format in such cases: + "19960501", "19961224". It is up to the maintainer whether + they want to bother the upstream maintainer to change + the version numbers upstream, too.
- The maintainer must be specified in the - Maintainer control field with their correct name - and a working email address. If one person maintains - several packages, he/she should try to avoid having - different forms of their name and email address in - the Maintainer fields of those packages. + Note that other version formats based on dates which are + parsed correctly by the package management system should + not be changed.
- If the maintainer of a package quits from the Debian
- project, "Debian QA Group"
-
- The detailed procedure for doing this gracefully can
- be found in the Debian Developer's Reference, either
- in the developers-reference package, or on
- the Debian FTP server
-
+ Every package must have a Debian maintainer (the + maintainer may be one person or a group of people + reachable from a common email address, such as a mailing + list). The maintainer is responsible for ensuring that + the package is placed in the appropriate distributions. +
+ ++ The maintainer must be specified in the + Maintainer control field with their correct name + and a working email address. If one person maintains + several packages, they should try to avoid having + different forms of their name and email address in + the Maintainer fields of those packages. +
+ ++ The format of the Maintainer control field is + described in . +
+ +
+ If the maintainer of a package quits from the Debian
+ project, "Debian QA Group"
+
+ Every Debian package must have an extended description + stored in the appropriate field of the control record. + The technical information about the format of the + Description field is in . +
+ ++ The description should describe the package (the program) to a + user (system administrator) who has never met it before so that + they have enough information to decide whether they want to + install it. This description should not just be copied verbatim + from the program's documentation. +
+ ++ Put important information first, both in the synopsis and + extended description. Sometimes only the first part of the + synopsis or of the description will be displayed. You can + assume that there will usually be a way to see the whole + extended description. +
+ ++ The description should also give information about the + significant dependencies and conflicts between this package + and others, so that the user knows why these dependencies and + conflicts have been declared. +
+ ++ Instructions for configuring or using the package should + not be included (that is what installation scripts, + manual pages, info files, etc., are for). Copyright + statements and other administrivia should not be included + either (that is what the copyright file is for). +
+ +- Every Debian package must have an extended description - stored in the appropriate field of the control record.
+ The single line synopsis should be kept brief - certainly + under 80 characters. +- The description should be written so that it gives the - system administrator enough information to decide whether - to install the package. This description should not just - be copied verbatim from the program's documentation. - Instructions for configuring or using the package should - not be included (that is what installation scripts, - manual pages, info files, etc., are for). Copyright - statements and other administrivia should not be included - either (that is what the copyright file is for). + Do not include the package name in the synopsis line. The + display software knows how to display this already, and you + do not need to state it. Remember that in many situations + the user may only see the synopsis line - make it as + informative as you can.
-- Every package must specify the dependency information - about other packages that are required for the first to - work correctly.
+ Do not try to continue the single line synopsis into the + extended description. This will not work correctly when + the full description is displayed, and makes no sense + where only the summary (the single line synopsis) is + available. +- For example, a dependency entry must be provided for any - shared libraries required by a dynamically-linked executable - binary in a package.
+ The extended description should describe what the package + does and how it relates to the rest of the system (in terms + of, for example, which subsystem it is which part of). +- Packages are not required to declare any dependencies they - have on other packages which are marked Essential - (see below), and should not do so unless they depend on a - particular version of that package.
+ The description field needs to make sense to anyone, even + people who have no idea about any of the things the + package deals with.- 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.
+ Every package must specify the dependency information + about other packages that are required for the first to + work correctly. +
-- Sometimes, there are several packages which offer - more-or-less the same functionality. In this case, it's - useful to define a virtual package whose name - describes that common functionality. (The virtual - packages only exist logically, not physically; that's why - they are called virtual.) The packages with this - particular function will then provide the virtual - package. Thus, any other package requiring that function - can simply depend on the virtual package without having to - specify all possible packages individually.
++ For example, a dependency entry must be provided for any + shared libraries required by a dynamically-linked executable + binary in a package. +
-- All packages should use virtual package names where - appropriate, and arrange to create new ones if necessary. - They should not use virtual package names (except privately, - amongst a cooperating group of packages) unless they have - been agreed upon and appear in the list of virtual package - names.
+
+ 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.
+ Essential is defined as the minimal set of functionality
+ that must be available and usable on the system even
+ when packages are in an unconfigured (but unpacked)
+ state. This is needed to avoid unresolvable dependency
+ loops on upgrade. If packages add unnecessary
+ dependencies on packages in this set, the chances that
+ there will be an unresolvable
+ dependency loop caused by forcing these Essential
+ packages to be configured first before they need to be
+ is greatly increased. It also increases the chances
+ that frontends will be unable to
+ calculate an upgrade path, even if one
+ exists.
+
+ Also, it's pretty unlikely that functionality from
+ Essential shall ever be removed (which is one reason why
+ care must be taken before adding to the Essential
+ packages set), but packages have been removed
+ from the Essential set when the functionality moved to a
+ different package. So depending on these packages
+ just in case they stop being essential does way
+ more harm than good.
+
- The latest version of the authoritative list of virtual
- package names can be found on
-
+ 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 packages included in the base section have a - special function. They form a minimum subset of the Debian - GNU/Linux system that is installed before everything else - on a new system. Thus, only very few packages are allowed - to go into the base section to keep the required - disk usage very small.
+- Most of these packages will have the priority value - required or at least important, and many - of them will be tagged essential (see below).
++ Sometimes, there are several packages which offer + more-or-less the same functionality. In this case, it's + useful to define a virtual package whose name + describes that common functionality. (The virtual + packages only exist logically, not physically; that's why + they are called virtual.) The packages with this + particular function will then provide the virtual + package. Thus, any other package requiring that function + can simply depend on the virtual package without having to + specify all possible packages individually. +
-- You must not place any packages into the base - section before this has been discussed on the - debian-devel mailing list and a consensus about - doing that has been reached.
++ All packages should use virtual package names where + appropriate, and arrange to create new ones if necessary. + They should not use virtual package names (except privately, + amongst a cooperating group of packages) unless they have + been agreed upon and appear in the list of virtual package + names. (See also ) +
+
+ The latest version of the authoritative list of virtual
+ package names can be found in the debian-policy package.
+ It is also available from the Debian web mirrors at
+
+ The procedure for updating the list is described in the preface + to the list. +
-- Some packages are tagged essential. (They have - Essential: yes in their package control record.) - This flag is used for packages that are essential - for a system.
+
- Since these packages cannot be easily removed (one has to
- specify an extra force option to
-
- Since dpkg will not prevent upgrading of other packages - while an essential package is in an unconfigured +
+ The base system is a minimum subset of the Debian + GNU/Linux system that is installed before everything else + on a new system. Only very few packages are allowed to form + part of the base system, in order to keep the required disk + usage very small. +
+ ++ The base system consists of all those packages with priority + required or important. Many of them will + be tagged essential (see below). +
++ Some packages are tagged essential for a system + using the Essential control file field. + The format of the Essential control field is + described in . +
+ +
+ Since these packages cannot be easily removed (one has to
+ specify an extra force option to
+
+ Since dpkg will not prevent upgrading of other packages + while an essential package is in an unconfigured state, all essential packages must supply all of their core functionality even when unconfigured. If the package cannot satisfy this requirement it must not be tagged as essential, and any packages depending on this package must instead have explicit dependency fields as appropriate. -
+ -- You must not tag any packages essential before - this has been discussed on the debian-devel - mailing list and a consensus about doing that has been - reached. -
- ++ You must not tag any packages essential before + this has been discussed on the debian-devel + mailing list and a consensus about doing that has been + reached. +
+
- The package installation scripts should avoid producing
- output which it is unnecessary for the user to see and
- should rely on
+ The package installation scripts should avoid producing
+ output which is unnecessary for the user to see and
+ should rely on
- Errors which occur during the execution of an installation - script must be checked and the installation must not - continue after an error. -
++ 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. -
++ Note that in general applies to package + maintainer scripts, too. +
+ +
+ You should not use
+ All packages which supply an instance of a common command
+ name (or, in general, filename) should generally use
+
- You should not use dpkg-divert on a file
- belonging to another package without consulting the
- maintainer of that package first.
+ Package maintainer scripts may prompt the user if
+ necessary. Prompting should be done by communicating
+ through a program, such as
- 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 may be accomplished by hand, or by
- communicating with a program, such as
-
- 4% of Debian packages [see
- With this increasing number of packages using
-
- Packages which use the Debian Configuration management
- specification may contain an additional
-
+
+ Packages which use the Debian Configuration management
+ specification may contain an additional
+
- Packages should try to minimize the amount of prompting
- they need to do, and they should ensure that the user
- will only ever be asked each question once. This means
- that packages should try to use appropriate shared
- configuration files (such as /etc/papersize and
- /etc/news/server), and shared
-
- 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
- In the source package's Standards-Version control
- field, you should specify the most recent version number
- of this policy document with which your package complied
- when it was last updated. The current version number is
- &version;.
+ Packages which use the Debian Configuration management
+ specification must allow for translation of their messages
+ by using a gettext-based system such as the one provided by
+ the
- This information may be used to file bug reports
- automatically if your package becomes too much out of
- date.
+ 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
- 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.
+ 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
- Thus only the first three components of the policy version
- are significant in the Standards-Version control
- field, and so either these three components or the all
- four components may be specified.
- In the past, people specified the full version number
- in the Standards-Version field, for example `2.3.0.0'.
- Since minor patch-level changes don't introduce new
- policy, it was thought it would be better to relax
- policy and only require the first 3 components to be
- specified, in this example `2.3.0'. All four
- components may still be used if someone wishes to do
- so.
-
- You should regularly, and especially if your package has
- become out of date, check for the newest Policy Manual
- available and update your package, if necessary. When your
- package complies with the new standards you should update the
- Standards-Version source package field and
- release it.
- See the file upgrading-checklist for
- information about policy which has changed between
- different versions of this document.
-
- Source packages should specify which binary packages they - require to be installed or not to be installed in order to - build correctly. For example, if building a package - requires a certain compiler, then the compiler should be - specified as a build-time dependency. -
-
- It is not necessary to explicitly specify build-time
- relationships on a minimal set of packages that are always
- needed to compile, link and put in a Debian package a
- standard "Hello World!" program written in C or C++. The
- required packages are called build-essential, and
- an informational list can be found in
- /usr/share/doc/build-essential/list (which is
- contained in the build-essential
- package). Rationale:
- This allows maintaining the list separately
- from the policy documents (the list does not
- need the kind of control that the policy
- documents do).
-
+ Source packages should specify the most recent version number
+ of this policy document with which your package complied
+ when it was last updated.
+
+ This information may be used to file bug reports
+ automatically if your package becomes too much out of date.
+
+ The version is specified in the Standards-Version
+ control field.
+ The format of the Standards-Version field is
+ described in .
+
+ You should regularly, and especially if your package has
+ become out of date, check for the newest Policy Manual
+ available and update your package, if necessary. When your
+ package complies with the new standards you should update the
+ Standards-Version source package field and
+ release it.
+ Source packages should specify which binary packages they
+ require to be installed or not to be installed in order to
+ build correctly. For example, if building a package
+ requires a certain compiler, then the compiler should be
+ specified as a build-time dependency.
+
+ It is not necessary to explicitly specify build-time
+ relationships on a minimal set of packages that are always
+ needed to compile, link and put in a Debian package a
+ standard "Hello World!" program written in C or C++. The
+ required packages are called build-essential, and
+ an informational list can be found in
+
Having a separate package allows one to install
the build-essential packages on a machine, as
- well as allowing other packages such as task
- packages to require installation of the
- build-essential packages using the depends
- relation.
-
The separate package allows bug reports against
the list to be categorized separately from
the policy management process in the BTS.
-
-
+
-
- When specifying the set of build-time dependencies, one
- should list only those packages explicitly required by the
- build. It is not necessary to list packages which are
- required merely because some other package in the list of
- build-time dependencies depends on them.
+
+ When specifying the set of build-time dependencies, one
+ should list only those packages explicitly required by the
+ build. It is not necessary to list packages which are
+ required merely because some other package in the list of
+ build-time dependencies depends on them.
- If build-time dependencies are specified, it must be - possible to build the package and produce working binaries - on a system with only essential and build-essential - packages installed and also those required to satisfy the - build-time relationships (including any implied - relationships). In particular, this means that version - clauses should be used rigorously in build-time - relationships so that one cannot produce bad or - inconsistently configured packages when the relationships - are properly satisfied. -
- -- If changes to the source code are made that are not - specific to the needs of the Debian system, they should be - sent to the upstream authors in whatever form they prefer - so as to be included in the upstream version of the - package.
- -
- If you need to configure the package differently for
- Debian or for Linux, and the upstream source doesn't
- provide a way to do so, you should add such configuration
- facilities (for example, a new
- You should make sure that the
- If you need to edit a
+ If build-time dependencies are specified, it must be + possible to build the package and produce working binaries + on a system with only essential and build-essential + packages installed and also those required to satisfy the + build-time relationships (including any implied + relationships). In particular, this means that version + clauses should be used rigorously in build-time + relationships so that one cannot produce bad or + inconsistently configured packages when the relationships + are properly satisfied. +
-- You should document your changes and updates to the source - package properly in the debian/changelog file. (Note - that mistakes in changelogs are usually best rectified by - making a new changelog entry rather than "rewriting history" - by editing old changelog entries.)
++ explains the technical details. +
+ -
- In non-experimental packages you must use a format for
- debian/changelog which is supported by the most
- recent released version of
- If you wish to use an alternative format, you may do
- so as long as you include a parser for it in your
- source package. The parser must have an API
- compatible with that expected by
-
+ If changes to the source code are made that are not + specific to the needs of the Debian system, they should be + sent to the upstream authors in whatever form they prefer + so as to be included in the upstream version of the + package. +
-
+ If you need to configure the package differently for
+ Debian or for Linux, and the upstream source doesn't
+ provide a way to do so, you should add such configuration
+ facilities (for example, a new
- When
+ You should make sure that the
- Every time you put more than one shell command (this - includes using a loop) in a makefile command you - must make sure that errors are trapped. For - simple compound commands, such as changing directory and - then running a program, using && rather - than semicolon as a command separator is sufficient. For - more complex commands including most loops and - conditionals you should include a separate set -e - command at the start of every makefile command that's - actually one of these miniature shell scripts.
+ If you need to edit a
+ 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 include file <varargs.h> is - provided to support end-users compiling very old software; - the library libtermcap is provided to support the - execution of software which has been linked against it - (either old programs or those such as Netscape which are - only available in binary form).
++ +
-- Debian packages should be patched to use - <stdarg.h> and ncurses - instead. -
-
+ The format of the
+ That format is a series of entries like this: -
- Many of the tools in the package management suite manipulate
- data represented in a common format, known as control
- data. The data is often stored in control
- files. Binary and source packages have control files,
- and the .changes files which control the installation
- of uploaded files are also in control file format.
-
+ package and version are the source + package name and version number. +
- A control file consists of one or more paragraphs of fields.
- The paragraphs are separated by blank lines. Some control
- files allow only one paragraph; others allow several, in
- which case each paragraph usually refers to a different
- package. (For example, in source packages, the first
- paragraph refers to the source package, and later paragraphs
- refer to binary packages generated from the source.)
+ distribution(s) lists the distributions where
+ this version should be installed when it is uploaded - it
+ is copied to the Distribution field in the
+
- 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 - tab. Any trailing spaces or tabs at the end of individual - lines of a field value are ignored. + 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.
- 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.
+ If this upload resolves bugs recorded in the Bug Tracking
+ System (BTS), they may be automatically closed on the
+ inclusion of this package into the Debian archive by
+ including the string: closes: Bug#nnnnn
+ in the change details.
- Field names are not case-sensitive, but it is usual to - capitalize the field names using mixed case as shown below. + The maintainer name and email address used in the changelog + should be the details of the person uploading this + version. They are not necessarily those of the + usual package maintainer. The information here will be + copied to the Changed-By field in the + .changes file (see ), + and then later used to send an acknowledgement when the + upload has been installed.
- 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 date should be in RFC822 format
+ 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. +
-- This list here is not supposed to be exhaustive. Most fields - are dealt with elsewhere in this document. + For more information on placement of the changelog files + within binary packages, please see .
-
- The name of the binary package. Package names consist of
- the alphanumerics and + - .
- (plus, minus and full stop).
+ In non-experimental packages you must use a format for
+
- They must be at least two characters long and must start - with an alphanumeric character and not be all digits. The - use of lowercase package names is strongly recommended - unless the package you're building (or referring to, in - other fields) is already using uppercase.
+ 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
+ Every package must be accompanied by a verbatim copy of
+ its copyright and distribution license in the file
+
+ When
- This lists the source or binary package's version number - - see . -
++ Every time you put more than one shell command (this + includes using a loop) in a makefile command you + must make sure that errors are trapped. For + simple compound commands, such as changing directory and + then running a program, using && rather + than semicolon as a command separator is sufficient. For + more complex commands including most loops and + conditionals you should include a separate set -e + command at the start of every makefile command that's + actually one of these miniature shell scripts. +
+
+ Maintainers should preserve the modification times of the
+ upstream source files in a package, as far as is reasonably
+ possible.
- The most recent version of the standards (the policy - manual and associated texts) with which the package - complies. This is updated manually when editing the - source package to conform to newer standards; it can - sometimes be used to tell when a package needs attention. - Its format is described above; see - . -
-
+ The source package may not contain any hard links
+ This is not currently detected when building source
+ packages, but only when extracting
+ them.
+
+ Hard links may be permitted at some point in the
+ future, but would require a fair amount of
+ work.
+
- In a .changes file or parsed changelog output
- this contains the (space-separated) name(s) of the
- distribution(s) where this version of the package should
- be installed. Valid distributions are determined by the
- archive maintainers.
- This is the current `released' version of Debian
- GNU/Linux. Once the distribution is
- stable only security fixes and other
- major bug fixes are allowed. When changes are
- made to this distribution, the release number is
- increased (for example: 2.2r1 becomes 2.2r2 then
- 2.2r3, etc).
-
- This distribution value refers to the
- developmental part of the Debian
- distribution tree. New packages, new upstream
- versions of packages and bug fixes go into the
- unstable directory tree. Download from
- this distribution at your own risk.
-
- This distribution value refers to the
- testing part of the Debian distribution
- tree. It receives its packages from the
- unstable distribution after a short time lag to
- ensure that there are no major issues with the
- unstable packages. It is less prone to breakage
- than unstable, but still risky. It is not
- possible to upload packages directly to
- testing.
-
- From time to time, the testing
- distribution enters a state of `code-freeze' in
- anticipation of release as a stable
- version. During this period of testing only
- fixes for existing or newly-discovered bugs will
- be allowed. The exact details of this stage are
- determined by the Release Manager.
-
- The packages with this distribution value are
- deemed by their maintainers to be high
- risk. Oftentimes they represent early beta or
- developmental packages from various sources that
- the maintainers want people to try, but are not
- ready to be a part of the other parts of the
- Debian distribution tree. Download at your own
- risk.
-
- Every package has a version number recorded in its - Version control file field. -
- -- The package management system imposes an ordering on version - numbers, so that it can tell whether packages are being up- or - downgraded and so that package system front end applications - can tell whether a package it finds available is newer than - the one installed on the system. The version number format - has the most significant parts (as far as comparison is - concerned) at the beginning. -
- -- The version number format is: - [epoch:]upstream_version[-debian_revision] -
- -
- The three components here are:
-
- 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 .deb file has been made,
- if this is applicable. Usually this will be in the same
- format as that specified by the upstream author(s);
- however, it may need to be reformatted to fit into the
- package management system's format and comparison
- scheme.
-
- The comparison behavior of the package management system
- with respect to the upstream_version is
- described below. The upstream_version
- portion of the version number is mandatory.
-
- The upstream_version may contain only
- alphanumerics Alphanumerics are A-Za-z0-9 only.
- This part of the version number specifies the version of
- the Debian package based on the upstream version. It
- may contain only alphanumerics and the characters
- + and . (plus and full stop) and is
- compared in the same way as the
- upstream_version is.
-
- It is optional; if it isn't present then the
- upstream_version may not contain a hyphen.
- This format represents the case where a piece of
- software was written specifically to be turned into a
- Debian package, and so there is only one `debianization'
- of it and therefore no revision indication is required.
-
- It is conventional to restart the
- debian_revision at 1 each time the
- upstream_version is increased.
-
- The package management system will break the version
- number apart at the last hyphen in the string (if there
- is one) to determine the upstream_version and
- debian_revision. The absence of a
- debian_revision compares earlier than the
- presence of one (but note that the
- debian_revision is the least significant part
- of the version number).
-
- The upstream_version and debian_revision - parts are compared by the package management system using the - same algorithm: -
- -- The strings are compared from left to right. -
- -- First the initial part of each string consisting entirely of - non-digit characters is determined. These two parts (one of - which may be empty) are compared lexically. If a difference - is found it is returned. The lexical comparison is a - comparison of ASCII values modified so that all the letters - sort earlier than all the non-letters. -
- -- Then the initial part of the remainder of each string which - consists entirely of digit characters is determined. The - numerical values of these two parts are compared, and any - difference found is returned as the result of the comparison. - For these purposes an empty string (which can only occur at - the end of one or both version strings being compared) counts - as zero. -
- -- These two steps (comparing and removing initial non-digit - strings and initial digit strings) are repeated until a - difference is found or both strings are exhausted. -
- -- Note that the purpose of epochs is to allow us to leave behind - mistakes in version numbering, and to cope with situations - where the version numbering scheme changes. It is - not intended to cope with version numbers containing - strings of letters which the package management system cannot - interpret (such as ALPHA or pre-), or with - silly orderings (the author of this manual has heard of a - package whose versions went 1.1, 1.2, - 1.3, 1, 2.1, 2.2, - 2 and so forth). -
- -- If an upstream package has problematic version numbers they - should be converted to a sane form for use in the - Version field. -
- -- 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.
-
- Maintainers should preserve the modification times of the
- upstream source files in a package, as far as is reasonably
- possible.
- The rationale is that there is some information conveyed
- by knowing the age of the file, for example, you could
- recognize that some documentation is very old by looking
- at the modification time, so it would be nice if the
- modification time of the upstream source would be
- preserved.
-
- 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. -
++ This file must be an executable makefile, and contains the + package-specific recipes for compiling the package and + building binary package(s) from the source. +
It must start with the line #!/usr/bin/make -f, @@ -1889,7 +1706,7 @@ Package: libc6
- Since an interactive debian/rules script makes it
+ Since an interactive
- The required and optional targets are as follows:
+ The targets are as follows (required unless stated otherwise):
- The build target should perform all
- non-interactive configuration and compilation of the
- package. If a package has an interactive pre-build
+ The build target should perform all the
+ configuration and compilation of the package.
+ If a package has an interactive pre-build
configuration routine, the Debianized source package
must either be built after this has taken place (so
that the binary package can be built without rerunning
@@ -1953,7 +1769,6 @@ Package: libc6
complete. This will ensure that if debian/rules
build is run again it will not rebuild the whole
program.
Another common way to do this is for build
to depend on
+ 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. All of these
- targets are required to be non-interactive. It is
+ produced from this source package. It is
split into two parts:
The binary targets must be invoked as
root.
The
@@ -2075,6 +1926,19 @@ Package: libc6 possible is a good idea.
+ ++ This target performs whatever additional actions are + required to make the source ready for editing (unpacking + additional upstream archives, applying patches, etc.). + It is recommended to be implemented for any package where + dpkg-source -x does not result in source ready + for additional modification. See + . +
+@@ -2085,7 +1949,7 @@ Package: libc6
- Additional targets may exist in debian/rules,
+ Additional targets may exist in
The architectures we build on and build for are determined
by DEB_*_ARCH (the Debian architecture) DEB_*_GNU_TYPE (the GNU style architecture
- specification string) DEB_*_GNU_CPU (the CPU part of
- DEB_*_GNU_TYPE) DEB_*_GNU_SYSTEM (the System part of
- DEB_*_GNU_TYPE)
where * is either BUILD for specification of
the build machine or HOST for specification of the
@@ -2134,337 +1999,1389 @@ Package: libc6
or system information; the GNU style variables should be
used for that.
+ Supporting the standardized environment variable
+ DEB_BUILD_OPTIONS is recommended. This variable can
+ contain several flags to change how a package is compiled and
+ built. Each flag must be in the form flag or
+ flag=options. If multiple flags are
+ given, they must be separated by whitespace.
+ The meaning of the following tags has been standardized:
+
+ Unknown flags must be ignored by
+ 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.
+
- This file records the changes to the Debian-specific parts of the
- package
- Though there is nothing stopping an author who is also
- the Debian maintainer from using it for all their
- changes, it will have to be renamed if the Debian and
- upstream maintainers become different people. In such a
- case, however, it might be better to maintain the
- package as a non-native package.
-
- It has a special format which allows the package building
- tools to discover which version of the package is being
- built and find out other release-specific information.
+ The
- That format is a series of entries like this:
- [optional blank line(s), stripped] [blank line(s), included in output of dpkg-parsechangelog] [optional blank line(s), stripped]
+ This is an optional, recommended control file for the
+ uscan utility which defines how to automatically
+ scan ftp or http sites for newly available updates of the
+ package. This is used by
- package and version are the source
- package name and version number.
+ This file is not a permanent part of the source tree; it
+ is used while building packages to record which files are
+ being generated.
- distribution(s) lists the distributions where
- this version should be installed when it is uploaded - it
- is copied to the Distribution field in the
- .changes file. See .
+ It should not exist in a shipped source package, and so it
+ (and any backup files or temporary files such as
+
- urgency is the value for the Urgency
- field in the .changes file for the upload. It is
- not possible to specify an urgency containing commas; commas
- are used to separate
- keyword=value settings in the
-
- Recognised urgency values are low,
- medium, high and emergency.
- They have an effect on how quickly a package will be
- considered for inclusion into the testing
- distribution, and give an indication of the importance
- of any fixes included in this upload.
-
+ If a package upload includes files besides the source
+ package and any binary packages whose control files were
+ made with
+ Some software packages include in their distribution convenience
+ copies of code from other software packages, generally so that
+ users compiling from source don't have to download multiple
+ packages. Debian packages should not make use of these
+ convenience copies unless the included package is explicitly
+ intended to be used in this way.
- The change details may in fact be any series of lines
- starting with at least two spaces, but conventionally each
- change starts with an asterisk and a separating space and
- continuation lines are indented so as to bring them in
- line with the start of the text above. Blank lines may be
- used here to separate groups of changes, if desired.
+ If running
- If this upload resolves bugs recorded in the Bug Tracking
- System (BTS), they may be automatically closed on the
- inclusion of this package into the Debian archive by
- including the string: closes: Bug#nnnnn
- in the change details.
- To be precise, the string should match the following
- Perl regular expression:
-
- The maintainer name and email address used in the changelog
- should be the details of the person uploading this
- version. They are not necessarily those of the
- usual package maintainer. The information here will be
- copied to the Changed-By field in the
- .changes file, and then later used to send an
- acknowledgement when the upload has been installed.
+
+ The 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
- The date should be in RFC822 format
- This is generated by the
- 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.
+ Each paragraph consists of a series of data fields; each
+ field consists of the field name, followed by a colon and
+ then the data/value associated with that field. It ends at
+ the end of the (logical) line. Horizontal whitespace
+ (spaces and tabs) may occur immediately before or after the
+ value and is ignored there; it is conventional to put a
+ single space after the colon. For example, a field might
+ be:
+
+ Many fields' values may span several lines; in this case + each continuation line must start with a space or a tab. + Any trailing spaces or tabs at the end of individual + lines of a field value are ignored. +
+ ++ In fields where it is specified that lines may not wrap, + only a single line of data is allowed and whitespace is not + significant in a field body. Whitespace must not appear + inside names (of packages, architectures, files or anything + else) or version numbers, or between the characters of + multi-character version relationships. +
+ ++ Field names are not case-sensitive, but it is usual to + capitalize the field names using mixed case as shown below. +
+ ++ Blank lines, or lines consisting only of spaces and tabs, + are not allowed within field values or between fields - that + would mean a new paragraph. +
-- It is possible to use a different format to the standard - one, by providing a parser for the format you wish to - use. -
-- A changelog parser must not interact with the user at - all. -
-
- When
- The debian/substvars file is usually generated and - modified dynamically by debian/rules targets; in - this case it must be removed by the clean - target. + The first paragraph of the control file contains information about + the source package in general. The subsequent sets each describe a + binary package that the source tree builds.
- See
- 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
- files.new
- files.new is used as a temporary file by
-
- When
- If a package upload includes files besides the source
- package and any binary packages whose control files were
- made with
- The source package may not contain any hard links
- This is not currently detected when building source
- packages, but only when extracting
- them.
-
- Hard links may be permitted at some point in the
- future, but would require a fair amount of
- work.
-
- Setgid directories are allowed.
-
+ The fields in this file are:
+
+
+
- The description is intended to describe the program to a user
- who has never met it before so that they know whether they
- want to install it. It should also give information about the
- significant dependencies and conflicts between this package
- and others, so that the user knows why these dependencies and
- conflicts have been declared.
+ This file contains a series of fields, identified and
+ separated just like the fields in the control file of
+ a binary package. The fields are listed below; their
+ syntax is described above, in .
+
+
+
+ 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:
+
+
+
+
- The single line synopsis should be kept brief - certainly - under 80 characters. + This field identifies the source package name.
- Do not include the package name in the synopsis line. The
- display software knows how to display this already, and you
- do not need to state it. Remember that in many situations
- the user may only see the synopsis line - make it as
- informative as you can.
+ In
- Do not try to continue the single line synopsis into the
- extended description. This will not work correctly when
- the full description is displayed, and makes no sense
- where only the summary (the single line synopsis) is
- available.
+ In a binary package control file or a
- The extended description should describe what the package - does and how it relates to the rest of the system (in terms - of, for example, which subsystem it is which part of). + The package maintainer's name and email address. The name + should come first, then the email address inside angle + brackets <> (in RFC822 format).
- The description field needs to make sense to anyone, even
- people who have no idea about any of the things the
- package deals with.
- The blurb that comes with a program in its
- announcements and/or
+ List of the names and email addresses of co-maintainers of
+ the package, if any. If the package has other maintainers
+ beside the one named in the
+
- 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.
+ Any parser that interprets the Uploaders field in
+
- You may include information about dependencies and so forth - in the extended description, if you wish. + 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.
+- Do not use tab characters. Their effect is not predictable. + This field specifies an application area into which the package + has been classified. See .
+
+ When it appears in the
+ This field represents how important that it is that the user + have the package installed. See . +
+ +
+ When it appears in the
+ 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. +
+
+ Depending on context and the control file used, the
+ Architecture field can include the following sets of
+ values:
+
+
+
+ In the main
+ Specifying any indicates that the source package
+ isn't dependent on any particular architecture and should
+ compile fine on any one. The produced binary package(s)
+ will be specific to whatever the current build architecture
+ is.
+ Specifying a list of architectures indicates that the source
+ will build an architecture-dependent package, and will only
+ work correctly on the listed architectures.
+ 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
+ + . ~ (plus, full stop,
+ tilde) 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 "debianisation"
+ 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 and so that a tilde
+ sorts before anything, even the end of a part. For example,
+ the following parts are in sorted order from earliest to
+ latest: ~~, ~~a, ~, the empty part,
+ a.
+ 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 taking one of the values low,
+ medium, high, emergency, or
+ critical
+ 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 + consisting 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. +
++ The URL of the web site for this package, preferably (when + applicable) the site from which the original source can be + obtained and any additional upstream documentation or + information may be found. The content of this field is a + simple URL without any surrounding characters such as + <>. +
++ 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 @@ -2474,11 +3391,12 @@ Package: libc6
These scripts are the files
@@ -2493,6 +3411,13 @@ Package: libc6 well.
+
+ Additionally, packages interacting with users using
+ debconf in the
When a package is upgraded a combination of the scripts from
the old and new packages is called during the upgrade
@@ -2517,7 +3442,7 @@ Package: libc6
It is necessary for the error recovery procedures that the
@@ -2537,40 +3462,37 @@ Package: libc6
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.
+ 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 /dev/tty, since
-
- Each script should return a zero exit status for - success, or a nonzero one for failure. + Each script must return a zero exit status for + success, or a nonzero one for failure, since the package + management system looks for the exit status of these scripts + and determines what action to take next based on that datum.
new-preinst install new-preinst install
- old-version new-preinst upgrade
- old-version old-preinst abort-upgrade
+ old-preinst abort-upgrade
new-version
-
postinst configure
- most-recently-configured-version old-postinst abort-upgrade
- new-version conflictor's-postinst abort-remove
+ conflictor's-postinst abort-remove
in-favour package
- new-version
deconfigured's-postinst
abort-deconfigure in-favour
failed-install-package version
- removing conflicting-package
- version
-
prerm remove old-prerm upgrade
- new-version new-prerm failed-upgrade
- old-version conflictor's-prerm remove
+ conflictor's-prerm remove
in-favour package
- new-version
deconfigured's-prerm deconfigure
in-favour package-being-installed
- version removing
+ version [removing
conflicting-package
- version
-
postrm remove postrm purge
old-postrm upgrade
- new-version new-postrm failed-upgrade
- old-version new-postrm abort-install new-postrm abort-install
- old-version new-postrm abort-upgrade
- old-version
disappearer's-postrm disappear
overwriter
- overwriter-version
The procedure on installation/upgrade/overwrite/disappear
@@ -2701,43 +3617,61 @@ Package: libc6
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
+ reverse order. These are the "error unwind" calls listed
below.
If a version of the package is already
- installed, call
+ If a version of the package is already installed, call
If the script runs but exits with a non-zero
exit status, If a `conflicting' package is being removed at the same time:
+ If a "conflicting" package is being removed at the same time,
+ or if any package will be broken (due to Breaks):
- If any packages depended on that conflicting
- package and --auto-deconfigure is
+ If --auto-deconfigure is
+ specified, call, for each package to be deconfigured
+ due to Breaks:
+ To prepare for removal of the conflicting package, call:
+ To prepare for removal of each conflicting package, call:
If the package is being upgraded, call:
+ If the package is being upgraded, call:
+ If that works, then
+
+ If it fails, then the old version is left
+ in an "Half-Installed" state.
+
Otherwise, if the package had some configuration
files from a previous version installed (i.e., it
- is in the `configuration files only' state):
+ is in the "configuration files only" state):
Otherwise (i.e., the package was completely purged):
+ Otherwise (i.e., the package was completely purged):
The new package's files are unpacked, overwriting any @@ -2817,7 +3781,7 @@ Package: libc6
- It is an error for a package to contains files which + It is an error for a package to contain files which are on the system in another package, unless Replaces is used (see ). + + +