X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=policy.sgml;h=0b5fc8b4cfc3b1f523ada13351afc20a881e047f;hb=229a09b599841d8cc4c077d68c4e1f4dff3bc44e;hp=4246954a59bf7d3849bb908c4f96aaad0f4b1ae3;hpb=be728601beaa04416d44dc68126f3e92a275f3dd;p=debian%2Fdebian-policy.git diff --git a/policy.sgml b/policy.sgml index 4246954..0b5fc8b 100644 --- a/policy.sgml +++ b/policy.sgml @@ -90,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 @@ -366,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 @@ -376,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 @@ -404,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 @@ -419,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 @@ -427,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 @@ -439,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 @@ -448,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 @@ -570,8 +569,8 @@ Copyright considerations

- Every package must be accompanied by a verbatim copy of - its copyright and distribution license in the file + Every package must be accompanied by a verbatim copy of its + copyright information and distribution license in the file /usr/share/doc/package/copyright (see for further details).

@@ -690,7 +689,15 @@ ruby, science, shells, sound, tex, text, utils, vcs, video, web, x11, xfce, - zope. + zope. The additional section debian-installer + contains special packages used by the installer and is not used + for normal Debian packages. +

+ +

+ For more information about the sections and their definitions, + see the .

@@ -1611,11 +1618,38 @@

- The date must be in RFC822 format - This is generated by date -R. - ; it must include the time zone specified - numerically, with the time zone name or abbreviation - optionally present as a comment in parentheses. + The date has the following format + This is the same as the format generated by date + -R. + (compatible and with the same semantics of + RFC 2822 and RFC 5322): + day-of-week, dd month yyyy hh:mm:ss +zzzz + where: + + + day-of week is one of: Mon, Tue, Wed, Thu, Fri, Sat, Sun + + + dd is a one- or two-digit day of the month (01-31) + + + month is one of: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, + Sep, Oct, Nov, Dec + + yyyy is the four-digit year (e.g. 2010) + hh is the two-digit hour (00-23) + mm is the two-digit minutes (00-59) + ss is the two-digit seconds (00-60) + + +zzzz or -zzzz is the the time zone offset from Coordinated + Universal Time (UTC). "+" indicates that the time is ahead + of (i.e., east of) UTC and "-" indicates that the time is + behind (i.e., west of) UTC. The first two digits indicate + the hour difference from UTC and the last two digits + indicate the number of additional minutes difference from + UTC. The last two digits must be in the range 00-59. + +

@@ -1639,11 +1673,11 @@ Copyright: debian/copyright

- Every package must be accompanied by a verbatim copy of - its copyright and distribution license in the file + Every package must be accompanied by a verbatim copy of its + copyright information 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.

@@ -1726,14 +1760,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, @@ -1817,21 +1854,28 @@ A package may also provide both of the targets build-arch and build-indep. The build-arch target, if provided, should - perform all the configuration and compilation required - for producing all architecture-dependant binary packages + perform all the configuration and compilation required for + producing all architecture-dependant binary packages (those packages for which the body of the - Architecture field in debian/control - is not all). - Similarly, the build-indep target, if - provided, should perform all the configuration and - compilation required for producing all - architecture-independent binary packages - (those packages for which the body of the - Architecture field in debian/control - is all). + Architecture field in debian/control is + not all). Similarly, the build-indep + target, if provided, should perform all the configuration + and compilation required for producing all + architecture-independent binary packages (those packages + for which the body of the Architecture field + in debian/control is all). The build target should depend on those of the targets build-arch and build-indep that - are provided in the rules file. + are provided in the rules file. + The intent of this split is so that binary-only builds + need not install the dependencies required for + the build-indep target. However, this is not + yet used in practice since dpkg-buildpackage + -B, and therefore the autobuilders, + invoke build rather than build-arch + due to the difficulties in determining whether the + optional build-arch target exists. +

@@ -2379,6 +2423,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.

