X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=policy.sgml;h=91173a5d8dc75381d63d02ea5070944ea9e4b513;hb=f26c91ed1486d2a7952ed0adf1b0632d193dbc67;hp=25a5fe644f09f3cfd7760b8f926bf2ccc0e1daa5;hpb=0657d7bbc96bd322cc798968cd2065b6465add0a;p=debian%2Fdebian-policy.git diff --git a/policy.sgml b/policy.sgml index 25a5fe6..91173a5 100644 --- a/policy.sgml +++ b/policy.sgml @@ -15,7 +15,7 @@ This manual describes the policy requirements for the Debian - GNU/Linux distribution. This includes the structure and + distribution. This includes the structure and contents of the Debian archive and several design issues of the operating system, as well as technical requirements that each package must satisfy to be included in the distribution. @@ -50,7 +50,7 @@

A copy of the GNU General Public License is available as - /usr/share/common-licenses/GPL in the Debian GNU/Linux + /usr/share/common-licenses/GPL in the Debian distribution or on the World Wide Web at . You can also @@ -68,7 +68,7 @@ Scope

This manual describes the policy requirements for the Debian - GNU/Linux distribution. This includes the structure and + distribution. This includes the structure and contents of the Debian archive and several design issues of the operating system, as well as technical requirements that each package must satisfy to be included in the @@ -218,12 +218,13 @@ The actual editing is done by a group of maintainers that have no editorial powers. These are the current maintainers: - - Julian Gilbey - Branden Robinson - Josip Rodin - Manoj Srivastava - + + Russ Allbery + Bill Allombert + Andrew McMillan + Manoj Srivastava + Colin Watson +

@@ -314,7 +315,7 @@ The Debian Archive

- The Debian GNU/Linux system is maintained and distributed as a + The Debian system is maintained and distributed as a collection of packages. Since there are so many of them (currently well over 15000), they are split into sections and given priorities to simplify @@ -348,8 +349,7 @@

- The main archive area forms the Debian GNU/Linux - distribution. + The main archive area forms the Debian distribution.

@@ -465,6 +465,20 @@ The main archive area +

+ 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 + See for + more about what we mean by free software. + . +

+

Every package in main must comply with the DFSG (Debian Free Software Guidelines). @@ -496,6 +510,13 @@ The contrib archive area +

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

@@ -514,7 +535,6 @@

-

Examples of packages which would be included in contrib are: @@ -536,6 +556,15 @@ The non-free archive area +

+ 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 @@ -796,7 +825,7 @@ Binary packages

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

@@ -1168,7 +1197,7 @@

The base system is a minimum subset of the Debian - GNU/Linux system that is installed before everything else + 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. @@ -2450,19 +2479,26 @@ endif fields The paragraphs are also sometimes referred to as stanzas. . - The paragraphs are separated by blank lines. Some control + The paragraphs are separated by empty lines. Parsers may accept + lines consisting solely of spaces and tabs as paragraph + separators, but control files should use empty 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.) + refer to binary packages generated from the source.) The + ordering of the paragraphs in control files is significant.

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 + then the data/value associated with that field. The field + name is composed of printable ASCII characters (i.e., + characters that have values between 33 and 126, inclusive) + except colon and must not with a begin with #. 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 @@ -2480,21 +2516,51 @@ Package: libc6

- 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: + + simple + + The field, including its value, must be a single line. Folding + of the field is not permitted. This is the default field type + if the definition of the field does not specify a different + type. + + folded + + The value of a folded field is a logical line that may span + several lines. The lines after the first are called + continuation lines and must start with a space or a tab. + Whitespace, including any newlines, is not significant in the + field values of folded fields. + This folding method is similar to RFC 5322, allowing control + files that contain only one paragraph and no multiline fields + to be read by parsers written for RFC 5322. + + + multiline + + The value of a multiline field may comprise multiple continuation + lines. The first line of the value, the part on the same line as + the field name, often has special significance or may have to be + empty. Other lines are added following the same syntax as the + continuation lines the folded fields. Whitespace, including newlines, + is significant in the values of multiline 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. @@ -2503,9 +2569,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 + (debian/control). These comment lines are ignored, even + between two continuation lines. They do not end logical lines.

@@ -2536,6 +2610,7 @@ Package: libc6 Source (mandatory) Maintainer (mandatory) Uploaders + DM-Upload-Allowed Section (recommended) Priority (recommended) Build-Depends et al @@ -2570,8 +2645,8 @@ Package: libc6 .changes file to accompany the upload, and by dpkg-source when it creates the .dsc source control file as part of a source - archive. Many fields are permitted to span multiple lines in - debian/control but not in any other control + archive. Some fields are folded in debian/control, + but not in any other control file. These tools are responsible for removing the line breaks from such fields when using fields from debian/control to generate other control files. @@ -2584,16 +2659,6 @@ Package: libc6 when they generate output control files. 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. -

