X-Git-Url: https://git.donarmstrong.com/?p=debian%2Fdebian-policy.git;a=blobdiff_plain;f=policy.sgml;h=404dc7373f80cdc20bf793e064d7163e3885518f;hp=57caf5dc68290d9bb2c86e6352ec8a58ed7be8a2;hb=HEAD;hpb=bfd59d44ff9e6362e19e88d3582ed5ee7e569c09 diff --git a/policy.sgml b/policy.sgml index 57caf5d..404dc73 100644 --- a/policy.sgml +++ b/policy.sgml @@ -158,6 +158,14 @@ distributed in some other way or is intended for local use only.

+ +

+ udebs (stripped-down binary packages used by the Debian Installer) do + not comply with all of the requirements discussed here. See the + for more + information about them. +

@@ -221,9 +229,8 @@ Russ Allbery Bill Allombert - Andrew McMillan - Manoj Srivastava - Colin Watson + Andreas Barth + Jonathan Nieder

@@ -714,21 +721,62 @@

The Debian archive maintainers provide the authoritative list of sections. At present, they are: - admin, cli-mono, comm, database, - devel, debug, doc, editors, - education, electronics, embedded, - fonts, games, gnome, graphics, - gnu-r, gnustep, hamradio, haskell, - httpd, interpreters, introspection, - java, kde, kernel, libs, - libdevel, lisp, localization, - mail, math, metapackages, misc, - net, news, ocaml, oldlibs, - otherosfs, perl, php, python, - ruby, science, shells, sound, - tex, text, utils, vcs, - video, web, x11, xfce, - zope. The additional section debian-installer +admin, +cli-mono, +comm, +database, +debug, +devel, +doc, +editors, +education, +electronics, +embedded, +fonts, +games, +gnome, +gnu-r, +gnustep, +graphics, +hamradio, +haskell, +httpd, +interpreters, +introspection, +java, +kde, +kernel, +libdevel, +libs, +lisp, +localization, +mail, +math, +metapackages, +misc, +net, +news, +ocaml, +oldlibs, +otherosfs, +perl, +php, +python, +ruby, +science, +shells, +sound, +tasks, +tex, +text, +utils, +vcs, +video, +web, +x11, +xfce, +zope. + The additional section debian-installer contains special packages used by the installer and is not used for normal Debian packages.

@@ -1225,7 +1273,7 @@

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.

@@ -1312,7 +1360,7 @@ 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 @@ -1688,7 +1736,7 @@ /closes:\s*(?:bug)?\#?\s?\d+(?:,\s*(?:bug)?\#?\s?\d+)*/i Then all of the bug numbers listed will be closed by the - archive maintenance script (katie) using the + archive maintenance software (dak) using the version of the changelog entry. This information is conveyed via the Closes field @@ -1697,11 +1745,14 @@

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 @@ -1867,7 +1918,8 @@

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.

@@ -1879,6 +1931,10 @@ 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: @@ -1947,51 +2003,33 @@

- build-arch (optional), - build-indep (optional) + build-arch (required), + build-indep (required)

- A package may also provide one or both of the targets - build-arch and build-indep. - The build-arch target, if provided, should + The build-arch target must 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 + target must 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). -

- -

- If build-arch or build-indep targets are - provided in the rules file, the build target + The build target should either depend on those targets or take the same actions as invoking those targets would perform. - 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. + This split allows binary-only builds to not install the + dependencies required for the build-indep + target and skip any resource-intensive build tasks that + are only required when building architecture-independent + binary packages.

-

- If one or both of the targets build-arch and - build-indep are not provided, then invoking - debian/rules with one of the not-provided - targets as arguments should produce a exit status code - of 2. Usually this is provided automatically by make - if the target is missing. -

-

The build-arch and build-indep targets must not do anything that might require root privilege. @@ -2130,7 +2168,7 @@

The architectures we build on and build for are determined by make variables using the - utility dpkg-architecture. + utility dpkg-architecture. You can determine the Debian architecture and the GNU style architecture specification string for the build architecture as well as for the host architecture. The build architecture is @@ -2335,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.

@@ -2510,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, -.

@@ -2525,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. @@ -2626,12 +2665,12 @@ Package: libc6 Source (mandatory) Maintainer (mandatory) Uploaders - DM-Upload-Allowed Section (recommended) Priority (recommended) Build-Depends et al Standards-Version (recommended) Homepage + Vcs-Browser, Vcs-Git, et al.