@@ -2442,8 +2488,6 @@ Package: libc6 The syntax and semantics of the fields are described below.

- -

These fields are used by dpkg-gencontrol to generate control files for binary packages (see below), by @@ -2517,15 +2561,17 @@ Package: libc6 Format (mandatory) Source (mandatory) + Binary + Architecture Version (mandatory) Maintainer (mandatory) Uploaders - Binary - Architecture - Build-Depends et al + Homepage Standards-Version (recommended) + Build-Depends et al + Checksums-Sha1 + and Checksums-Sha256 (recommended) Files (mandatory) - Homepage

@@ -2569,6 +2615,8 @@ Package: libc6 Description (mandatory) Closes Changes (mandatory) + Checksums-Sha1 + and Checksums-Sha256 (recommended) Files (mandatory)

@@ -2688,7 +2736,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 .

@@ -2723,41 +2771,64 @@ Package: libc6 Architecture field can include the following sets of values: - A unique single word identifying a Debian machine - architecture as described in . - all, which indicates an - architecture-independent package. - any, which indicates a package available - for building on any architecture. - source, which indicates a source package. + + A unique single word identifying a Debian machine + architecture as described in . + + + An architecture wildcard identifying a set of Debian + machine architectures, see . + any matches all Debian machine architectures + and is the most frequently used. + + + all, which indicates an + architecture-independent package. + + + source, which indicates a source package. +

In the main debian/control file in the source - package, this field may contain the special value - any, the special value all, or a list of - architectures separated by spaces. If any or - all appear, they 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. + package, this field may contain the special + value all, the special architecture + wildcard any, or a list of specific and wildcard + architectures separated by spaces. If all + or any appears, that value must be the entire + contents of the field. Most packages will use + either all or any. +

+ +

+ Specifying a specific list of architectures indicates that the + source will build an architecture-dependent package only on + architectures included in the list. Specifying a list of + architecture wildcards indicates that the source will build an + architecture-dependent package on only those architectures + that match any of the specified architecture wildcards. + Specifying a list of architectures or architecture wildcards + other than any is for the minority of cases where a + program is not portable or is not useful on some + architectures. 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. + 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 + 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.

@@ -2777,28 +2848,29 @@ Package: libc6

- Specifying a list of architectures indicates that the source - will build an architecture-dependent package, and will only - 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 architectures or architecture wildcards + indicates that the source will build an architecture-dependent + package, and will only work correctly on the listed or + matching architectures. If the source package also builds at + least one architecture-independent package, all will + also be included in the list.

In a .changes file, the Architecture - 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 + 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. all will be present if any architecture-independent packages are being - uploaded. any may never occur in the - Architecture field in the .changes - file. + uploaded. Architecture wildcards such as any must + 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.

@@ -2859,8 +2931,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 @@ -3027,10 +3099,12 @@ Package: libc6 not intended to cope with version numbers containing strings of letters which the package management system cannot interpret (such as ALPHA or pre-), or with - silly orderings (the author of this manual has heard of a - package whose versions went 1.1, 1.2, - 1.3, 1, 2.1, 2.2, - 2 and so forth). + silly orderings. + The author of this manual has heard of a package whose + versions went 1.1, 1.2, 1.3, + 1, 2.1, 2.2, 2 and so + forth. +

@@ -3101,18 +3175,16 @@ Package: libc6

- In a .changes file, the Description field - contains a summary of the descriptions for the packages being - uploaded. -

- -

- The part of the field before the first newline is empty; - thereafter each line has the name of a binary package and - the summary description line from that binary package. - Each line is indented by one space. + In a .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.

- @@ -3164,7 +3236,9 @@ Package: libc6 Date

- This field includes the date the package was built or last edited. + This field includes the date the package was built or last + edited. It must be in the same format as the date + in a debian/changelog entry.

@@ -3229,10 +3303,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 (.).

@@ -3252,7 +3328,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).

