X-Git-Url: https://git.donarmstrong.com/?p=debian%2Fdebian-policy.git;a=blobdiff_plain;f=policy.sgml;h=404dc7373f80cdc20bf793e064d7163e3885518f;hp=50c0289fa7f2d682cbc40d7e5bb50c85a937323a;hb=HEAD;hpb=5da78a06d531b211ab83cc50f7e988a4f559be5b diff --git a/policy.sgml b/policy.sgml index 50c0289..404dc73 100644 --- a/policy.sgml +++ b/policy.sgml @@ -229,9 +229,8 @@ Russ Allbery Bill Allombert - Andrew McMillan - Manoj Srivastava - Colin Watson + Andreas Barth + Jonathan Nieder

@@ -1274,7 +1273,7 @@ zope.

Essential is defined as the minimal set of functionality that must be available and usable on the system at all times, even - when packages are in an unconfigured (but unpacked) state. + when packages are in the "Unpacked" state. Packages are tagged essential for a system using the Essential control field. The format of the Essential control field is described in dpkg to stave off boredom on - the part of a user installing many packages. This means, - amongst other things, using the --quiet option on - install-info. + the part of a user installing many packages. This means, + amongst other things, not passing the --verbose + option to update-alternatives.

@@ -1361,7 +1360,7 @@ zope. installed together. If update-alternatives is not used, then each package must use Conflicts to ensure that other packages are - de-installed. (In this case, it may be appropriate to + removed. (In this case, it may be appropriate to specify a conflict against earlier versions of something that previously did not use update-alternatives; this is an exception to @@ -1746,11 +1745,14 @@ zope.

The maintainer name and email address used in the changelog - should be the details of the person uploading this - version. They are not necessarily those of the - usual package maintainer. - If the developer uploading the package is not one of the usual - maintainers of the package (as listed in + should be the details of the person who prepared this release of + the package. They are not necessarily those of the + uploader or usual package maintainer. + In the case of a sponsored upload, the uploader signs the + files, but the changelog maintainer name and address are those + of the person who prepared this release. If the preparer of + the release is not one of the usual maintainers of the package + (as listed in the Maintainer or Uploaders control fields of the package), the first line of the changelog is @@ -1916,7 +1918,8 @@ zope.

The following targets are required and must be implemented by debian/rules: clean, binary, - binary-arch, binary-indep, and build. + binary-arch, binary-indep, build, + build-arch and build-indep. These are the targets called by dpkg-buildpackage.

@@ -1928,6 +1931,10 @@ zope. any target that these targets depend on must also be non-interactive.

+

+ For packages in the main archive, no required targets + may attempt network access. +

The targets are as follows: @@ -2366,8 +2373,7 @@ endif This is an optional, recommended configuration file for the uscan utility which defines how to automatically scan ftp or http sites for newly available updates of the - package. This is used - by and other Debian QA + package. This is used Debian QA tools to help with quality control and maintenance of the distribution as a whole.

@@ -2541,7 +2547,7 @@ endif 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, #. + character, #, nor with the hyphen character, -.

@@ -2556,7 +2562,9 @@ Package: libc6 the field name is Package and the field value libc6.

- +

Empty field values are only permitted in source package control files + (debian/control). Such fields are ignored. +

A paragraph must not contain more than one instance of a particular field name. @@ -2699,6 +2707,7 @@ Package: libc6 file. These tools are responsible for removing the line breaks from such fields when using fields from debian/control to generate other control files. + They are also responsible for discarding empty fields.

@@ -2758,6 +2767,7 @@ Package: libc6 Uploaders Homepage Vcs-Browser, Vcs-Git, et al. + Dgit Standards-Version (recommended) Build-Depends et al Package-List (recommended) @@ -3672,7 +3682,7 @@ Files:

The special value byhand for the section in a .changes file indicates that the file in question - is not an ordinary package file and must by installed by + is not an ordinary package file and must be installed by hand by the distribution maintainers. If the section is byhand the priority should be -.

@@ -3839,6 +3849,26 @@ Checksums-Sha256: this value is assumed for paragraphs lacking this field.

+ + + Dgit + +

+ Folded field containing a single git commit hash, presented in + full, followed optionally by whitespace and other data to be + defined in future extensions. +

+ +

+ Declares that the source package corresponds exactly to a + referenced commit in a Git repository available at the canonical + location called dgit-repos, used by dgit, a + bidirectional gateway between the Debian archive and Git. The + commit is reachable from at least one reference whose name matches + refs/dgit/*. See the manual page of dgit for + further details. +

+ @@ -3969,8 +3999,7 @@ Checksums-Sha256: Programs called from maintainer scripts should not normally have a path prepended to them. Before installation is started, the package management system checks to see if the - programs ldconfig, - start-stop-daemon, install-info, + programs ldconfig, start-stop-daemon, and update-rc.d can be found via the PATH environment variable. Those programs, and any other program that one would expect to be in the @@ -4069,7 +4098,7 @@ Checksums-Sha256: pre-dependencies (Pre-Depends) may be assumed to be available. Pre-dependencies will have been configured at least once, but at the time the preinst is - called they may only be in an unpacked or "Half-Configured" + called they may only be in an "Unpacked" or "Half-Configured" state if a previous version of the pre-dependency was completely configured and has not been removed since then. @@ -4083,7 +4112,7 @@ Checksums-Sha256: partly from the new version or partly missing, so the script cannot rely on files included in the package. Package dependencies may not be available. Pre-dependencies will be - at least unpacked following the same rules as above, except + at least "Unpacked" following the same rules as above, except they may be only "Half-Installed" if an upgrade of the pre-dependency failed. This can happen if the new version of the package no @@ -4102,7 +4131,7 @@ Checksums-Sha256: most-recently-configured-version The files contained in the package will be unpacked. All - package dependencies will at least be unpacked. If there + package dependencies will at least be "Unpacked". If there are no circular dependencies involved, all package dependencies will be configured. For behavior in the case of circular dependencies, see the discussion @@ -4126,7 +4155,7 @@ Checksums-Sha256: will have previously been configured and not removed. However, dependencies may not be configured or even fully unpacked in some error situations. - For example, suppose packages foo and bar are installed + For example, suppose packages foo and bar are "Installed" with foo depending on bar. If an upgrade of bar were started and then aborted, and then an attempt to remove foo failed because its prerm script failed, @@ -4163,7 +4192,7 @@ Checksums-Sha256: at least "Half-Installed". All package dependencies will at least be "Half-Installed" and will have previously been configured and not removed. If there was no error, all - dependencies will at least be unpacked, but these actions + dependencies will at least be "Unpacked", but these actions may be called in various error states where dependencies are only "Half-Installed" due to a partial upgrade. @@ -4192,7 +4221,7 @@ Checksums-Sha256: The postrm script is called after the package's files have been removed or replaced. The package whose postrm is being called may have - previously been deconfigured and only be unpacked, at which + previously been deconfigured and only be "Unpacked", at which point subsequent package changes do not consider its dependencies. Therefore, all postrm actions may only rely on essential packages and must gracefully skip @@ -4255,7 +4284,7 @@ fi - If a version of the package is already installed, call + If a version of the package is already "Installed", call old-prerm upgrade new-version @@ -4370,7 +4399,7 @@ fi Otherwise, if the package had some configuration files from a previous version installed (i.e., it - is in the "configuration files only" state): + is in the "Config-Files" state): new-preinst install old-version @@ -4395,7 +4424,7 @@ fi If the error-unwind fails, the package is in a "Half-Installed" phase, and requires a reinstall. If the error unwind works, the - package is in a not installed state. + package is in the "Not-Installed" state. @@ -4533,7 +4562,7 @@ fi It is noted in the status database as being in a - sane state, namely not installed (any conffiles + sane state, namely "Not-Installed" (any conffiles it may have are ignored, rather than being removed by dpkg). Note that disappearing packages do not have their prerm @@ -4559,7 +4588,7 @@ fi

The new package's status is now sane, and recorded as - "unpacked". + "Unpacked".

@@ -4596,7 +4625,7 @@ fi

No attempt is made to unwind after errors during configuration. If the configuration fails, the package is in - a "Failed Config" state, and an error message is generated. + a "Half-Configured" state, and an error message is generated.

@@ -4716,8 +4745,8 @@ fi dependencies on other packages, the package names listed may also include lists of alternative package names, separated by vertical bar (pipe) symbols |. In such a case, - if any one of the alternative packages is installed, that - part of the dependency is considered to be satisfied. + that part of the dependency can be satisfied by any one of + the alternative packages.

@@ -5048,11 +5077,11 @@ Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any] 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 in the "Half-Configured" + package(s) are only in the "Unpacked" or 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 + previously-configured and currently "Unpacked" or "Half-Configured" versions must satisfy any version clause in the Pre-Depends field.

@@ -5407,7 +5436,7 @@ Depends: foo-data (>= 1.2-3) dpkg does not know of any files it still contains, it is considered to have "disappeared". It will be marked as not wanted on the system (selected for - removal) and not installed. Any conffiles + removal) and "Not-Installed". Any conffiles details noted for the package will be ignored, as they will have been taken over by the overwriting package. The package's postrm script will be run with a @@ -6897,6 +6926,20 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1) exceptions to the FHS apply: + +

+ The FHS requirement that architecture-independent + application-specific static files be located in + /usr/share is relaxed to a suggestion. + + In particular, a subdirectory of /usr/lib may + be used by a package (or a collection of packages) to hold a + mixture of architecture-independent and + architecture-dependent files. However, when a directory is + entirely composed of architecture-independent files, it + should be located in /usr/share. +

+

The optional rules related to user specific @@ -6938,8 +6981,18 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1) 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. + architectures, as part of multiarch. + +

+

+ The requirement for C and C++ headers files to be + accessible through the search path + /usr/include/ is amended, permitting files to + be accessible through the search path + /usr/include/triplet where + triplet is as above. + This is necessary for architecture-dependant headers + file to coexist in a multiarch setup.

@@ -7000,15 +7053,29 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1) stable release of Debian supports /run.

- + +

+ The /sys directory in the root filesystem is + additionally allowed. This directory is used as + mount point to mount virtual filesystems to get access to + kernel information. +

+ +

- 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. + The /var/www directory is additionally allowed.

- + + +

+ The requirement for /usr/local/lib<qual> + to exist if /lib<qual> or + /usr/lib<qual> exists (where + lib<qual> is a variant of + lib such as lib32 or + lib64) is removed. +

+

On GNU/Hurd systems, the following additional @@ -7289,6 +7356,35 @@ rmdir /usr/local/share/emacs 2>/dev/null || true 65535: + +

+ This value must not be used, because it was + the error return sentinel value when uid_t + was 16 bits. +

+ + + 65536-4294967293: + +

+ Dynamically allocated user accounts. By + default adduser will not allocate UIDs + and GIDs in this range, to ease compatibility with + legacy systems where uid_t is still 16 + bits. +

+ + + 4294967294: + +

+ (uid_t)(-2) == (gid_t)(-2) must not be + used, because it is used as the anonymous, unauthenticated + user by some NFS implementations. +

+ + + 4294967295:

(uid_t)(-1) == (gid_t)(-1) must @@ -8412,7 +8508,17 @@ fi renamed. If a consensus cannot be reached, both programs must be renamed.

- +

+ Binary executables must not be statically linked with the GNU C + library, since this prevents the binary from benefiting from + fixes and improvements to the C library without being rebuilt + and complicates security updates. This requirement may be + relaxed for binary executables whose intended purpose is to + diagnose and fix the system in situations where the GNU C + library may not be usable (such as system recovery shells or + utilities like ldconfig) or for binary executables where the + security benefits of static linking outweigh the drawbacks. +

By default, when a package is being built, any binaries created should include debugging information, as well as @@ -8821,6 +8927,7 @@ fname () { would point to /srv/run rather than the intended target. + Symbolic links must not traverse above the root directory.

@@ -8853,7 +8960,9 @@ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq

- A symbolic link pointing to a compressed file should always + A symbolic link pointing to a compressed file (in the sense + that it is meant to be uncompressed with unzip + or zless etc.) should always have the same file extension as the referenced file. (For example, if a file foo.gz is referenced by a symbolic link, the filename of the link has to end with @@ -8987,8 +9096,10 @@ 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. + Obsolete configuration files without local changes should be + removed by the package during upgrade. + The dpkg-maintscript-helper tool, available from the + dpkg package, can help for this task.

@@ -9471,6 +9582,23 @@ done

+ + + File names + +

+ The name of the files installed by binary packages in the system PATH + (namely /bin, /sbin, /usr/bin, + /usr/sbin and /usr/games) must be encoded in + ASCII. +

+ +

+ The name of the files and directories installed by binary packages + outside the system PATH must be encoded in UTF-8 and should be + restricted to ASCII when it is possible to do so. +

+ @@ -9657,36 +9785,20 @@ done Cgi-bin executable files are installed in the directory -/usr/lib/cgi-bin/cgi-bin-name +/usr/lib/cgi-bin - or a subdirectory of that directory, and should be - referred to as + or a subdirectory of that directory, and the script -http://localhost/cgi-bin/cgi-bin-name +/usr/lib/cgi-bin/.../cgi-bin-name - (possibly with a subdirectory name - before cgi-bin-name). - - - -

Access to HTML documents

- -

- HTML documents for a package are stored in - /usr/share/doc/package - and can be referred to as + should be referred to as -http://localhost/doc/package/filename +http://localhost/cgi-bin/.../cgi-bin-name -

+ -

- The web server should restrict access to the document - tree so that only clients on the same host can read - the documents. If the web server does not support such - access controls, then it should not provide access at - all, or ask about providing access during installation. -

+ +

(Deleted)

 @@ -9714,7 +9826,7 @@ http://localhost/doc/package/filename doc-base package. If access to the web document root is unavoidable then use -/var/www +/var/www/html as the Document Root. This might be just a symbolic link to the location where the system administrator @@ -10497,18 +10609,23 @@ name ["syshostname"]:

The install-info program maintains a directory of - installed info documents in /usr/share/info/dir for - the use of info readers. - It was previously necessary for packages installing info - documents to run install-info from maintainer - scripts. This is no longer necessary. The installation - system now uses dpkg triggers. - - This file must not be included in packages. Packages containing - info documents should depend on dpkg (>= 1.15.4) | - install-info to ensure that the directory file is properly - rebuilt during partial upgrades from Debian 5.0 (lenny) and - earlier. + installed info documents in /usr/share/info/dir for the + use of info readers. This file must not be included in packages + other than install-info. +

+ +

+ install-info is automatically invoked when + appropriate using dpkg triggers. Packages other than + install-info should not invoke + install-info directly and should not + depend on, recommend, or suggest install-info + for this purpose. +

+ +

+ Info readers requiring the /usr/share/info/dir file + should depend on install-info.

@@ -10545,45 +10662,77 @@ END-INFO-DIR-ENTRY

- + Additional documentation

- Any additional documentation that comes with the package may - be installed at the discretion of the package maintainer. - Plain text documentation should be installed in the directory - /usr/share/doc/package, where - package is the name of the package, and - compressed with gzip -9 unless it is small. -

+ Any additional documentation that comes with the package may be + installed at the discretion of the package maintainer. It is + often a good idea to include text information files + (READMEs, FAQs, and so forth) that come with the + source package in the binary package. However, you don't need + to install the instructions for building and installing the + package, of course! +

- If a package comes with large amounts of documentation which - many users of the package will not require you should create - a separate binary package to contain it, so that it does not - take up disk space on the machines of users who do not need - or want it installed.

+ Plain text documentation should be compressed with gzip + -9 unless it is small. +

+ +

+ If a package comes with large amounts of documentation that many + users of the package will not require, you should create a + separate binary package to contain it so that it does not take + up disk space on the machines of users who do not need or want + it installed. As a special case of this rule, shared library + documentation of any appreciable size should always be packaged + with the library development package () + or in a separate documentation package, since shared libraries + are frequently installed as dependencies of other packages by + users who have little interest in documentation of the library + itself. The documentation package for the + package package is conventionally + named package-doc + (or package-doc-language-code if there are + separate documentation packages for multiple languages). +

- It is often a good idea to put text information files - (READMEs, changelogs, and so forth) that come with - the source package in /usr/share/doc/package - in the binary package. However, you don't need to install - the instructions for building and installing the package, of - course!

+ Additional documentation included in the package should be + installed under /usr/share/doc/package. + If the documentation is packaged separately, + as package-doc for example, it may be installed under + either that path or into the documentation directory for the + separate documentation package + (/usr/share/doc/package-doc in this + example). However, installing the documentation into the + documentation directory of the main package is preferred since + it is independent of the packaging method and will be easier for + users to find. +

+ +

+ Any separate package providing documentation must still install + standard documentation files in its + own /usr/share/doc directory as specified in the + rest of this policy. See, for example, + and . +

Packages must not require the existence of any files in /usr/share/doc/ in order to function - The system administrator should be able to - delete files in /usr/share/doc/ without causing - any programs to break. - . - Any files that are referenced by programs but are also - useful as stand alone documentation should be installed under - /usr/share/package/ with symbolic links from - /usr/share/doc/package. + The system administrator should be able to delete files + in /usr/share/doc/ without causing any programs + to break. + . Any files that are used or read by programs but + are also useful as stand alone documentation should be installed + elsewhere, such as + under /usr/share/package/, and then + included via symbolic links + in /usr/share/doc/package.

@@ -10603,18 +10752,6 @@ END-INFO-DIR-ENTRY

- -

- Former Debian releases placed all additional documentation - in /usr/doc/package. This has been - changed to /usr/share/doc/package, - and packages must not put documentation in the directory - /usr/doc/package. - At this phase of the transition, we no longer require a - symbolic link in /usr/doc/. At a later point, - policy shall change to make the symbolic links a bug. - -

@@ -10625,16 +10762,16 @@ END-INFO-DIR-ENTRY via HTML.

- If your package comes with extensive documentation in a + If the package comes with extensive documentation in a markup format that can be converted to various other formats you should if possible ship HTML versions in a binary - package, in the directory - /usr/share/doc/appropriate-package or - its subdirectories. - The rationale: The important thing here is that HTML - docs should be available in some package, not - necessarily in the main binary package. + package. + Rationale: The important thing here is that HTML + documentation should be available from some + binary package. + The documentation must be installed as specified in + .

@@ -12043,6 +12180,11 @@ END-INFO-DIR-ENTRY there is a time, after it has been diverted but before dpkg has installed the new version, when the file does not exist.

+ +

+ Do not attempt to divert a conffile, as dpkg does not + handle it well. +