X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=policy.sgml;h=003675c1f5c5605ee7afb2f5e0dadfbf835eae21;hb=6ee89c2ae3c6a4fb7b07d207a882ac6e20e55a83;hp=b61ab26140fc17f3735e0e085a67af520c6e4cb5;hpb=de8e6ddc94be9d04836d7d1f68d1429978d14bfd;p=debian%2Fdebian-policy.git
diff --git a/policy.sgml b/policy.sgml
index b61ab26..003675c 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -218,12 +218,13 @@
The actual editing is done by a group of maintainers that have
no editorial powers. These are the current maintainers:
-
@@ -257,7 +258,6 @@
+ Finally, a
+ The main archive area comprises the Debian
+ distribution. Only the packages in this area are considered
+ part of the distribution. None of the packages in
+ the main archive area require software outside of
+ that area to function. Anyone may use, share, modify and
+ redistribute the packages in this archive area
+ freely
Every package in main must comply with the DFSG
(Debian Free Software Guidelines).
@@ -473,11 +495,11 @@
In addition, the packages in main
+ The contrib archive area contains supplemental
+ packages intended to work with the Debian distribution, but
+ which require software outside of the distribution to either
+ build or function.
+
Every package in contrib must comply with the DFSG.
Examples of packages which would be included in
contrib are:
@@ -535,6 +563,15 @@
+ The non-free archive area contains supplemental
+ packages intended to work with the Debian distribution that do
+ not comply with the DFSG or have other problems that make
+ their distribution problematic. They may not comply with all
+ of the policy requirements in this manual due to restrictions
+ on modifications or other limitations.
+
Packages must be placed in non-free if they are
not compliant with the DFSG or are encumbered by patents
@@ -677,20 +714,62 @@
The Debian archive maintainers provide the authoritative
list of sections. At present, they are:
- 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. The additional section debian-installer
+admin,
+cli-mono,
+comm,
+database,
+debug,
+devel,
+doc,
+editors,
+education,
+electronics,
+embedded,
+fonts,
+games,
+gnome,
+gnu-r,
+gnustep,
+graphics,
+hamradio,
+haskell,
+httpd,
+interpreters,
+introspection,
+java,
+kde,
+kernel,
+libdevel,
+libs,
+lisp,
+localization,
+mail,
+math,
+metapackages,
+misc,
+net,
+news,
+ocaml,
+oldlibs,
+otherosfs,
+perl,
+php,
+python,
+ruby,
+science,
+shells,
+sound,
+tasks,
+tex,
+text,
+utils,
+vcs,
+video,
+web,
+x11,
+xfce,
+zope.
+ The additional section debian-installer
contains special packages used by the installer and is not used
for normal Debian packages.
@@ -1103,10 +1182,10 @@
- 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. + Sometimes, unpacking one package requires that another package + be first unpacked and configured. In this case, the + depending package must specify this dependency in + the Pre-Depends control field.
@@ -1913,7 +1992,7 @@
- A package may also provide both of the targets
+ A package may also provide one or both of the targets
build-arch and build-indep.
The build-arch target, if provided, should
perform all the configuration and compilation required for
@@ -1926,9 +2005,13 @@
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 build-arch or build-indep targets are
+ provided in the rules file, the build target
+ should either depend on those targets or take the same
+ actions as invoking those targets would perform.
- 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:
+ 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. The field name is
+ composed of US-ASCII characters excluding control characters,
+ space, and colon (i.e., characters in the ranges 33-57 and
+ 59-126, inclusive). Field names must not begin with the comment
+ character, #.
+
+ The field ends at the end of the line or at the end of the last
+ continuation line (see below). 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.
+ There are three types of fields:
+
- 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
+ Whitespace must not appear
inside names (of packages, architectures, files or anything
else) or version numbers, or between the characters of
multi-character version relationships.
+ The presence and purpose of a field, and the syntax of its
+ value may differ between types of control files.
+
Field names are not case-sensitive, but it is usual to
capitalize the field names using mixed case as shown below.
@@ -2502,9 +2625,17 @@ Package: libc6
- 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.
+ Paragraph separators (empty lines) and lines consisting only of
+ spaces and tabs are not allowed within field values or between
+ fields. Empty lines in field values are usually escaped by
+ representing them by a space followed by a dot.
+
+ Lines starting with # without any preceding whitespace are comments
+ lines that are only permitted in source package control files
+ (
@@ -2535,11 +2666,13 @@ Package: libc6
- In addition to the control file syntax described
This file consists of a single paragraph, possibly surrounded by
a PGP signature. The fields of that paragraph are listed below.
- Their syntax is described above, in .
+ Their syntax is described above, in .
- The source package control file is generated by
+ The Debian source control file is generated by
- Any parser that interprets the Uploaders field in
-
- In the source package control file
+ The list may include (or consist solely of) the special
value all. In other words, in
- Specifying any indicates that the source package + Specifying only 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 either be specific to whatever the current build - architecture is or will be architecture-independent. + will be specific to whatever the current build architecture is.
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. + will only build architecture-independent packages. +
+ ++ Specifying any all indicates that the source package + isn't dependent on any particular architecture. The set of + produced binary packages will include at least one + architecture-dependant package and one architecture-independent + package.
@@ -2974,7 +3105,7 @@ Package: libc6
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. + paragraph of a source package control file.
@@ -3210,7 +3341,8 @@ Package: libc6 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: + long description. It is a multiline field with the following + format:
@@ -3230,6 +3362,7 @@ Package: libc6
Those starting with a single space are part of a paragraph.
Successive lines of this form will be word-wrapped when
displayed. The leading space will usually be stripped off.
+ The line must contain at least one non-whitespace character.
- This field contains the human-readable changes data, describing
+ This multiline field contains the human-readable changes data, describing
the differences between the last version and the current one.
- This field is a list of binary packages. Its syntax and
+ This folded 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
- These fields contain a list of files with a checksum and size
+ These multiline fields contain a list of files with a checksum and size
for each one. Both Checksums-Sha1
and Checksums-Sha256 have the same syntax and differ
only in the checksum algorithm used: SHA-1
@@ -3631,6 +3765,70 @@ Checksums-Sha256:
must match the list of files in the Files field.
+ Indicates that Debian Maintainers may upload this package to
+ the Debian archive. The only valid value is yes. If
+ the field DM-Upload-Allowed: yes is present in the
+ source section of the source control file of the most recent
+ version of a package in unstable or experimental, the Debian
+ archive will accept uploads of this package signed with a key
+ in the Debian Maintainer keyring. See the General
+ Resolution
+ Debian source packages are increasingly developed using VCSs. The
+ purpose of the following fields is to indicate a publicly accessible
+ repository where the Debian source package is developed.
+
+
+ URL of a web interface for browsing the repository.
+
+ The field name identifies the VCS. The field's value uses the
+ version control system's conventional syntax for describing
+ repository locations and should be sufficient to locate the
+ repository used for packaging. Ideally, it also locates the
+ branch used for development of new versions of the Debian
+ package.
+
+ In the case of Git, the value consists of a URL, optionally
+ followed by the word -b and the name of a branch in
+ the indicated repository, following the syntax of the
+ git clone command. If no branch is specified, the
+ packaging should be on the default branch.
+
+ More than one different VCS may be specified for the same
+ package.
+
@@ -3657,7 +3855,7 @@ Checksums-Sha256: 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 + letter S is used in Debian source control files and where C is used in upload control (.changes) files.
@@ -3668,7 +3866,7 @@ Checksums-Sha256:
Broadly speaking the
-
-
+ What follows is a summary of all the ways in which maintainer
+ scripts may be called along with what facilities those scripts
+ may rely on being available at that time. Script names preceded
+ by new- are the scripts from the new version of a
+ package being installed, upgraded to, or downgraded to. Script
+ names preceded by old- are the scripts from the old
+ version of a package that is being upgraded from or downgraded
+ from.
+
-
-
+
+
-
-
+
+
-
-
+ The
The relations allowed are <<, <=,
- =, >= and >> for
- strictly earlier, earlier or equal, exactly equal, later or
- equal and strictly later, respectively. The deprecated
- forms < and > were used to mean
- earlier/later or equal, rather than strictly earlier/later,
- so they should not appear in new packages (though
-
- For binary relationship fields, the architecture restriction
+ For binary relationship fields and the Built-Using
+ field, the architecture restriction
syntax is only supported in the source package control
file
Relationships may also be restricted to a certain set of - architectures using architecture wildcards. The syntax for + architectures using architecture wildcards in the format + described in . The syntax for declaring such restrictions is the same as declaring restrictions using a certain set of architectures without architecture wildcards. For example: @@ -4595,31 +4885,40 @@ Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any]
- For this reason packages in an installation run are usually
- all unpacked first and all configured later; this gives
- later versions of packages with dependencies on later
- versions of other packages the opportunity to have their
- dependencies satisfied.
+ Since Depends only places requirements on the order in
+ which packages are configured, packages in an installation run
+ are usually all unpacked first and all configured later.
+
- In case of circular dependencies, since installation or - removal order honoring the dependency order can't be - established, dependency loops are broken at some point - (based on rules below), and some packages may not be able to - rely on their dependencies being present when being - installed or removed, depending on which side of the break - of the circular dependency loop they happen to be on. If one - of the packages in the loop has no postinst script, then the - cycle will be broken at that package, so as to ensure that - all postinst scripts run with the dependencies properly - configured if this is possible. Otherwise the breaking point - is arbitrary. -
-
- The Depends field thus allows package maintainers
- to impose an order in which packages should be configured.
+ If there is a circular dependency among packages being installed
+ or removed, installation or removal order honoring the
+ dependency order is impossible, requiring the dependency loop be
+ broken at some point and the dependency requirements violated
+ for at least one package. Packages involved in circular
+ dependencies may not be able to rely on their dependencies being
+ configured before they themselves are configured, depending on
+ which side of the break of the circular dependency loop they
+ happen to be on. If one of the packages in the loop has
+ no
@@ -4631,7 +4930,8 @@ Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any] This declares an absolute dependency. A package will not be configured unless all of the packages listed in its Depends field have been correctly - configured. + configured (unless there is a circular dependency as + described above).
@@ -4643,12 +4943,31 @@ Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any]
The Depends field should also be used if the
-
+ Finally, the Depends field should be used if the
+ depended-on package is needed by the
- When the package declaring a pre-dependency is about - to be configured, the pre-dependency will be - treated as a normal Depends, that is, it will - be considered satisfied only if the depended-on - package has been correctly configured. + When the package declaring a pre-dependency is about to + be configured, the pre-dependency will be treated + as a normal Depends. It will be considered + satisfied only if the depended-on package has been + correctly configured. However, unlike + with Depends, Pre-Depends does not + permit circular dependencies to be broken. If a circular + dependency is encountered while attempting to honor + Pre-Depends, the installation will be aborted. +
+ +
+ Pre-Depends are also required if the
+
@@ -4722,10 +5051,10 @@ Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any]
- Pre-Depends are also required if the
-
When one binary package declares that it breaks another,
- When one binary package declares a conflict with another
- using a Conflicts field,
- If one package is to be installed, the other must be removed
- first. If the package being installed is marked as replacing
+ If one package is to be unpacked, the other must be removed
+ first. If the package being unpacked is marked as replacing
(see , but note that Breaks should
normally be used in this case) the one on the system, or the one
on the system is marked as deselected, or both packages are
@@ -4862,7 +5191,7 @@ Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any]
+ Some binary packages incorporate parts of other packages when built + but do not have to depend on those packages. Examples include + linking with static libraries or incorporating source code from + another package during the build. In this case, the source packages + of those other packages are a required part of the complete source + (the binary package is not reproducible without them). +
+ +
+ A Built-Using field must list the corresponding source
+ package for any such binary package incorporated during the build
+
+ A package using the source code from the gcc-4.6-source
+ binary package built from the gcc-4.6 source package would
+ have this field in its control file:
+
+ A package including binaries from grub2 and loadlin would
+ have this field in its control file:
+
During install or upgrade, the preinst is called before - the new files are installed, so calling "ldconfig" is + the new files are unpacked, so calling "ldconfig" is pointless. The preinst of an existing package can also be called if an upgrade fails. However, this happens during the critical time when a shared libs may exist on-disk @@ -5538,7 +5911,7 @@ Replaces: mail-transport-agent ) to ensure that the user only installs one development version at a time (as different development versions are likely to have the same header files in them, which would cause a - filename clash if both were installed). + filename clash if both were unpacked).
@@ -5945,11 +6318,11 @@ install -m644 debian/shlibs.package debian/package/DEBIAN/
- The location of all installed files and directories must
- 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:
+ The location of all files and directories must 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:
+ The additional directory
+ Packages must not assume the
The following directories in the root filesystem are @@ -6039,9 +6437,21 @@ install -m644 debian/shlibs.package debian/package/DEBIAN/ to get access to kernel information.
+ On GNU/Hurd systems, the following additional
+ directories are allowed in the root
+ filesystem:
The version of this document referred here can be
found in the debian-policy package or on
+ The directory
+ Packages must not include files or directories
+ under
-
Packages must not modify the configuration file
- If a package wants to install a job that has to be executed
- via cron, it should place a file with the name of the
- package in one or more of the following directories:
+ If a package wants to install a job that has to be executed via
+ cron, it should place a file named as specified
+ in into one or more of the following
+ directories:
All files installed in any of these directories must be @@ -6944,15 +7378,18 @@ Reloading description configuration...done.
If a certain job has to be executed at some other frequency or
- at a specific time, the package should install a file
-
Unlike
+ The file name of a cron job file should normally match the + name of the package from which it comes. +
+ ++ If a package supplies multiple cron job files files in the + same directory, the file names should all start with the name + of the package (possibly modified as described below) followed + by a hyphen (-) and a suitable suffix. +
+ ++ A cron job file name must not include any period or plus + characters (. or +) characters as this will + cause cron to ignore the file. Underscores (_) + should be used instead of . and + + characters. +
+
- The MIME support policy can be found in the mime-policy
- files in the debian-policy package.
- It is also available from the Debian web mirrors at
-
+ Packages containing such programs must register them
+ with
Please refer to the documentation that comes with the @@ -7649,10 +8123,13 @@ fname () {
You may wish to restrict your script to SUSv3 features plus the
above set when possible so that it may use
@@ -7691,11 +8168,23 @@ fname () {
- In general, symbolic links within a top-level directory
- should be relative, and symbolic links pointing from one
- top-level directory into another should be absolute. (A
- top-level directory is a sub-directory of the root
- directory
@@ -8896,9 +9385,9 @@ name ["syshostname"]:
- Programs that require the non-DFSG-compliant OSF/Motif or
- OpenMotif libraries
- Both Motif-linked versions are dependent - upon non-DFSG-compliant software and thus cannot be - uploaded to the main distribution; if the - software is itself DFSG-compliant it may be uploaded to - the contrib distribution. While known existing - versions of Motif permit unlimited redistribution of - binaries linked against the library (whether statically or - dynamically), it is the package maintainer's - responsibility to determine whether this is permitted by - the license of the copy of Motif in their possession. -
-In addition, the copyright file must say where the upstream - sources (if any) were obtained. It should name the original - authors of the package and the Debian maintainer(s) who were - involved with its creation. + sources (if any) were obtained, and should name the original + authors.
@@ -9586,8 +10039,8 @@ END-INFO-DIR-ENTRY
+ All copyright files must be encoded in UTF-8. +
+ +
+ A specification for a standard, machine-readable format
+ for
+ Use of this format is optional. +
+
- The Debian version of the FSF's GNU hello program is provided
- as an example for people wishing to create Debian
- packages. The Debian
The
@@ -10159,10 +10633,10 @@ END-INFO-DIR-ENTRY
the