@@ -3260,29 +3336,27 @@ Package: libc6 Binary

- This field is a list of 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 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. -

- -

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

@@ -3291,11 +3365,11 @@ Package: libc6

This field appears in the control files of binary packages, - and in the Packages files. It gives an - estimate 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. + 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.

@@ -3310,20 +3384,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 .

@@ -3331,14 +3415,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.

@@ -3354,7 +3444,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 @@ -3384,6 +3474,51 @@ Package: libc6

+ + Checksums-Sha1 + and Checksums-Sha256 + +

+ These 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 + for Checksums-Sha1 and SHA-256 + for Checksums-Sha256. +

+ +

+ Checksums-Sha1 and Checksums-Sha256 are + multiline fields. The first line of the field value (the part + on the same line as Checksums-Sha1: + or Checksums-Sha256:) is always empty. The content + of the field is expressed as continuation lines, one line per + file. Each line consists of the checksum, a space, the file + size, a space, and the file name. For example (from + a .changes file): + +Checksums-Sha1: + 1f418afaa01464e63cc1ee8a66a05f0848bd155c 1276 example_1.0-1.dsc + a0ed1456fad61116f868b1855530dbe948e20f06 171602 example_1.0.orig.tar.gz + 5e86ecf0671e113b63388dac81dd8d00e00ef298 6137 example_1.0-1.debian.tar.gz + 71a0ff7da0faaf608481195f9cf30974b142c183 548402 example_1.0-1_i386.deb +Checksums-Sha256: + ac9d57254f7e835bed299926fd51bf6f534597cc3fcc52db01c4bffedae81272 1276 example_1.0-1.dsc + 0d123be7f51e61c4bf15e5c492b484054be7e90f3081608a5517007bfb1fd128 171602 example_1.0.orig.tar.gz + f54ae966a5f580571ae7d9ef5e1df0bd42d63e27cb505b27957351a495bc6288 6137 example_1.0-1.debian.tar.gz + 3bec05c03974fdecd11d020fc2e8250de8404867a8a2ce865160c250eb723664 548402 example_1.0-1_i386.deb + +

+ +

+ In the .dsc file, these fields should list all + files that make up the source package. In + the .changes file, these fields should list all + files being uploaded. The list of files in these fields + must match the list of files in the Files field. +

+ + @@ -3531,15 +3666,26 @@ Package: libc6 Controlling terminal for maintainer scripts

- The maintainer scripts are guaranteed to run with a - controlling terminal and can interact with the user. - Because these scripts may be executed with standard output - redirected into a pipe for logging purposes, Perl scripts - should set unbuffered output by setting $|=1 so - that the output is printed immediately rather than being - buffered. + Maintainer scripts are not guaranteed to run with a controlling + terminal and may not be able to interact with the user. They + must be able to fall back to noninteractive behavior if no + controlling terminal is available. Maintainer scripts that + prompt via a program conforming to the Debian Configuration + Management Specification (see ) may + assume that program will handle falling back to noninteractive + behavior. +

+ +

+ For high-priority prompts without a reasonable default answer, + maintainer scripts may abort if there is no controlling + terminal. However, this situation should be avoided if at all + possible, since it prevents automated or unattended installs. + In most cases, users will consider this to be a bug in the + package.

+ Exit status @@ -3697,7 +3843,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. @@ -3805,7 +3951,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): @@ -3817,7 +3963,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. @@ -3897,14 +4043,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 @@ -4063,7 +4209,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".

@@ -4233,6 +4379,21 @@ Build-Depends: foo [!i386] | bar [!amd64] bar on all other architectures.

+

+ All fields that specify build-time relationships 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 any architecture + using a kernel other than Linux. +

+

Note that the binary package relationship fields such as Depends appear in one of the binary package @@ -4399,12 +4560,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.

@@ -4461,7 +4622,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".

@@ -4515,7 +4676,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".

