X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=policy.sgml;h=bb424ed456a8c602859128e1972c51d59ca35676;hb=fee1838470a56f3f5595dfd949ec01010e85c96e;hp=774c8225313222a6420ae457c5a07f2667053583;hpb=6cfe091b91f402a3c42b6c55b94a1cc701c1ec04;p=debian%2Fdebian-policy.git diff --git a/policy.sgml b/policy.sgml index 774c822..bb424ed 100644 --- a/policy.sgml +++ b/policy.sgml @@ -1090,7 +1090,7 @@ - + Dependencies

@@ -2479,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 @@ -2509,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. @@ -2532,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.

@@ -2565,7 +2610,7 @@ Package: libc6 Source (mandatory) Maintainer (mandatory) Uploaders - DM-Upload-Allowed + DM-Upload-Allowed Section (recommended) Priority (recommended) Build-Depends et al @@ -2600,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. @@ -2614,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. -

- @@ -2671,7 +2706,7 @@ Package: libc6 Version (mandatory) Maintainer (mandatory) Uploaders - DM-Upload-Allowed + DM-Upload-Allowed Homepage Standards-Version (recommended) Build-Depends et al @@ -2682,7 +2717,7 @@ Package: libc6

- The source package control file is generated by + The Debian source control file is generated by dpkg-source when it builds the source archive, from other files in the source package, described above. When unpacking, it is checked against @@ -2822,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.

@@ -2943,34 +2974,42 @@ Package: libc6

- In the source package control file .dsc, this - field may contain either the architecture - wildcard any or a list of architectures and - architecture wildcards separated by spaces. If a list is - given, it may include (or consist solely of) the special + In the Debian source control file .dsc, this + field contains a list of architectures and architecture + wildcards separated by spaces. When the list contains the + architecture wildcard any, the only other value + allowed in the list is all. +

+ +

+ The list 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 + The Architecture field in the Debian source 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 + 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.

@@ -3006,7 +3045,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.

@@ -3242,7 +3281,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:

@@ -3306,8 +3346,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. @@ -3443,7 +3483,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.

@@ -3481,7 +3521,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.

@@ -3491,7 +3531,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 @@ -3501,7 +3541,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).

@@ -3624,7 +3664,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 @@ -3687,7 +3727,7 @@ Checksums-Sha256: 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. + Debian source control files or upload control files.

@@ -3704,7 +3744,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.

@@ -3715,7 +3755,7 @@ Checksums-Sha256: XBS-Comment: I stand between the candle and the star. - then the binary and source package control files will contain the + then the binary and Debian source control files will contain the field Comment: I stand between the candle and the star. @@ -4562,13 +4602,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.

@@ -4587,6 +4627,7 @@ Depends: libc6 (>= 2.2.1), exim | mail-transport-agent architectures. This is indicated in brackets after each individual package name and the optional version specification. The brackets enclose a list of Debian architecture names + in the format described in , separated by whitespace. Exclamation marks may be prepended to each of the names. (It is not permitted for some names to be prepended with exclamation marks while others aren't.) @@ -4654,7 +4695,8 @@ Build-Depends: foo [!i386] | bar [!amd64]

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: @@ -4895,6 +4937,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 . +

@@ -6148,13 +6197,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 @@ -9061,9 +9110,9 @@ name ["syshostname"]: If the window manager complies with , - written by the , add 40 points. @@ -9331,41 +9380,6 @@ name ["syshostname"]: policy (such as for ).

- - - The OSF/Motif and OpenMotif libraries - -

- Programs that require the non-DFSG-compliant OSF/Motif or - OpenMotif libraries - OSF/Motif and OpenMotif are collectively referred to as - "Motif" in this policy document. - - should be compiled against and tested with LessTif (a free - re-implementation of Motif) instead. If the maintainer - judges that the program or programs do not work - sufficiently well with LessTif to be distributed and - supported, but do so when compiled against Motif, then two - versions of the package should be created; one linked - statically against Motif and with -smotif - appended to the package name, and one linked dynamically - against Motif and with -dmotif appended to the - package name. -

- -

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

- @@ -9751,8 +9765,8 @@ END-INFO-DIR-ENTRY /usr/share/doc/package may be a symbolic link to another directory in /usr/share/doc only if the two packages both come from the same source and the - first package Depends on the second. These rules are - important because copyrights must be extractable by + first package Depends on the second. These rules are important + because copyright files must be extractable by mechanical means.

@@ -11268,4 +11282,4 @@ END-INFO-DIR-ENTRY - +