@@ -2647,6 +2686,8 @@ Package: libc6 Depends et al Description (mandatory) Homepage + Built-Using + Package-Type

@@ -2666,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.

@@ -2702,6 +2744,7 @@ Package: libc6 Maintainer (mandatory) Description (mandatory) Homepage + Built-Using

@@ -2722,12 +2765,14 @@ Package: libc6 Version (mandatory) Maintainer (mandatory) Uploaders - DM-Upload-Allowed Homepage + Vcs-Browser, Vcs-Git, et al. + Dgit Standards-Version (recommended) Build-Depends et al + Package-List (recommended) Checksums-Sha1 - and Checksums-Sha256 (recommended) + and Checksums-Sha256 (mandatory) Files (mandatory)

@@ -2780,7 +2825,7 @@ Package: libc6 Closes Changes (mandatory) Checksums-Sha1 - and Checksums-Sha256 (recommended) + and Checksums-Sha256 (mandatory) Files (mandatory)

@@ -3637,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 -.

@@ -3714,28 +3759,114 @@ Checksums-Sha256:

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

- + DM-Upload-Allowed

- Indicates that Debian Maintainers may upload this package to - the Debian archive. The only valid value is yes. If - the field DM-Upload-Allowed: yes is present in the - source section of the source control file of the most recent - version of a package in unstable or experimental, the Debian - archive will accept uploads of this package signed with a key - in the Debian Maintainer keyring. See the General - Resolution for more - details. + Obsolete, see below. +

+ + + + Version Control System (VCS) fields + +

+ Debian source packages are increasingly developed using VCSs. The + purpose of the following fields is to indicate a publicly accessible + repository where the Debian source package is developed. + + + Vcs-Browser + +

+ URL of a web interface for browsing the repository. +

+ + + + Vcs-Arch, Vcs-Bzr (Bazaar), Vcs-Cvs, + Vcs-Darcs, Vcs-Git, Vcs-Hg + (Mercurial), Vcs-Mtn (Monotone), Vcs-Svn + (Subversion) + + +

+ The field name identifies the VCS. The field's value uses the + version control system's conventional syntax for describing + repository locations and should be sufficient to locate the + repository used for packaging. Ideally, it also locates the + branch used for development of new versions of the Debian + package. +

+

+ In the case of Git, the value consists of a URL, optionally + followed by the word -b and the name of a branch in + the indicated repository, following the syntax of the + git clone command. If no branch is specified, the + packaging should be on the default branch. +

+

+ More than one different VCS may be specified for the same + package. +

+ + +

+ + + + Package-List + +

+ Multiline field listing all the packages that can be built from + the source package, considering every architecture. The first line + of the field value is empty. Each one of the next lines describes + one binary package, by listing its name, type, section and priority + separated by spaces. Fifth and subsequent space-separated items + may be present and parsers must allow them. See the + Package-Type field for a list of + package types. +

+ + + + Package-Type + +

+ Simple field containing a word indicating the type of package: + deb for binary packages and udeb for micro binary + packages. Other types not defined here may be indicated. In + source package control files, the Package-Type field + should be omitted instead of giving it a value of deb, as + 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.

@@ -3784,6 +3915,28 @@ Checksums-Sha256: + + Obsolete fields + +

+ The following fields have been obsoleted and may be found in packages + conforming with previous versions of the Policy. +

+ + + DM-Upload-Allowed + +

+ Indicates that Debian Maintainers may upload this package to + the Debian archive. The only valid value is yes. This + field was used to regulate uploads by Debian Maintainers, See the + General Resolution for more details. +

+ + + + @@ -3846,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 @@ -3946,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. @@ -3960,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 @@ -3979,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 @@ -4003,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, @@ -4040,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. @@ -4069,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 @@ -4132,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 @@ -4247,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 @@ -4272,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. @@ -4410,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 @@ -4436,7 +4588,7 @@ fi

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

@@ -4473,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.

@@ -4593,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.

@@ -4608,13 +4760,13 @@ fi

The relations allowed are <<, <=, - =, >= and >> for - strictly earlier, earlier or equal, exactly equal, later or - equal and strictly later, respectively. The deprecated - forms < and > were used to mean - earlier/later or equal, rather than strictly earlier/later, - so they should not appear in new packages (though - dpkg still supports them). + =, >= and >> for strictly + earlier, earlier or equal, exactly equal, later or equal and + strictly later, respectively. The deprecated + forms < and > were confusingly used to + mean earlier/later or equal, rather than strictly earlier/later, + and must not appear in new packages (though dpkg + still supports them with a warning).