@@ -4636,6 +4797,20 @@ Provides: bar will no longer be listed as "owned" by the old package.

+

+ For example, if a package foo is split + into foo and foo-data + starting at version 1.2-3, foo-data should + have the field + +Replaces: foo (<< 1.2-3) + + in its control file. The package foo + doesn't need any special control fields in this example, + although would generally depend on or + recommend foo-data. +

+

If a package is completely replaced in this way, so that dpkg does not know of any files it still @@ -4726,58 +4901,44 @@ Replaces: mail-transport-agent The dependencies and conflicts they define must be satisfied (as defined earlier for binary packages) in order to invoke the targets in debian/rules, as follows: -

- If you make "build-arch" or "binary-arch", you need - Build-Depends. If you make "build-indep" or - "binary-indep", you need Build-Depends and - Build-Depends-Indep. If you make "build" or "binary", - you need both. -

There is no Build-Depends-Arch; this role is essentially - met with Build-Depends. Anyone building the - build-indep and binary-indep targets - is basically assumed to be building the whole package - anyway and so installs all build dependencies. The - autobuilders use dpkg-buildpackage -B, which - calls build (not build-arch, since it - does not yet know how to check for its existence) and - binary-arch. + met with Build-Depends. Anyone building the + build-indep and binary-indep targets is + assumed to be building the whole package, and therefore + installation of all build dependencies is required.

- The purpose of the original split, I recall, was so that - the autobuilders wouldn't need to install extra packages - needed only for the binary-indep targets. But without a - build-arch/build-indep split, this didn't work, since - most of the work is done in the build target, not in the - binary target. + The autobuilders use dpkg-buildpackage -B, which + calls build, not build-arch since it does + not yet know how to check for its existence, and + binary-arch. The purpose of the original split + between Build-Depends and + Build-Depends-Indep was so that the autobuilders + wouldn't need to install extra packages needed only for the + binary-indep targets. But without a build-arch/build-indep + split, this didn't work, since most of the work is done in + the build target, not in the binary target.

- - Build-Depends, Build-Conflicts + clean, build-arch, and + binary-arch - The Build-Depends and - Build-Conflicts fields must be satisfied when - any of the following targets is invoked: - build, clean, binary, - binary-arch, build-arch, - build-indep and binary-indep. + Only the Build-Depends and Build-Conflicts + fields must be satisfied when these targets are invoked. - Build-Depends-Indep, - Build-Conflicts-Indep + build, build-indep, binary, + and binary-indep - The Build-Depends-Indep and - Build-Conflicts-Indep fields must be - satisfied when any of the following targets is - invoked: build, build-indep, - binary and binary-indep. + The Build-Depends, Build-Conflicts, + Build-Depends-Indep, and + Build-Conflicts-Indep fields must be satisfied when + these targets are invoked.

- - @@ -5321,10 +5482,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. @@ -5566,6 +5727,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 @@ -5589,6 +5784,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. +

+

@@ -5634,13 +5838,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.

@@ -5701,9 +5907,10 @@ 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.

@@ -5785,7 +5992,7 @@ rmdir /usr/local/share/emacs 2>/dev/null || true

- 1000-29999: + 1000-59999:

Dynamically allocated user accounts. By default @@ -5796,11 +6003,6 @@ rmdir /usr/local/share/emacs 2>/dev/null || true

- 30000-59999: - -

Reserved.

- - 60000-64999:

@@ -5947,7 +6149,7 @@ rmdir /usr/local/share/emacs 2>/dev/null || true

- + Writing the scripts

@@ -5997,6 +6199,23 @@ rmdir /usr/local/share/emacs 2>/dev/null || true option.

+

+ Be careful of using set -e in init.d + scripts. Writing correct init.d scripts requires + accepting various error exit statuses when daemons are already + running or already stopped without aborting + the init.d script, and common init.d + function libraries are not safe to call with set -e + in effect + /lib/lsb/init-functions, which assists in writing + LSB-compliant init scripts, may fail if set -e is + in effect and echoing status messages to the console fails, + for example. + . For init.d scripts, it's often easier + to not use set -e and instead check the result of + each command separately. +

