X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=policy.sgml;h=1de249479b7fb128679dd6ad1da1ce78c83bfb2b;hb=baea58c43486488c3c9bd0b4e52957ce88ddd94c;hp=9b9ee4c22e4ebf6b9dd7421df0e830b53cb7a9e5;hpb=efc6efea905ceaedb8c59140bd22603b12105426;p=debian%2Fdebian-policy.git
diff --git a/policy.sgml b/policy.sgml
index 9b9ee4c..1de2494 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -24,6 +24,13 @@
Copyright © 1996,1997,1998 Ian Jackson
and Christian Schwarz.
+
+ These are the copyright dates of the original Policy manual.
+ Since then, this manual has been updated by many others. No
+ comprehensive collection of copyright notices for subsequent
+ work exists.
+
+
This manual is free software; you may redistribute it and/or
modify it under the terms of the GNU General Public License
@@ -83,11 +90,10 @@
is used by, a significant number of packages, and
therefore should not be changed without peer
review. Package maintainers can then rely on this
- interfaces not changing, and the package
- management software authors need to ensure
- compatibility with these interface
- definitions. (Control file and changelog file
- formats are examples.)
+ interface not changing, and the package management
+ software authors need to ensure compatibility with
+ this interface definition. (Control file and
+ changelog file formats are examples.)
Chosen Convention
-
@@ -318,13 +324,11 @@
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 distribution
- areas or components
+ restrictions. Thus, the archive is split into areas
The Debian archive software uses the term "component" internally
and in the Release file format to refer to the division of an
- archive. The Debian Social Contract refers to distribution
- areas. This document uses the same terminology as the Social
- Contract.
+ archive. The Debian Social Contract simply refers to "areas."
+ This document uses terminology similar to the Social Contract.
based on their licenses and other restrictions.
@@ -342,12 +346,12 @@
- The main distribution area forms the Debian GNU/Linux
+ The main archive area forms the Debian GNU/Linux
distribution.
- Packages in the other distribution areas (contrib,
+ Packages in the other archive 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
@@ -361,7 +365,7 @@
The Debian Free Software Guidelines (DFSG) form our
definition of "free software". These are:
- Free Redistribution
+ 1. Free Redistribution
-
The license of a Debian component may not restrict any
@@ -371,20 +375,20 @@
sources. The license may not require a royalty or
other fee for such sale.
- Source Code
+ 2. Source Code
-
The program must include source code, and must allow
distribution in source code as well as compiled form.
- Derived Works
+ 3. Derived Works
-
The license must allow modifications and derived
works, and must allow them to be distributed under the
same terms as the license of the original software.
- Integrity of The Author's Source Code
+ 4. Integrity of The Author's Source Code
-
The license may restrict source-code from being
@@ -399,13 +403,13 @@
Project encourages all authors to not restrict any
files, source or binary, from being modified.)
- No Discrimination Against Persons or Groups
+ 5. No Discrimination Against Persons or Groups
-
The license must not discriminate against any person
or group of persons.
- No Discrimination Against Fields of Endeavor
+ 6. No Discrimination Against Fields of Endeavor
-
The license must not restrict anyone from making use
@@ -414,7 +418,7 @@
used in a business, or from being used for genetic
research.
- Distribution of License
+ 7. Distribution of License
-
The rights attached to the program must apply to all
@@ -422,7 +426,7 @@
for execution of an additional license by those
parties.
- License Must Not Be Specific to Debian
+ 8. License Must Not Be Specific to Debian
-
The rights attached to the program must not depend on
@@ -434,7 +438,7 @@
rights as those that are granted in conjunction with
the Debian system.
- License Must Not Contaminate Other Software
+ 9. License Must Not Contaminate Other Software
-
The license must not place restrictions on other
@@ -443,7 +447,7 @@
that all other programs distributed on the same medium
must be free software.
- Example Licenses
+ 10. Example Licenses
-
The "GPL," "BSD," and "Artistic" licenses are examples of
@@ -454,10 +458,10 @@
- Distribution areas
+ Archive areas
- The main distribution area
+ The main archive area
Every package in main must comply with the DFSG
@@ -488,7 +492,7 @@
- The contrib distribution area
+ The contrib archive area
Every package in contrib must comply with the DFSG.
@@ -528,7 +532,7 @@
- The non-free distribution area
+ The non-free archive area
Packages must be placed in non-free if they are
@@ -644,27 +648,27 @@
Sections
- The packages in the distribution areas main,
- contrib and non-free are grouped further
- into sections to simplify handling.
+ The packages in the archive areas main,
+ contrib and non-free are grouped further into
+ sections to simplify handling.
- The distribution area 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 archive area 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:
]
-
section if the package is in the
- main distribution area,
+ main archive area,
-
area/section if the package is in
the contrib or non-free
- distribution areas.
+ archive areas.
@@ -672,18 +676,20 @@
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.
+ admin, cli-mono, comm, database,
+ devel, debug, doc, editors,
+ electronics, embedded, fonts,
+ games, gnome, graphics, gnu-r,
+ gnustep, hamradio, haskell,
+ httpd, interpreters, java, kde,
+ kernel, libs, libdevel, lisp,
+ localization, mail, math, misc,
+ net, news, ocaml, oldlibs,
+ otherosfs, perl, php, python,
+ ruby, science, shells, sound,
+ tex, text, utils, vcs,
+ video, web, x11, xfce,
+ zope.
@@ -1220,17 +1226,16 @@
Prompting in maintainer scripts
Package maintainer scripts may prompt the user if
- necessary. Prompting should be done by communicating
+ necessary. Prompting must be done by communicating
through a program, such as debconf, which
conforms to the Debian Configuration Management
- Specification, version 2 or higher. Prompting the user by
- other means, such as by hand
- From the Jargon file: by hand 2. By extension,
- writing code which does something in an explicit or
- low-level way for which a presupplied library
- (debconf, in this instance) routine ought
- to have been available.
- , is now deprecated.
+ Specification, version 2 or higher.
+
+
+
+ Packages which are essential, or which are dependencies of
+ essential packages, may fall back on another prompting method
+ if no such interface is available when they are executed.
@@ -1637,7 +1642,7 @@
its copyright and distribution license in the file
/usr/share/doc/package/copyright
(see [ for further details). Also see
- ][ for further considerations relayed
+ ][ for further considerations related
to copyrights for packages.
]
@@ -1720,14 +1725,17 @@
It must start with the line #!/usr/bin/make -f,
so that it can be invoked by saying its name rather than
- invoking make explicitly.
+ invoking make explicitly. That is, invoking
+ either of make -f debian/rules args...
+ or ./debian/rules args... must result in
+ identical behavior.
Since an interactive debian/rules script makes it
impossible to auto-compile that package and also makes it
hard for other people to reproduce the same binary
- package, all required targets MUST be
+ package, all required targets must be
non-interactive. At a minimum, required targets are the
ones called by dpkg-buildpackage, namely,
clean, binary, binary-arch,
@@ -1986,6 +1994,12 @@
-
DEB_*_ARCH (the Debian architecture)
+ -
+ DEB_*_ARCH_CPU (the Debian CPU name)
+
+ -
+ DEB_*_ARCH_OS (the Debian System name)
+
-
DEB_*_GNU_TYPE (the GNU style architecture
specification string)
@@ -2014,8 +2028,10 @@
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.
+ or system information; the DEB_*_ARCH_CPU and
+ DEB_*_ARCH_OS variables should be used for that.
+ GNU style variables should generally only be used with upstream
+ build systems.
@@ -2365,6 +2381,8 @@ Package: libc6
Field names are not case-sensitive, but it is usual to
capitalize the field names using mixed case as shown below.
+ Field values are case-sensitive unless the description of the
+ field says otherwise.
@@ -2452,6 +2470,15 @@ Package: libc6
See [ for details.
]
+
+ In addition to the control file syntax described above, this file may also contain
+ comment lines starting with # without any preceding
+ whitespace. All such lines are ignored, even in the middle of
+ continuation lines for a multiline field, and do not end a
+ multiline field.
+
+
@@ -2580,6 +2607,15 @@ Package: libc6
package control file when the source package has the same
name and version as the binary package.
+
+
+ Package names (both source and binary,
+ see [) 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.
+ ]
@@ -2656,7 +2692,7 @@ Package: libc6
Priority
- This field represents how important that it is that the user
+ This field represents how important it is that the user
have the package installed. See [.
]
@@ -2677,11 +2713,9 @@ Package: libc6
- 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.
+ Binary package names must follow the same syntax and
+ restrictions as source package names. See [
+ for the details.
]
@@ -2694,7 +2728,12 @@ Package: libc6
values:
- A unique single word identifying a Debian machine
- architecture, see
[.
+ architecture as described in ][.
+ ]
+ -
+ An architecture wildcard identifying a set of Debian
+ machine architectures, see
[.
+ ]
- all, which indicates an
architecture-independent package.
- any, which indicates a package available
@@ -2705,31 +2744,72 @@ Package: libc6
In the main debian/control file in the source
- package, or in the source package control file
- .dsc, one may specify a list of architectures
- separated by spaces, or the special values any or
- all.
+ package, this field may contain the special value
+ any, the special value all, or a list of
+ specific and wildcard architectures separated by
+ spaces. If the special value any appears, it must
+ be the entire contents of the field. Most packages will
+ use either any or all. Specifying a
+ specific list of architectures is for the minority of
+ cases where a program is not portable or is not useful on
+ some architectures, and where possible the program should
+ be made portable instead.
+
+
+
+ In the source package control file .dsc, this
+ field may contain either the special value any or a
+ list of architectures separated by spaces. If a list is given,
+ it may include (or consist solely of) the special value
+ all. In other words, in .dsc files
+ unlike the debian/control, all may occur
+ in combination with specific architectures. The
+ Architecture field in the source package control file
+ .dsc is generally constructed from the
+ Architecture fields in the
+ debian/control in the source package.
Specifying any indicates that the source package
isn't dependent on any particular architecture and should
compile fine on any one. The produced binary package(s)
- will be specific to whatever the current build architecture
- is.
- This is the most often used setting, and is recommended
- for new packages that aren't Architecture: all.
-
+ will either be specific to whatever the current build
+ architecture is or will be architecture-independent.
+
+
+
+ Specifying only all indicates that the source package
+ will only build architecture-independent packages. If this is
+ the case, all must be used rather than any;
+ any implies that the source package will build at
+ least one architecture-dependent package.
Specifying a list of architectures indicates that the source
will build an architecture-dependent package, and will only
- work correctly on the listed architectures.
- This is a setting used for a minority of cases where the
- program is not portable. Generally, it should not be used
- for new packages.
-
+ work correctly on the listed architectures. If the source
+ package also builds at least one architecture-independent
+ package, all will also be included in the list.
+
+
+
+ Specifying a list of architecture wildcards indicates that
+ the source will build an architecture-dependent package on
+ the union of the lists of architectures from the expansion
+ of each specified architecture wildcard, and will only
+ work correctly on the architectures in the union of the
+ lists. As mentioned in the footnote for
+ specifying a list of architectures, this is for a minority
+ of cases where the program is not portable. Generally, it
+ should not be used for new packages. Wildcards are not
+ expanded into a list of known architectures before
+ comparing to the build architecutre. Instead, the build
+ architecture is matched against wildcards and this package
+ is built if the wildcard matches. If the source
+ package also builds at least one architecture-independent
+ package, all will also be included in the list.
@@ -2737,12 +2817,16 @@ Package: libc6
field lists the architecture(s) of the package(s)
currently being uploaded. This will be a list; if the
source for the package is also being uploaded, the special
- entry source is also present.
+ entry source is also present. all will be
+ present if any architecture-independent packages are being
+ uploaded. any may never occur in the
+ Architecture field in the .changes
+ file.
- See [ for information how to get the
- architecture for the build process.
+ See ][ for information on how to get
+ the architecture for the build process.
]
@@ -2803,8 +2887,8 @@ Package: libc6
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.
+ field, and so either these three components or 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
@@ -3045,18 +3129,16 @@ Package: libc6
- In a .changes file, the Description field
- contains a summary of the descriptions for the packages being
- uploaded.
+ In a .changes file, the Description
+ field contains a summary of the descriptions for the packages
+ being uploaded. For this case, the first line of the field
+ value (the part on the same line as Description:) is
+ always empty. The content of the field is expressed as
+ continuation lines, one line per package. Each line is
+ indented by one space and contains the name of a binary
+ package, a space, a hyphen (-), a space, and the
+ short description line from that package.
-
-
- 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.
-
-
@@ -3068,76 +3150,39 @@ Package: libc6
distribution(s) where this version of the package should
be installed. Valid distributions are determined by the
archive maintainers.
- Current distribution names are:
+ Example distribution names in the Debian archive used in
+ .changes files are:
- stable
- -
- This is the current "released" version of Debian
- GNU/Linux. Once the distribution is
- stable only security fixes and other
- major bug fixes are allowed. When changes are
- made to this distribution, the release number is
- increased (for example: 2.2r1 becomes 2.2r2 then
- 2.2r3, etc).
-
-
unstable
-
- This distribution value refers to the
- developmental part of the Debian
- distribution tree. New packages, new upstream
- versions of packages and bug fixes go into the
- unstable directory tree. Download from
- this distribution at your own risk.
-
-
- testing
- -
- This distribution value refers to the
- testing part of the Debian distribution
- tree. It receives its packages from the
- unstable distribution after a short time lag to
- ensure that there are no major issues with the
- unstable packages. It is less prone to breakage
- than unstable, but still risky. It is not
- possible to upload packages directly to
- testing.
-
-
- frozen
- -
- From time to time, the testing
- distribution enters a state of "code-freeze" in
- anticipation of release as a stable
- version. During this period of testing only
- fixes for existing or newly-discovered bugs will
- be allowed. The exact details of this stage are
- determined by the Release Manager.
+ This distribution value refers to the
+ developmental part of the Debian distribution
+ tree. Most new packages, new upstream versions of
+ packages and bug fixes go into the unstable
+ directory tree.
experimental
-
- The packages with this distribution value are
- deemed by their maintainers to be high
- risk. Oftentimes they represent early beta or
- developmental packages from various sources that
- the maintainers want people to try, but are not
- ready to be a part of the other parts of the
- Debian distribution tree. Download at your own
- risk.
+ The 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.
- 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".
+ Others are used for updating stable releases or for
+ security uploads. More information is available in the
+ Debian Developer's Reference, section "The Debian
+ archive".
+ The Debian archive software only supports listing a single
+ distribution. Migration of packages to other distributions is
+ handled outside of the upload process.
@@ -3210,10 +3255,12 @@ Package: libc6
- 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 first line of the field value (the part on the same line
+ as Changes:) is always empty. The content of the
+ field is expressed as continuation lines, with each line
+ indented by at least one space. Blank lines must be
+ represented by a line consisting only of a space and a full
+ stop (.).
@@ -3233,7 +3280,7 @@ Package: libc6
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).
+ representation of a blank line).
@@ -3241,29 +3288,27 @@ Package: libc6
Binary
- This field is a list of binary packages.
-
-
-
- When it appears in the .dsc file it is the list
- of binary packages which a source package can produce. It
- does not necessarily produce all of these binary packages
- for every architecture. The source control file doesn't
- contain details of which architectures are appropriate for
- which of the binary packages.
+ This field is a list of binary packages. Its syntax and
+ meaning varies depending on the control file in which it
+ appears.
- When it appears in a .changes file it lists the
- names of the binary packages actually being uploaded.
+ When it appears in the .dsc file, it lists binary
+ packages which a source package can produce, separated by
+ commas
+ A space after each comma is conventional.
+ . It may span multiple lines. The source package
+ does not necessarily produce all of these binary packages for
+ every architecture. The source control file doesn't contain
+ details of which architectures are appropriate for which of
+ the binary packages.
- The syntax is a list of binary packages separated by
- commas
- A space after each comma is conventional.
- . Currently the packages must be separated using
- only spaces in the .changes file.
+ When it appears in a .changes file, it lists the
+ names of the binary packages being uploaded, separated by
+ whitespace (not commas). It may span multiple lines.
@@ -3271,15 +3316,17 @@ Package: libc6
Installed-Size
- This field appears in the control files of binary
- packages, and in the Packages files. It gives
- the total amount of disk space required to install the
- named package.
+ This field appears in the control files of binary packages,
+ and in the Packages files. It gives an estimate
+ of the total amount of disk space required to install the
+ named package. Actual installed size may vary based on block
+ size, file system properties, or actions taken by package
+ maintainer scripts.
- The disk space is represented in kilobytes as a simple
- decimal number.
+ The disk space is given as the integer value of the estimated
+ installed size in bytes, divided by 1024 and rounded up.
@@ -3289,20 +3336,30 @@ Package: libc6
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.
+ the context.
+
+
+
+ In all cases, Files is a multiline field. The first line of
+ the field value (the part on the same line as Files:)
+ is always empty. The content of the field is expressed as
+ continuation lines, one line per file. Each line must be
+ indented by one space and contain a number of sub-fields,
+ separated by spaces, as described below.
In the .dsc file, each line contains the MD5
- checksum, size and filename of the tar file and (if applicable)
- diff file which make up the remainder of the source
- package
- That is, the parts which are not the .dsc.
- .
+ checksum, size and filename of the tar file and (if
+ applicable) diff file which make up the remainder of the
+ source package
+ That is, the parts which are not the .dsc.
+ . For example:
+
+Files:
+ c6f698f19f2a2aa07dbb9bbda90a2754 571925 example_1.2.orig.tar.gz
+ 938512f08422f3509ff36f125f5873ba 6220 example_1.2-1.diff.gz
+
The exact forms of the filenames are described
in [.
]
@@ -3310,14 +3367,20 @@ Package: libc6
In the .changes file this contains one line per
file being uploaded. Each line contains the MD5 checksum,
- size, section and priority and the filename.
+ size, section and priority and the filename. For example:
+
+Files:
+ 4c31ab7bfc40d3cf49d7811987390357 1428 text extra example_1.2-1.dsc
+ c6f698f19f2a2aa07dbb9bbda90a2754 571925 text extra example_1.2.orig.tar.gz
+ 938512f08422f3509ff36f125f5873ba 6220 text extra example_1.2-1.diff.gz
+ 7c98fe853b3bbb47a00e5cd129b6cb56 703542 text extra example_1.2-1_i386.deb
+
The section
- and priority
- are the values of the corresponding fields in
- the main source control file. If no section or priority is
- specified then - should be used, though section
- and priority values must be specified for new packages to
- be installed properly.
+ and priority are the values of
+ the corresponding fields in the main source control file. If
+ no section or priority is specified then - should be
+ used, though section and priority values must be specified for
+ new packages to be installed properly.
@@ -3333,7 +3396,7 @@ Package: libc6
no new original source archive is being distributed the
.dsc must still contain the Files field
entry for the original source archive
- package-upstream-version.orig.tar.gz,
+ package_upstream-version.orig.tar.gz,
but the .changes file should leave it out. In
this case the original source archive on the distribution
site must match exactly, byte-for-byte, the original
@@ -3676,7 +3739,7 @@ Package: libc6
If this works, then the old-version is
"Installed", if not, the old version is in a
- "Failed-Config" state.
+ "Half-Configured" state.
@@ -3784,7 +3847,7 @@ Package: libc6
If this fails, the package is left in a
"Half-Installed" state, which requires a
reinstall. If it works, the packages is left in
- a "Config Files" state.
+ a "Config-Files" state.
-
Otherwise (i.e., the package was completely purged):
@@ -3796,7 +3859,7 @@ Package: libc6
new-postrm abort-install
If the error-unwind fails, the package is in a
- "Half Installed" phase, and requires a
+ "Half-Installed" phase, and requires a
reinstall. If the error unwind works, the
package is in a not installed state.
@@ -3876,14 +3939,14 @@ Package: libc6
old-preinst abort-upgrade new-version
- If this fails, the old version is left in an
- "Half Installed" state. If it works, dpkg now
+ If this fails, the old version is left in a
+ "Half-Installed" state. If it works, dpkg now
calls:
new-postrm abort-upgrade old-version
- If this fails, the old version is left in an
- "Half Installed" state. If it works, dpkg now
+ If this fails, the old version is left in a
+ "Half-Installed" state. If it works, dpkg now
calls:
old-postinst abort-upgrade new-version
@@ -4042,7 +4105,7 @@ Package: libc6
- If this fails, the package is in a "Failed-Config"
+ If this fails, the package is in a "Half-Configured"
state, or else it remains "Installed".
@@ -4220,6 +4283,23 @@ Build-Depends: foo [!i386] | bar [!amd64]
source package section of the control file (which is the
first section).
+
+ All fields that specify build-time relationships
+ (Build-Depends, Build-Depends-Indep,
+ Build-Conflicts and Build-Conflicts-Indep) may also
+ be restricted to a certain set of architectures using architecture
+ wildcards. The syntax for declaring such restrictions is the same as
+ declaring restrictions using a certain set of architectures without
+ architecture wildcards.
+ For example:
+
+Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any]
+
+ is equivalent to foo on architectures using the
+ Linux kernel and any cpu, bar on architectures
+ using any kernel and an i386 cpu, and baz on
+ on any architecture using a kernel other than Linux.
+
@@ -4239,6 +4319,9 @@ Build-Depends: foo [!i386] | bar [!amd64]
This is done using the Depends, Pre-Depends,
Recommends, Suggests, Enhances,
Breaks and Conflicts control file fields.
+ Breaks is described in [, and
+ Conflicts is described in ][. The
+ rest are described below.
]
@@ -4375,12 +4458,12 @@ Build-Depends: foo [!i386] | bar [!amd64]
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
+ package(s) are only unpacked or in the "Half-Configured"
+ state, 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
+ "Half-Configured" versions must satisfy any version
clause in the Pre-Depends field.
@@ -4426,12 +4509,6 @@ Build-Depends: foo [!i386] | bar [!amd64]
Packages which break other packages - Breaks
-
- Using Breaks may cause problems for upgrades from older
- versions of Debian and should not be used until the stable
- release of Debian supports Breaks.
-
-
When one binary package declares that it breaks another,
dpkg will refuse to allow the package which
@@ -4443,7 +4520,7 @@ Build-Depends: foo [!i386] | bar [!amd64]
A package will not be regarded as causing breakage merely
because its configuration files are still installed; it must
- be at least half-installed.
+ be at least "Half-Installed".
@@ -4497,7 +4574,7 @@ Build-Depends: foo [!i386] | bar [!amd64]
A package will not cause a conflict merely because its
configuration files are still installed; it must be at least
- half-installed.
+ "Half-Installed".
@@ -4516,8 +4593,7 @@ Build-Depends: foo [!i386] | bar [!amd64]
dpkg from upgrading or installing the package
which declared such a conflict until the upgrade or removal
of the conflicted-with package had been completed. Instead,
- Breaks may be used (once Breaks is supported
- by the stable release of Debian).
+ Breaks may be used.
@@ -5304,10 +5380,10 @@ dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* \
- If you are creating a udeb for use in the Debian Installer, you
- will need to specify that dpkg-shlibdeps should use
- the dependency line of type udeb by adding
- -tudeb as option
+ If you are creating a udeb for use in the Debian Installer,
+ you will need to specify that dpkg-shlibdeps
+ should use the dependency line of type udeb by
+ adding the -tudeb option
dh_shlibdeps from the debhelper suite
will automatically add this option if it knows it is
processing a udeb.
@@ -5518,23 +5594,16 @@ libbar 1 bar1 (>= 1.0-1)
- File system Structure
+ File System Structure
The location of all installed files and directories must
- comply with the File system Hierarchy Standard (FHS),
+ comply with the Filesystem Hierarchy Standard (FHS),
version 2.3, with the exceptions noted below, and except
where doing so would violate other terms of Debian
Policy. The following exceptions to the FHS apply:
- -
-
- Legacy XFree86 servers are permitted to retain the
- configuration file location
- /etc/X11/XF86Config-4.
-
-
-
The optional rules related to user specific
@@ -5556,6 +5625,40 @@ libbar 1 bar1 (>= 1.0-1)
for 64 bit binaries is removed.
+ -
+
+ The requirement for object files, internal binaries, and
+ libraries, including libc.so.*, to be located
+ directly under /lib{,32} and
+ /usr/lib{,32} is amended, permitting files
+ to instead be installed to
+ /lib/triplet and
+ /usr/lib/triplet, where
+ triplet is the value returned by
+ dpkg-architecture -qDEB_HOST_GNU_TYPE for the
+ architecture of the package. Packages may not
+ install files to any triplet path other
+ than the one matching the architecture of that package;
+ for instance, an Architecture: amd64 package
+ containing 32-bit x86 libraries may not install these
+ libraries to /usr/lib/i486-linux-gnu.
+
+ This is necessary in order to reserve the directories for
+ use in cross-installation of library packages from other
+ architectures, as part of the planned deployment of
+ multiarch.
+
+
+
+ Applications may also use a single subdirectory under
+ /usr/lib/triplet.
+
+
+ The execution time linker/loader, ld*, must still be made
+ available in the existing location under /lib or /lib64
+ since this is part of the ELF ABI for the architecture.
+
+
-
The requirement that
@@ -5579,6 +5682,15 @@ libbar 1 bar1 (>= 1.0-1)
symlinked there, is relaxed to a recommendation.
+ -
+
+ The following directories in the root filesystem are
+ additionally allowed: /sys and
+ /selinux. These directories
+ are used as mount points to mount virtual filesystems
+ to get access to kernel information.
+
+
@@ -5624,13 +5736,15 @@ libbar 1 bar1 (>= 1.0-1)
- Note, that this applies only to directories below
- /usr/local, not in /usr/local.
- Packages must not create sub-directories in the directory
- /usr/local itself, except those listed in FHS,
- section 4.5. However, you may create directories below
- them as you wish. You must not remove any of the
- directories listed in 4.5, even if you created them.
+ Note that this applies only to
+ directories below /usr/local,
+ not in /usr/local. Packages must
+ not create sub-directories in the
+ directory /usr/local itself, except those
+ listed in FHS, section 4.5. However, you may create
+ directories below them as you wish. You must not remove
+ any of the directories listed in 4.5, even if you created
+ them.
@@ -5691,17 +5805,12 @@ rmdir /usr/local/share/emacs 2>/dev/null || true
The system-wide mail directory
- The system-wide mail directory is /var/mail. This
- directory is part of the base system and should not owned
- by any particular mail agents. The use of the old
+ The system-wide mail directory
+ is /var/mail. This directory is part of the
+ base system and should not be owned by any particular mail
+ agents. The use of the old
location /var/spool/mail is deprecated, even
though the spool may still be physically located there.
- To maintain partial upgrade compatibility for systems
- which have /var/spool/mail as their physical mail
- spool, packages using /var/mail must depend on
- either libc6 (>= 2.1.3-13), or on
- base-files (>= 2.2.0), or on later
- versions of either one of these packages.
@@ -5941,13 +6050,6 @@ rmdir /usr/local/share/emacs 2>/dev/null || true
K prefix, but they too are called with the single
argument stop.
-
-
- Also, if the script name ends in .sh, the script
- will be sourced in runlevel S rather than being
- run in a forked subprocess, but will be explicitly run by
- sh in all other runlevels.
-
@@ -6071,6 +6173,18 @@ test -f program-executed-later-in-script || exit 0
script must behave sensibly and not fail if the
/etc/default file is deleted.
+
+
+ /var/run and /var/lock may be mounted
+ as temporary filesystems
+ For example, using the RAMRUN and RAMLOCK
+ options in /etc/default/rcS.
+ , so the init.d scripts must handle this
+ correctly. This will typically amount to creating any required
+ subdirectories dynamically when the init.d script
+ is run, rather than including them in the package and relying on
+ dpkg to create them.
+
@@ -6369,10 +6483,10 @@ echo "Setting DNS domainname to \"$domainname\"."
- Note that the same symbol (") is used for the left
- and right quotation marks. A grave accent (`) is
- not a quote character; neither is an apostrophe
- (').
+ 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 (').
@@ -6479,13 +6593,48 @@ Reloading description configuration...done.
anacron. Thus, you should only use this
directory for jobs which may be skipped if the system is not
running.)
+
+ Unlike crontab files described in the IEEE Std
+ 1003.1-2008 (POSIX.1) available from
+ , the files in
+ /etc/cron.d and the file
+ /etc/crontab have seven fields; namely:
+
+ - Minute [0,59]
+ - Hour [0,23]
+ - Day of the month [1,31]
+ - Month of the year [1,12]
+ - Day of the week ([0,6] with 0=Sunday)
+ - Username
+ - Command to be run
+
+ Ranges of numbers are allowed. Ranges are two numbers
+ separated with a hyphen. The specified range is inclusive.
+ Lists are allowed. A list is a set of numbers (or ranges)
+ separated by commas. Step values can be used in conjunction
+ with ranges.
+
- The scripts or crontab entries in these directories should
+ 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.
+ are kept on the system in this situation.
+
+
+
+ Any cron daemon must provide
+ /usr/bin/crontab and support normal
+ crontab entries as specified in POSIX. The daemon
+ must also support names for days and months, ranges, and
+ step values. It has to support /etc/crontab,
+ and correctly execute the scripts in
+ /etc/cron.d. The daemon must also correctly
+ execute scripts in
+ /etc/cron.{hourly,daily,weekly,monthly}.
+
@@ -7764,9 +7914,17 @@ do
fi
done
- The corresponding dpkg-statoverride --remove
- calls can then be made unconditionally when the package is
- purged.
+ The corresponding code to remove the override when the package
+ is purged would be:
+
+for i in /usr/bin/foo /usr/sbin/bar
+do
+ if dpkg-statoverride --list $i >/dev/null 2>&1
+ then
+ dpkg-statoverride --remove $i
+ fi
+done
+
@@ -7839,6 +7997,27 @@ done
+
+ Architecture Wildcards
+
+
+ A package may specify an architecture wildcard. Architecture
+ wildcards are in the format os-any and
+ any-cpu. Internally, the package
+ system normalizes the GNU triplets and the Debian
+ arches into Debian arch triplets (which are kind of inverted GNU
+ triplets). So when matching two Debian arch triplets, whenever an
+ any is found it matches with anything on the other side,
+ like in:
+
+ gnu-linux-i386 is matched by gnu-linux-any
+ gnu-kfreebsd-amd64 is matched by any-any-amd64
+
+ And for example any is normalized to any-any-any.
+
+
+
+
Daemons
@@ -7934,10 +8113,10 @@ done
use /usr/bin/sensible-editor and
/usr/bin/sensible-pager as the editor or pager
program respectively. These are two scripts provided in the
- Debian base system that check the EDITOR and PAGER variables
- and launch the appropriate program, and fall back to
- /usr/bin/editor and /usr/bin/pager if the
- variable is not set.
+ sensible-utils package that check the EDITOR
+ and PAGER variables and launch the appropriate program, and fall
+ back to /usr/bin/editor
+ and /usr/bin/pager if the variable is not set.
@@ -8413,11 +8592,6 @@ name ["syshostname"]:
- -
- Speedo fonts must be placed in
- /usr/share/fonts/X11/Speedo/.
-
-
-
Type 1 fonts must be placed in
/usr/share/fonts/X11/Type1/. If font
@@ -8429,9 +8603,9 @@ name ["syshostname"]:
Subdirectories of /usr/share/fonts/X11/
other than those listed above must be neither
created nor used. (The PEX, CID,
- and cyrillic directories are excepted for
- historical reasons, but installation of files into
- these directories remains discouraged.)
+ Speedo, and cyrillic directories
+ are excepted for historical reasons, but installation of
+ files into these directories remains discouraged.)
-
@@ -8540,7 +8714,7 @@ name ["syshostname"]:
-
+
Application defaults files
@@ -8556,9 +8730,9 @@ name ["syshostname"]:
Customization of programs' X resources may also be
supported with the provision of a file with the same name
- as that of the package placed in the
- /etc/X11/Xresources/ directory, which must
- registered as a conffile or handled as a
+ as that of the package placed in
+ the /etc/X11/Xresources/ directory, which
+ must be registered as a conffile or handled as a
configuration file.
Note that this mechanism is not the same as using
app-defaults; app-defaults are tied to the client
@@ -8573,54 +8747,35 @@ name ["syshostname"]:
Installation directory issues
- Packages using the X Window System should not be
- configured to install files under the
- /usr/X11R6/ directory. The
- /usr/X11R6/ directory hierarchy should be
+ Historically, packages using the X Window System used a
+ separate set of installation directories from other packages.
+ This practice has been discontinued and packages using the X
+ Window System should now generally be installed in the same
+ directories as any other package. Specifically, packages must
+ not install files under the /usr/X11R6/ directory
+ and the /usr/X11R6/ directory hierarchy should be
regarded as obsolete.
- Programs that use GNU autoconf and
- automake are usually easily configured at
- compile time to use /usr/ instead of
- /usr/X11R6/, and this should be done whenever
- possible. Configuration files for window managers and
- display managers should be placed in a subdirectory of
- /etc/X11/ corresponding to the package name due
- to these programs' tight integration with the mechanisms
- of the X Window System. Application-level programs should
- use the /etc/ directory unless otherwise mandated
- by policy.
+ Include files previously installed under
+ /usr/X11R6/include/X11/ should be installed into
+ /usr/include/X11/. For files previously
+ installed into subdirectories of
+ /usr/X11R6/lib/X11/, package maintainers should
+ determine if subdirectories of /usr/lib/ and
+ /usr/share/ can be used. If not, a subdirectory
+ of /usr/lib/X11/ should be used.
- The installation of files into subdirectories
- of /usr/X11R6/include/X11/ and
- /usr/X11R6/lib/X11/ is now prohibited;
- package maintainers should determine if subdirectories of
- /usr/lib/ and /usr/share/ can be used
- instead.
-
-
-
- Packages should install any relevant files into the
- directories /usr/include/X11/ and
- /usr/lib/X11/, but if they do so, they must
- pre-depend on x11-common (>=
- 1:7.0.0)
-
- These libraries used to be all symbolic
- links. However, with X11R7,
- /usr/include/X11 and /usr/lib/X11
- are now real directories, and packages
- should ship their files here instead
- of in /usr/X11R6/{include,lib}/X11.
- x11-common (>= 1:7.0.0) is the package
- responsible for converting these symlinks into
- directories.
-
-
+ Configuration files for window, display, or session managers
+ or other applications that are tightly integrated with the X
+ Window System may be placed in a subdirectory
+ of /etc/X11/ corresponding to the package name.
+ Other X Window System applications should use
+ the /etc/ directory unless otherwise mandated by
+ policy (such as for [).
]
@@ -8845,12 +9000,12 @@ name ["syshostname"]:
- Due to limitations in current implementations, all characters
- in the manual page source should be representable in the usual
- legacy encoding for that language, even if the file is
- actually encoded in UTF-8. Safe alternative ways to write many
- characters outside that range may be found in
- .
+ If a localized version of a manual page is provided, it should
+ either be up-to-date or it should be obvious to the reader that
+ it is outdated and the original manual page should be used
+ instead. This can be done either by a note at the beginning of
+ the manual page or by showing the missing or changed portions in
+ the original language instead of the target language.
@@ -8863,37 +9018,53 @@ name ["syshostname"]:
- Your package should call install-info to update
- the Info dir file in its postinst
- script when called with a configure argument, for
- example:
-
-install-info --quiet --section Development Development \
- /usr/share/info/foobar.info
-
-
-
- It is a good idea to specify a section for the location of
- your program; this is done with the --section
- switch. To determine which section to use, you should look
- at /usr/share/info/dir on your system and choose the most
- relevant (or create a new section if none of the current
- sections are relevant). Note that the --section
- flag takes two arguments; the first is a regular expression
- to match (case-insensitively) against an existing section,
- the second is used when creating a new one.
-
-
- You should remove the entries in the prerm
- script when called with a remove argument:
-
-install-info --quiet --remove /usr/share/info/foobar.info
-
-
-
- If install-info cannot find a description entry
- in the Info file you must supply one. See for details.
+ The install-info program maintains a directory of
+ installed info documents in /usr/share/info/dir for
+ the use of info readers.
+ It was previously necessary for packages installing info
+ documents to run install-info from maintainer
+ scripts. This is no longer necessary. The installation
+ system now uses dpkg triggers.
+
+ This file must not be included in packages. Packages containing
+ info documents should depend on dpkg (>= 1.15.4) |
+ install-info to ensure that the directory file is properly
+ rebuilt during partial upgrades from Debian 5.0 (lenny) and
+ earlier.
+
+
+
+ Info documents should contain section and directory entry
+ information in the document for the use
+ of install-info. The section should be specified
+ via a line starting with INFO-DIR-SECTION followed by a
+ space and the section of this info page. The directory entry or
+ entries should be included between
+ a START-INFO-DIR-ENTRY line and
+ an END-INFO-DIR-ENTRY line. For example:
+
+INFO-DIR-SECTION Individual utilities
+START-INFO-DIR-ENTRY
+* example: (example). An example info directory entry.
+END-INFO-DIR-ENTRY
+
+ 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).
+ Normally, info documents are generated from Texinfo source.
+ To include this information in the generated info document, if
+ it is absent, add commands like:
+
+@dircategory Individual utilities
+@direntry
+* example: (example). An example info directory entry.
+@end direntry
+
+ to the Texinfo source of the document and ensure that the info
+ documents are rebuilt from source during the package build.
+
+
@@ -8945,7 +9116,7 @@ install-info --quiet --remove /usr/share/info/foobar.info
Please note that this does not override the section on
changelog files below, so the file
- /usr/share/package/changelog.Debian.gz
+ /usr/share/doc/package/changelog.Debian.gz
must refer to the changelog for the current version of
package in question. In practice, this means
that the sources of the target and the destination of the
@@ -9012,10 +9183,10 @@ install-info --quiet --remove /usr/share/info/foobar.info
- Packages in the contrib or non-free
- distribution areas should state in the copyright file that the
- package is not part of the Debian GNU/Linux distribution and
- briefly explain why.
+ Packages in the contrib or non-free archive
+ areas should state in the copyright file that the package is not
+ part of the Debian GNU/Linux distribution and briefly explain
+ why.
@@ -9036,8 +9207,8 @@ install-info --quiet --remove /usr/share/info/foobar.info
Packages distributed under the UCB BSD license, the Apache
license (version 2.0), the Artistic license, the GNU GPL
- (version 2 or 3), the GNU LGPL (versions 2, 2.1, or 3), and
- the GNU FDL (version 1.2) should refer to the corresponding
+ (version 2 or 3), the GNU LGPL (versions 2, 2.1, or 3), and the
+ GNU FDL (versions 1.2 or 1.3) should refer to the corresponding
files under /usr/share/common-licenses,
In particular,
@@ -9048,8 +9219,9 @@ install-info --quiet --remove /usr/share/info/foobar.info
/usr/share/common-licenses/GPL-3,
/usr/share/common-licenses/LGPL-2,
/usr/share/common-licenses/LGPL-2.1,
- /usr/share/common-licenses/LGPL-3, and
- /usr/share/common-licenses/GFDL-1.2
+ /usr/share/common-licenses/LGPL-3,
+ /usr/share/common-licenses/GFDL-1.2, and
+ /usr/share/common-licenses/GFDL-1.3
respectively.
rather than quoting them in the copyright