- @@ -2641,6 +2706,7 @@ Package: libc6 Version (mandatory) Maintainer (mandatory) Uploaders + DM-Upload-Allowed Homepage Standards-Version (recommended) Build-Depends et al @@ -2791,11 +2857,7 @@ Package: libc6

- Any parser that interprets the Uploaders field in - debian/control must permit it to span multiple - lines. Line breaks in an Uploaders field that spans multiple - lines are not significant and the semantics of the field are - the same as if the line breaks had not been present. + The Uploaders field in debian/control can be folded.

@@ -2975,7 +3037,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.

@@ -3211,7 +3273,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:

@@ -3275,8 +3338,8 @@ Package: libc6 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 + always empty. It is a multiline field, with 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. @@ -3412,7 +3475,7 @@ Package: libc6 Changes

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

@@ -3450,7 +3513,7 @@ Package: libc6 Binary

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

@@ -3460,7 +3523,7 @@ Package: libc6 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 + . 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 @@ -3470,7 +3533,7 @@ Package: libc6

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. + whitespace (not commas).

@@ -3593,7 +3656,7 @@ Files: and Checksums-Sha256

- 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 @@ -3632,6 +3695,21 @@ Checksums-Sha256: must match the list of files in the Files field.

+ + + DM-Upload-Allowed + +

+ The most recent version of a package uploaded to unstable or + experimental must include the field DM-Upload-Allowed: + yes in the source section of its source control file for + the Debian archive to accept uploads signed with a key in the + Debian Maintainer keyring. See the General + Resolution for more + details. +

+ @@ -3981,7 +4059,7 @@ fi in postrm purges the debconf configuration for the package if debconf is installed. - + new-postrm failed-upgrade @@ -4516,13 +4594,13 @@ fi specification subject to the rules in , and must appear where it's necessary to disambiguate; it is not otherwise significant. All of the - relationship fields may span multiple lines. For + relationship fields can only be folded in source package control files. For consistency and in case of future changes to dpkg it is recommended that a single space be used after a version relationship and before a version number; it is also conventional to put a single space after each comma, on either side of each vertical bar, and before - each open parenthesis. When wrapping a relationship field, it + each open parenthesis. When opening a continuation line in a relationship field, it is conventional to do so after a comma and before the space following that comma.

@@ -4849,6 +4927,13 @@ Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any] installation would hamper the ability of the system to continue with any upgrade that might be in progress.

+ +

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

@@ -5487,12 +5572,9 @@ Replaces: mail-transport-agent library directories of the dynamic linker (which are currently /usr/lib and /lib) or a directory that is listed in /etc/ld.so.conf - These are currently - - /usr/local/lib - /usr/lib/libc5-compat - /lib/libc5-compat - + These are currently /usr/local/lib plus + directories under /lib and /usr/lib + matching the multiarch triplet for the system architecture. must use ldconfig to update the shared library system. @@ -6105,13 +6187,13 @@ install -m644 debian/shlibs.package debian/package/DEBIAN/ /lib/triplet and /usr/lib/triplet, where triplet is the value returned by - dpkg-architecture -qDEB_HOST_GNU_TYPE for the + dpkg-architecture -qDEB_HOST_MULTIARCH 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. + libraries to /usr/lib/i386-linux-gnu. This is necessary in order to reserve the directories for use in cross-installation of library packages from other @@ -6161,9 +6243,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: /hurd + and /servers. + These directories are used to store translators and as + a set of standard names for mount points, + respectively. + +

+ -

+

The version of this document referred here can be found in the debian-policy package or on syshostname"]: If the window manager complies with , - written by the , add 40 points. @@ -9423,13 +9517,13 @@ name ["syshostname"]: maintainer of the package is allowed to write this bug report themselves, if they so desire). Do not close the bug report until a proper man page is available. - It is not very hard to write a man page. See the + It is not very hard to write a man page. See the , - , the examples - created by debmake or dh_make, - the helper program help2man, or the - directory /usr/share/doc/man-db/examples. + , the examples created + by dh_make, the helper + program help2man, or the + directory /usr/share/doc/man-db/examples.

@@ -9683,8 +9777,7 @@ END-INFO-DIR-ENTRY

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. + part of the Debian distribution and briefly explain why.

@@ -9855,9 +9948,8 @@ END-INFO-DIR-ENTRY dpkg is a suite of programs for creating binary package files and installing and removing them on Unix systems. - dpkg is targeted primarily at Debian - GNU/Linux, but may work on or be ported to other - systems. + dpkg is targeted primarily at Debian, but may + work on or be ported to other systems.

@@ -9902,13 +9994,10 @@ END-INFO-DIR-ENTRY

- The Debian version of the FSF's GNU hello program is provided - as an example for people wishing to create Debian - packages. The Debian debmake package is - recommended as a very helpful tool in creating and maintaining - Debian packages. However, while the tools and examples are - helpful, they do not replace the need to read and follow the - Policy and Programmer's Manual.

+ The Debian version of the FSF's GNU hello program is provided as + an example for people wishing to create Debian packages. However, + while the examples are helpful, they do not replace the need to + read and follow the Policy and Programmer's Manual.