+

If a service reloads its configuration automatically (as in the case of cron, for example), the @@ -6378,10 +6597,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 (').

@@ -6488,13 +6707,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}. +

@@ -7059,13 +7313,19 @@ strip --strip-unneeded your-lib language currently used to implement it.

- Shell scripts (sh and bash) - should almost certainly start with set -e so that - errors are detected. Every script should use - set -e or check the exit status of every - command. + Shell scripts (sh and bash) other than + init.d scripts should almost certainly start + with set -e so that errors are detected. + init.d scripts are something of a special case, due + to how frequently they need to call commands that are allowed to + fail, and it may instead be easier to check the exit status of + commands directly. See for more + information about writing init.d scripts. +

+

+ Every script should use set -e or check the exit status + of every command.

-

Scripts may assume that /bin/sh implements the SUSv3 Shell Command Language @@ -7204,8 +7464,8 @@ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq Device files

- Packages must not include device files in the package file - tree. + Packages must not include device files or named pipes in the + package file tree.

@@ -7230,6 +7490,18 @@ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq /dev/cu* devices should be changed to use /dev/ttyS*.

+ +

+ Named pipes needed by the package must be created in + the postinst script + It's better to use mkfifo rather + than mknod to create named pipes so that + automated checks for packages incorrectly creating device + files with mknod won't have false positives. + and removed in + the prerm or postrm script as + appropriate. +

@@ -7314,6 +7586,8 @@ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq package is purged. + Obsolete configuration files without local changes may be + removed by the package during upgrade.

@@ -7647,15 +7921,12 @@ endscript security policy by changing the permissions on a binary: they can do this by using dpkg-statoverride, as described below. - Ordinary files installed by dpkg (as - opposed to conffiles and other similar objects) - normally have their permissions reset to the distributed - permissions when the package is reinstalled. However, - the use of dpkg-statoverride overrides this - default behavior. If you use this method, you should - remember to describe dpkg-statoverride in - the package documentation; being a relatively new - addition to Debian, it is probably not yet well-known. + Ordinary files installed by dpkg (as + opposed to conffiles and other similar objects) + normally have their permissions reset to the distributed + permissions when the package is reinstalled. However, + the use of dpkg-statoverride overrides this + default behavior. Another method you should consider is to create a group for people allowed to use the program(s) and make any setuid @@ -7762,9 +8033,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 +

@@ -7779,51 +8058,10 @@ done

If a program needs to specify an architecture specification - string in some place, it should select one of the - strings provided by dpkg-architecture -L. The - strings are in the format - os-arch, though the OS part - is sometimes elided, as when the OS is Linux. -