@@ -4678,7 +4830,8 @@ Build-Depends: kernel-headers-2.2.10 [!hurd-i386],

- For binary relationship fields, the architecture restriction + For binary relationship fields and the Built-Using + field, the architecture restriction syntax is only supported in the source package control file debian/control. When the corresponding binary package control file is generated, the relationship will either @@ -4924,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.

@@ -5283,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 @@ -5402,6 +5555,53 @@ Replaces: mail-transport-agent

+ + + Additional source packages used to build the binary + - Built-Using + + +

+ Some binary packages incorporate parts of other packages when built + but do not have to depend on those packages. Examples include + linking with static libraries or incorporating source code from + another package during the build. In this case, the source packages + of those other packages are a required part of the complete source + (the binary package is not reproducible without them). +

+ +

+ A Built-Using field must list the corresponding source + package for any such binary package incorporated during the build + + Build-Depends in the source package is not adequate since + it (rightfully) does not document the exact version used in the + build. + , + including an "exactly equal" ("=") version relation on the version + that was used to build that binary package + The archive software might reject packages that refer to + non-existent sources. + . +

+ +

+ A package using the source code from the gcc-4.6-source + binary package built from the gcc-4.6 source package would + have this field in its control file: + +Built-Using: gcc-4.6 (= 4.6.0-11) + +

+ +

+ A package including binaries from grub2 and loadlin would + have this field in its control file: + +Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1) + +

+ @@ -5506,7 +5706,7 @@ Replaces: mail-transport-agent

To determine the soversion, look at the SONAME of the library, stored in the - ELF SONAME attribute. it is usually of the + ELF SONAME attribute. It is usually of the form name.so.major-version (for example, libz.so.1). The version part is the part which comes after .so., so in that example it @@ -5838,28 +6038,37 @@ Replaces: mail-transport-agent whether new library interfaces are available and can be called). To allow these dependencies to be constructed, shared libraries must provide either a symbols file or - a shlibs file, which provide information on the - package dependencies required to ensure the presence of this - library. Any package which uses a shared library must use these - files to determine the required dependencies when it is built. -

- -

- These two mechanisms differ in the degree of detail that they - provide. A symbols file documents every symbol - that is part of the library ABI and, for each, the version of - the package in which it was introduced. This permits detailed - analysis of the symbols used by a particular package and - construction of an accurate dependency, but it requires the - package maintainer to track more information about the shared - library. A shlibs file, in contrast, only - documents the last time the library ABI changed in any way. It - only provides information about the library as a whole, not - individual symbols. When a package is built using a shared - library with only a shlibs file, the generated - dependency will require a version of the shared library equal to - or newer than the version of the last ABI change. This - generates unnecessarily restrictive dependencies compared + a shlibs file. These provide information on the + package dependencies required to ensure the presence of + interfaces provided by this library. Any package with binaries + or libraries linking to a shared library must use these files to + determine the required dependencies when it is built. Other + packages which use a shared library (for example using + dlopen()) should compute appropriate dependencies + using these files at build time as well. +

+ +

+ The two mechanisms differ in the degree of detail that they + provide. A symbols file documents, for each symbol + exported by a library, the minimal version of the package any + binary using this symbol will need. This is typically the + version of the package in which the symbol was introduced. This + information permits detailed analysis of the symbols used by a + particular package and construction of an accurate dependency, + but it requires the package maintainer to track more information + about the shared library. +

+ +

+ A shlibs file, in contrast, only documents the last + time the library ABI changed in any way. It only provides + information about the library as a whole, not individual + symbols. When a package is built using a shared library with + only a shlibs file, the generated dependency will + require a version of the shared library equal to or newer than + the version of the last ABI change. This generates + unnecessarily restrictive dependencies compared to symbols files if none of the symbols used by the package have changed. This, in turn, may make upgrades needlessly complex and unnecessarily restrict use of the package @@ -5867,9 +6076,16 @@ Replaces: mail-transport-agent

- shlibs files also have a flawed representation of + shlibs files also only support a limited range of library SONAMEs, making it difficult to use shlibs - files in some unusual corner cases. + files in some unusual corner cases. + A shlibs file represents an SONAME as a library + name and version number, such as libfoo VERSION, + instead of recording the actual SONAME. If the SONAME doesn't + match one of the two expected formats + (libfoo-VERSION.so or libfoo.so.VERSION), it + cannot be represented. +

