X-Git-Url: https://git.donarmstrong.com/?p=debian%2Fdebian-policy.git;a=blobdiff_plain;f=policy.sgml;h=10e626babf857a9c1b25e56444ae3d75f9f12e2c;hp=6cb5b0de28ee9e05eab509d3396aaca0cd03ccff;hb=bce4b938b4e603a7bceeaf2ad31d007d0a9dcb43;hpb=28ec95b89d5f29d1aaa54b990a0dc9d10301ef1a diff --git a/policy.sgml b/policy.sgml index 6cb5b0d..10e626b 100644 --- a/policy.sgml +++ b/policy.sgml @@ -1988,51 +1988,33 @@ zope.

- 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. @@ -2667,7 +2649,6 @@ Package: libc6 Source (mandatory) Maintainer (mandatory) Uploaders - DM-Upload-Allowed Section (recommended) Priority (recommended) Build-Depends et al @@ -2766,13 +2747,12 @@ Package: libc6 Version (mandatory) Maintainer (mandatory) Uploaders - DM-Upload-Allowed Homepage Vcs-Browser, Vcs-Git, et al. Standards-Version (recommended) Build-Depends et al Checksums-Sha1 - and Checksums-Sha256 (recommended) + and Checksums-Sha256 (mandatory) Files (mandatory)

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

@@ -3759,28 +3739,19 @@ 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.

@@ -3876,6 +3847,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. +

+ + + + @@ -5646,7 +5639,7 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1)

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 @@ -5978,28 +5971,37 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1) 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 @@ -6007,9 +6009,16 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1)

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

@@ -6019,9 +6028,10 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1) 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.

@@ -6080,10 +6090,10 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1) 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 @@ -6109,8 +6119,8 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1) 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 @@ -6154,14 +6164,26 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1)

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 @@ -6209,9 +6231,9 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1)

- 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); @@ -6262,10 +6284,10 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1)

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. @@ -6460,8 +6482,9 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1) 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. @@ -6482,9 +6505,9 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1) 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).

@@ -6611,7 +6634,7 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1) 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 @@ -6769,7 +6792,7 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1) 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 @@ -6781,7 +6804,7 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1) 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)

@@ -6932,6 +6955,12 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1) 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. +

@@ -8020,33 +8049,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.

- @@ -8260,6 +8284,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. +

+ + +