Currently, the strings are: - i386 ia64 alpha amd64 armeb arm hppa m32r m68k mips - mipsel powerpc ppc64 s390 s390x sh3 sh3eb sh4 sh4eb - sparc darwin-i386 darwin-ia64 darwin-alpha darwin-amd64 - darwin-armeb darwin-arm darwin-hppa darwin-m32r - darwin-m68k darwin-mips darwin-mipsel darwin-powerpc - darwin-ppc64 darwin-s390 darwin-s390x darwin-sh3 - darwin-sh3eb darwin-sh4 darwin-sh4eb darwin-sparc - freebsd-i386 freebsd-ia64 freebsd-alpha freebsd-amd64 - freebsd-armeb freebsd-arm freebsd-hppa freebsd-m32r - freebsd-m68k freebsd-mips freebsd-mipsel freebsd-powerpc - freebsd-ppc64 freebsd-s390 freebsd-s390x freebsd-sh3 - freebsd-sh3eb freebsd-sh4 freebsd-sh4eb freebsd-sparc - kfreebsd-i386 kfreebsd-ia64 kfreebsd-alpha - kfreebsd-amd64 kfreebsd-armeb kfreebsd-arm kfreebsd-hppa - kfreebsd-m32r kfreebsd-m68k kfreebsd-mips - kfreebsd-mipsel kfreebsd-powerpc kfreebsd-ppc64 - kfreebsd-s390 kfreebsd-s390x kfreebsd-sh3 kfreebsd-sh3eb - kfreebsd-sh4 kfreebsd-sh4eb kfreebsd-sparc knetbsd-i386 - knetbsd-ia64 knetbsd-alpha knetbsd-amd64 knetbsd-armeb - knetbsd-arm knetbsd-hppa knetbsd-m32r knetbsd-m68k - knetbsd-mips knetbsd-mipsel knetbsd-powerpc - knetbsd-ppc64 knetbsd-s390 knetbsd-s390x knetbsd-sh3 - knetbsd-sh3eb knetbsd-sh4 knetbsd-sh4eb knetbsd-sparc - netbsd-i386 netbsd-ia64 netbsd-alpha netbsd-amd64 - netbsd-armeb netbsd-arm netbsd-hppa netbsd-m32r - netbsd-m68k netbsd-mips netbsd-mipsel netbsd-powerpc - netbsd-ppc64 netbsd-s390 netbsd-s390x netbsd-sh3 - netbsd-sh3eb netbsd-sh4 netbsd-sh4eb netbsd-sparc - openbsd-i386 openbsd-ia64 openbsd-alpha openbsd-amd64 - openbsd-armeb openbsd-arm openbsd-hppa openbsd-m32r - openbsd-m68k openbsd-mips openbsd-mipsel openbsd-powerpc - openbsd-ppc64 openbsd-s390 openbsd-s390x openbsd-sh3 - openbsd-sh3eb openbsd-sh4 openbsd-sh4eb openbsd-sparc - hurd-i386 hurd-ia64 hurd-alpha hurd-amd64 hurd-armeb - hurd-arm hurd-hppa hurd-m32r hurd-m68k hurd-mips - hurd-mipsel hurd-powerpc hurd-ppc64 hurd-s390 hurd-s390x - hurd-sh3 hurd-sh3eb hurd-sh4 hurd-sh4eb hurd-sparc -

- + string in some place, it should select one of the strings + provided by dpkg-architecture -L. The strings are in + the format os-arch, though the OS + part is sometimes elided, as when the OS is Linux.

@@ -7835,6 +8073,27 @@ done arch-unknown-linux, since the unknown does not look very good.

+ + + Architecture wildcards + +

+ A package may specify an architecture wildcard. Architecture + wildcards are in the format any (which matches every + architecture), os-any, or + 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), with the first component of + the triplet representing the libc and ABI in use, and then + does matching against those triplets. However, such + triplets are an internal implementation detail that should + not be used by packages directly. The libc and ABI portion + is handled internally by the package system based on + the os and cpu. + +

+ @@ -7932,10 +8191,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.

@@ -8549,9 +8808,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 @@ -8749,7 +9008,7 @@ name ["syshostname"]: name="Man-Page-HOWTO">, , the examples created by debmake or dh_make, - the helper programs help2man, or the + the helper program help2man, or the directory /usr/share/doc/man-db/examples.

@@ -8818,15 +9077,6 @@ 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 @@ -8852,9 +9102,13 @@ name ["syshostname"]: 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 hooks. + system now uses dpkg triggers. - This file must not be included in packages. + 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.

@@ -8885,9 +9139,9 @@ END-INFO-DIR-ENTRY * 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. - to the Texinfo source of the document and ensure that the info - documents are rebuilt from source during the package build.

@@ -8940,7 +9194,7 @@ END-INFO-DIR-ENTRY

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 @@ -8994,7 +9248,7 @@ END-INFO-DIR-ENTRY