@@ -5879,9 +6095,10 @@ Replaces: mail-transport-agent required by symbols files is not too difficult to maintain. However, maintaining exhaustive symbols information for a C++ library can be quite onerous, so shlibs - files may be more appropriate for most C++ libraries. udebs - must also use shlibs, since the udeb infrastructure - does not use symbols. + files may be more appropriate for most C++ libraries. Libraries + with a corresponding udeb must also provide + a shlibs file, since the udeb infrastructure does + not use symbols files.

@@ -5940,10 +6157,10 @@ Replaces: mail-transport-agent binaries, libraries, or loadable modules. If you have multiple binary packages, you will need to call dpkg-shlibdeps on each one which contains - compiled libraries or binaries, using the -T option - to the dpkg utilities to specify a - different substvars file for each binary - package. + compiled libraries or binaries. For example, you could use + the -T option to the dpkg utilities to + specify a different substvars file for each + binary package. Again, dh_shlibdeps and dh_gencontrol will handle everything except the addition of the variable to the control file for you if @@ -5969,8 +6186,8 @@ Replaces: mail-transport-agent linked indirectly to foo, and the dynamic linker will load them automatically when it loads libbar. A package should depend on the - libraries it directly uses, but not the libraries it - indirectly uses. The dependencies for the libraries used + libraries it directly uses, but not the libraries it only uses + indirectly. The dependencies for the libraries used directly will automatically pull in the indirectly-used libraries. dpkg-shlibdeps will handle this logic automatically, but package maintainers need to be aware of @@ -6014,14 +6231,26 @@ Replaces: mail-transport-agent

There are two types of ABI changes: ones that are backward-compatible and ones that are not. An ABI change is - backward-compatible if any binary was linked with the previous - version of the shared library will still work correctly with - the new version of the shared library. Adding new symbols to - the shared library is a backward-compatible change. Removing - symbols from the shared library is not. Changing the behavior - of a symbol may or may not be backward-compatible depending on - the change; for example, changing a function to accept a new - enum constant not previously used by the library is generally + backward-compatible if any reasonable program or library that + was linked with the previous version of the shared library + will still work correctly with the new version of the shared + library. + An example of an "unreasonable" program is one that uses + library interfaces that are documented as internal and + unsupported. If the only programs or libraries affected by + a change are "unreasonable" ones, other techniques, such as + declaring Breaks relationships with affected + packages or treating their usage of the library as bugs in + those packages, may be appropriate instead of changing the + SONAME. However, the default approach is to change the + SONAME for any change to the ABI that could break a program. + + Adding new symbols to the shared library is a + backward-compatible change. Removing symbols from the shared + library is not. Changing the behavior of a symbol may or may + not be backward-compatible depending on the change; for + example, changing a function to accept a new enum constant not + previously used by the library is generally backward-compatible, but changing the members of a struct that is passed into library functions is generally not unless the library takes special precautions to accept old versions of @@ -6069,9 +6298,9 @@ Replaces: mail-transport-agent

- A common example of when a change to the is required is a - function that takes an enum or struct argument that controls - what the function does. For example: + A common example of when a change to the dependency version + is required is a function that takes an enum or struct + argument that controls what the function does. For example: enum library_op { OP_FOO, OP_BAR }; int library_do_operation(enum library_op); @@ -6122,10 +6351,10 @@ Replaces: mail-transport-agent

symbols files for a shared library are normally - provided by the shared library package, but there are - several override paths that are checked first in case that - information is wrong or missing. The following list gives - them in the order in which they are read + provided by the shared library package as a control file, + but there are several override paths that are checked first + in case that information is wrong or missing. The following + list gives them in the order in which they are read by dpkg-shlibdeps The first one that contains the required information is used. @@ -6320,8 +6549,9 @@ Replaces: mail-transport-agent recent version of the shared library that changed the behavior of that symbol, whether by adding it, changing its function signature (the parameters, their types, or the - return type), or its behavior in a way that is visible to a - caller. id-of-dependency-template is an optional + return type), or changing its behavior in a way that is + visible to a caller. + id-of-dependency-template is an optional field that references an alternative-dependency-template; see below for a full description. @@ -6342,9 +6572,9 @@ Replaces: mail-transport-agent compressBound@ZLIB_1.2.0 1:1.2.0 Packages using only compress would then get a - dependency of zlib1g (>= 1:1.1.4), but packages + dependency on zlib1g (>= 1:1.1.4), but packages using compressBound would get a dependency - of zlib1g (>= 1:1.2.0). + on zlib1g (>= 1:1.2.0).

