X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=policy.sgml;h=1390cf41c5e0d69d6de6135e806776c1c181c73d;hb=f812bda88f43e6af288b21d37a5a6e34d675190d;hp=5d2105e6cdd8f25a50b695c5c69e2c280e4386e2;hpb=52ad20d192fa0583a5697031570693cc3bfe6d50;p=debian%2Fdebian-policy.git diff --git a/policy.sgml b/policy.sgml index 5d2105e..1390cf4 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. +

@@ -1322,9 +1330,9 @@ zope. The package installation scripts should avoid producing output which is unnecessary for the user to see and should rely on 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.

@@ -1729,7 +1737,7 @@ zope. /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 @@ -1988,51 +1996,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. @@ -2171,7 +2161,7 @@ zope.

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 @@ -2667,7 +2657,6 @@ Package: libc6 Source (mandatory) Maintainer (mandatory) Uploaders - DM-Upload-Allowed Section (recommended) Priority (recommended) Build-Depends et al @@ -2690,6 +2679,7 @@ Package: libc6 Description (mandatory) Homepage Built-Using + Package-Type

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

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

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

@@ -3830,6 +3811,34 @@ Checksums-Sha256:

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

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

+ + + + @@ -3938,8 +3969,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 @@ -6641,7 +6671,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 @@ -6712,7 +6742,7 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1) 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 @@ -8056,33 +8086,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.

- @@ -8296,6 +8321,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. +

+ + + @@ -10403,18 +10496,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.

@@ -10781,12 +10879,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 @@ -10796,10 +10888,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.

@@ -10819,25 +10908,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. -

- -

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

- Creating package files - dpkg-deb @@ -11139,55 +11212,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 .

@@ -11311,23 +11336,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 @@ -11335,12 +11347,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 .

@@ -11351,10 +11358,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 .