Every package must be accompanied by a verbatim copy of its - copyright and distribution license in the file + copyright information and distribution license in the file /usr/share/doc/package/copyright. This file must neither be compressed nor be a symbolic link.

@@ -9029,14 +9283,13 @@ END-INFO-DIR-ENTRY

- 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 (versions 1.2 or 1.3) should refer to the corresponding - files under /usr/share/common-licenses, + Packages distributed under 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 (versions 1.2 or 1.3) + should refer to the corresponding files + under /usr/share/common-licenses,

In particular, - /usr/share/common-licenses/BSD, /usr/share/common-licenses/Apache-2.0, /usr/share/common-licenses/Artistic, /usr/share/common-licenses/GPL-2, @@ -9046,7 +9299,14 @@ END-INFO-DIR-ENTRY /usr/share/common-licenses/LGPL-3, /usr/share/common-licenses/GFDL-1.2, and /usr/share/common-licenses/GFDL-1.3 - respectively. + respectively. The University of California BSD license is + also included in base-files as + /usr/share/common-licenses/BSD, but given the + brevity of this license, its specificity to code whose + copyright is held by the Regents of the University of + California, and the frequency of minor wording changes, its + text should be included in the copyright file rather than + referencing this file.

rather than quoting them in the copyright file. @@ -9400,9 +9660,9 @@ END-INFO-DIR-ENTRY

- The maintainer scripts are guaranteed to run with a - controlling terminal and can interact with the user. - See . + The maintainer scripts are not guaranteed to run with a + controlling terminal and may not be able to interact with + the user. See .

@@ -9874,120 +10134,6 @@ END-INFO-DIR-ENTRY

- - - debian/changelog - -

- See . -

- - Defining alternative changelog formats - - -

- It is possible to use a different format to the standard - one, by providing a parser for the format you wish to - use. -

- -

- In order to have dpkg-parsechangelog run your - parser, you must include a line within the last 40 lines - of your file matching the Perl regular expression: - \schangelog-format:\s+([0-9a-z]+)\W The part in - parentheses should be the name of the format. For - example, you might say: - - @@@ changelog-format: joebloggs @@@ - - Changelog format names are non-empty strings of alphanumerics. -

- -

- If such a line exists then dpkg-parsechangelog - will look for the parser as - /usr/lib/dpkg/parsechangelog/format-name - or - /usr/local/lib/dpkg/parsechangelog/format-name; - it is an error for it not to find it, or for it not to - be an executable program. The default changelog format - is dpkg, and a parser for it is provided with - the dpkg package. -

- -

- The parser will be invoked with the changelog open on - standard input at the start of the file. It should read - the file (it may seek if it wishes) to determine the - information required and return the parsed information - to standard output in the form of a series of control - fields in the standard format. By default it should - return information about only the most recent version in - the changelog; it should accept a - -vversion option to return changes - information from all versions present strictly - after version, and it should then be an - error for version not to be present in the - changelog. -

- -

- The fields are: - - Source - Version (mandatory) - Distribution (mandatory) - Urgency (mandatory) - Maintainer (mandatory) - Date - Changes (mandatory) - -

- -

- If several versions are being returned (due to the use - of -v), the urgency value should be of the - highest urgency code listed at the start of any of the - versions requested followed by the concatenated - (space-separated) comments from all the versions - requested; the maintainer, version, distribution and - date should always be from the most recent version. -

- -

- For the format of the Changes field see - . -

- -

- If the changelog format which is being parsed always or - almost always leaves a blank line between individual - change notes these blank lines should be stripped out, - so as to make the resulting output compact. -

- -

- If the changelog format does not contain date or package - name information this information should be omitted from - the output. The parser should not attempt to synthesize - it or find it from other sources. -

- -

- If the changelog does not have the expected format the - parser should exit with a nonzero exit status, rather - than trying to muddle through and possibly generating - incorrect output. -

- -

- A changelog parser may not interact with the user at - all. -

- - - debian/substvars and variable substitutions