@@ -6471,7 +6701,7 @@ Replaces: mail-transport-agent The shlibs system

- The shlibs system is an simpler alternative to + The shlibs system is a simpler alternative to the symbols system for declaring dependencies for shared libraries. It may be more appropriate for C++ libraries and other cases where tracking individual symbols is @@ -6542,7 +6772,7 @@ Replaces: mail-transport-agent The shlibs control files for all the packages currently installed on the system. These are normally found - in /var/lib/dpkg/info/*.symbols, but + in /var/lib/dpkg/info/*.shlibs, but packages should not rely on this and instead should use dpkg-query --control-path package shlibs if for some reason these files need to be @@ -6629,7 +6859,7 @@ Replaces: mail-transport-agent library was in version 1:1.2.3.3.dfsg-1, then the shlibs entry for this library could say: - libz 1 zlib1g (>= 1:1.2.3.3.dfsg-1) + libz 1 zlib1g (>= 1:1.2.3.3.dfsg) This version restriction must be new enough that any binary built against the current version of the library will work @@ -6641,7 +6871,7 @@ Replaces: mail-transport-agent As zlib1g also provides a udeb containing the shared library, there would also be a second line: - udeb: libz 1 zlib1g-udeb (>= 1:1.2.3.3.dfsg-1) + udeb: libz 1 zlib1g-udeb (>= 1:1.2.3.3.dfsg)

@@ -6696,6 +6926,20 @@ Replaces: mail-transport-agent 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 @@ -6737,8 +6981,18 @@ Replaces: mail-transport-agent 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.

@@ -6792,16 +7046,36 @@ Replaces: mail-transport-agent in /run should be stored on a temporary file system.

+

+ Packages must not assume the /run + directory exists or is usable without a dependency + on initscripts (>= 2.88dsf-13.3) until the + 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 @@ -7082,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 @@ -7880,33 +8183,28 @@ Reloading description configuration...done.

- Packages which provide the ability to view/show/play, - compose, edit or print MIME types should register themselves - as such following the current MIME support policy. + Packages which provide programs to view/show/play, compose, edit or + print MIME types should register them as such by placing a file in + format (RFC 1524) in the directory + /usr/lib/mime/packages/. The file name should be the + binary package's name.

The mime-support package provides the - update-mime program which allows packages to - register programs that can show, compose, edit or print - MIME types. -

- -

- Packages containing such programs must register them - with update-mime as documented in . They should not depend - on, recommend, or suggest mime-support. Instead, - they should just put something like the following in the - postinst and postrm scripts: - - - if [ -x /usr/sbin/update-mime ]; then - update-mime - fi - + update-mime program, which integrates these + registrations in the /etc/mailcap file, using dpkg + triggers + Creating, modifying or removing a file in + /usr/lib/mime/packages/ using maintainer scripts will + not activate the trigger. In that case, it can be done by calling + dpkg-trigger --no-await /usr/lib/mime/packages from + the maintainer script after creating, modifying, or removing + the file. + . + Packages using this facility should not depend on, + recommend, or suggest mime-support.

- @@ -8120,6 +8418,74 @@ exec /usr/lib/foo/foo "$@"

+ + Alternate init systems +

+ A number of other init systems are available now in Debian that + can be used in place of sysvinit. Alternative + init implementations must support running SysV init scripts as + described at for compatibility. +

+

+ Packages may integrate with these replacement init systems by + providing implementation-specific configuration information about + how and when to start a service or in what order to run certain + tasks at boot time. However, any package integrating with other + init systems must also be backwards-compatible with + sysvinit by providing a SysV-style init script + with the same name as and equivalent functionality to any + init-specific job, as this is the only start-up configuration + method guaranteed to be supported by all init implementations. An + exception to this rule is scripts or jobs provided by the init + implementation itself; such jobs may be required for an + implementation-specific equivalent of the /etc/rcS.d/ + scripts and may not have a one-to-one correspondence with the init + scripts. +

+ + Event-based boot with upstart + +

+ Packages may integrate with the upstart event-based + boot system by installing job files in the + /etc/init directory. SysV init scripts for which + an equivalent upstart job is available must query the output of + the command initctl version for the string + upstart and avoid running in favor of the native + upstart job, using a test such as this: + +if [ "$1" = start ] && which initctl >/dev/null && initctl version | grep -q upstart +then + exit 1 +fi + +

+

+ Because packages shipping upstart jobs may be installed on + systems that are not using upstart, maintainer scripts must + still use the common update-rc.d and + invoke-rc.d interfaces for configuring runlevels + and for starting and stopping services. These maintainer + scripts must not call the upstart start, + restart, reload, or stop + interfaces directly. Instead, implementations of + invoke-rc.d must detect when upstart is running and + when an upstart job with the same name as an init script is + present, and perform the requested action using the upstart job + instead of the init script. +

+

+ Dependency-based boot managers for SysV init scripts, such as + startpar, may avoid running a given init script + entirely when an equivalent upstart job is present, to avoid + unnecessary forking of no-op init scripts. In this case, the + boot manager should integrate with upstart to detect when the + upstart job in question is started or stopped to know when the + dependency has been satisfied. +

+ + + @@ -8142,7 +8508,17 @@ exec /usr/lib/foo/foo "$@" 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 @@ -8551,6 +8927,7 @@ fname () { would point to /srv/run rather than the intended target. + Symbolic links must not traverse above the root directory.

@@ -8583,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 @@ -8717,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.

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

+ @@ -9387,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)

 @@ -9444,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 @@ -10227,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.

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

+ +

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

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

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

@@ -10333,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. - -

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

@@ -10448,6 +10855,10 @@ END-INFO-DIR-ENTRY README.Debian or some other appropriate place.

+

+ All copyright files must be encoded in UTF-8. +

+ Machine-readable copyright information @@ -10601,12 +11012,6 @@ END-INFO-DIR-ENTRY dpkg, dselect et al. and the way they interact with packages.

-

- It also documents the interaction between - dselect's core and the access method scripts it - uses to actually install the selected packages, and describes - how to create a new access method.

-

This manual does not go into detail about the options and usage of the package building and installation tools. It @@ -10616,10 +11021,7 @@ END-INFO-DIR-ENTRY

The utility programs which are provided with dpkg - for managing various system configuration and similar issues, - such as update-rc.d and - install-info, are not described in detail here - - please see their man pages. + not described in detail here, are documented in their man pages.

@@ -10639,25 +11041,9 @@ END-INFO-DIR-ENTRY Binary packages (from old Packaging Manual)

- The binary package has two main sections. The first part - consists of various control information files and scripts used - by dpkg when installing and removing. See . -

- -

- The second part is an archive containing the files and - directories to be installed. + See and .

-

- In the future binary packages may also contain other - components, such as checksums and digital signatures. The - format for the archive is described in full in the - deb(5) man page. -

- - Creating package files - dpkg-deb @@ -10959,55 +11345,7 @@ END-INFO-DIR-ENTRY

- dpkg-buildpackage is a script which invokes - dpkg-source, the debian/rules - targets clean, build and - binary, dpkg-genchanges and - gpg (or pgp) to build a signed - source and binary package upload. -

- -

- It is usually invoked by hand from the top level of the - built or unbuilt source directory. It may be invoked with - no arguments; useful arguments include: - - -uc, -us - -

- Do not sign the .changes file or the - source package .dsc file, respectively.

- - -psign-command - -

- Invoke sign-command instead of finding - gpg or pgp on the PATH. - sign-command must behave just like - gpg or pgp.

- - -rroot-command - -

- When root privilege is required, invoke the command - root-command. root-command - should invoke its first argument as a command, from - the PATH if necessary, and pass its - second and subsequent arguments to the command it - calls. If no root-command is supplied - then dpkg-buildpackage will use - the fakeroot command, which is sufficient - to build most packages without actually requiring root - privileges.

- - -b, -B - -

- Two types of binary-only build and upload - see - . -

- - + See .

@@ -11131,23 +11469,10 @@ END-INFO-DIR-ENTRY

- This program is usually called by package-independent - automatic building scripts such as - dpkg-buildpackage, but it may also be called - by hand. -

- -

- It is usually called in the top level of a built source - tree, and when invoked with no arguments will print out a - straightforward .changes file based on the - information in the source package's changelog and control - file and the binary and source packages which should have - been built. + See .

- dpkg-parsechangelog - produces parsed @@ -11155,12 +11480,7 @@ END-INFO-DIR-ENTRY

- This program is used internally by - dpkg-source et al. It may also occasionally - be useful in debian/rules and elsewhere. It - parses a changelog, debian/changelog by default, - and prints a control-file format representation of the - information in it to standard output. + See .

@@ -11171,10 +11491,7 @@ END-INFO-DIR-ENTRY

- This program can be used manually, but is also invoked by - dpkg-buildpackage or debian/rules to set - environment or make variables which specify the build and host - architecture for the package building process. + See .

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