X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=policy.sgml;h=1e9934cd29e49b489cccca7584f84719c1637f09;hb=3bb4976623bbf548b6b31f84495355abaeffc81e;hp=0bf8253e31ba9cb10ed901d4dd6b1c645872f287;hpb=10f927594e0ddeffc217e675cbd16f380be2da4f;p=debian%2Fdebian-policy.git diff --git a/policy.sgml b/policy.sgml index 0bf8253..1e9934c 100644 --- a/policy.sgml +++ b/policy.sgml @@ -90,11 +90,10 @@ is used by, a significant number of packages, and therefore should not be changed without peer review. Package maintainers can then rely on this - interfaces not changing, and the package - management software authors need to ensure - compatibility with these interface - definitions. (Control file and changelog file - formats are examples.) + interface not changing, and the package management + software authors need to ensure compatibility with + this interface definition. (Control file and + changelog file formats are examples.) Chosen Convention @@ -366,7 +365,7 @@ The Debian Free Software Guidelines (DFSG) form our definition of "free software". These are: - Free Redistribution + 1. Free Redistribution The license of a Debian component may not restrict any @@ -376,20 +375,20 @@ sources. The license may not require a royalty or other fee for such sale. - Source Code + 2. Source Code The program must include source code, and must allow distribution in source code as well as compiled form. - Derived Works + 3. Derived Works The license must allow modifications and derived works, and must allow them to be distributed under the same terms as the license of the original software. - Integrity of The Author's Source Code + 4. Integrity of The Author's Source Code The license may restrict source-code from being @@ -404,13 +403,13 @@ Project encourages all authors to not restrict any files, source or binary, from being modified.) - No Discrimination Against Persons or Groups + 5. No Discrimination Against Persons or Groups The license must not discriminate against any person or group of persons. - No Discrimination Against Fields of Endeavor + 6. No Discrimination Against Fields of Endeavor The license must not restrict anyone from making use @@ -419,7 +418,7 @@ used in a business, or from being used for genetic research. - Distribution of License + 7. Distribution of License The rights attached to the program must apply to all @@ -427,7 +426,7 @@ for execution of an additional license by those parties. - License Must Not Be Specific to Debian + 8. License Must Not Be Specific to Debian The rights attached to the program must not depend on @@ -439,7 +438,7 @@ rights as those that are granted in conjunction with the Debian system. - License Must Not Contaminate Other Software + 9. License Must Not Contaminate Other Software The license must not place restrictions on other @@ -448,7 +447,7 @@ that all other programs distributed on the same medium must be free software. - Example Licenses + 10. Example Licenses The "GPL," "BSD," and "Artistic" licenses are examples of @@ -570,8 +569,8 @@ Copyright considerations

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

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

+ +

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

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

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

@@ -1726,14 +1733,17 @@

It must start with the line #!/usr/bin/make -f, so that it can be invoked by saying its name rather than - invoking make explicitly. + invoking make explicitly. That is, invoking + either of make -f debian/rules args... + or ./debian/rules args... must result in + identical behavior.

Since an interactive debian/rules script makes it impossible to auto-compile that package and also makes it hard for other people to reproduce the same binary - package, all required targets MUST be + package, all required targets must be non-interactive. At a minimum, required targets are the ones called by dpkg-buildpackage, namely, clean, binary, binary-arch, @@ -2690,7 +2700,7 @@ Package: libc6 Priority

- This field represents how important that it is that the user + This field represents how important it is that the user have the package installed. See .

@@ -2799,8 +2809,8 @@ Package: libc6

- See for information how to get the - architecture for the build process. + See for information on how to get + the architecture for the build process.

@@ -2861,8 +2871,8 @@ Package: libc6

Thus only the first three components of the policy version are significant in the Standards-Version control - field, and so either these three components or the all - four components may be specified. + field, and so either these three components or all four + components may be specified. In the past, people specified the full version number in the Standards-Version field, for example "2.3.0.0". Since minor patch-level changes don't introduce new @@ -3254,7 +3264,7 @@ Package: libc6 for the most recent version should be returned first, and entries should be separated by the representation of a blank line (the "title" line may also be followed by the - representation of blank line). + representation of a blank line).

@@ -3370,7 +3380,7 @@ Files: no new original source archive is being distributed the .dsc must still contain the Files field entry for the original source archive - package-upstream-version.orig.tar.gz, + package_upstream-version.orig.tar.gz, but the .changes file should leave it out. In this case the original source archive on the distribution site must match exactly, byte-for-byte, the original @@ -3547,15 +3557,17 @@ Files: Controlling terminal for maintainer scripts

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

+ Exit status @@ -3713,7 +3725,7 @@ Files: If this works, then the old-version is "Installed", if not, the old version is in a - "Failed-Config" state. + "Half-Configured" state. @@ -3821,7 +3833,7 @@ Files: If this fails, the package is left in a "Half-Installed" state, which requires a reinstall. If it works, the packages is left in - a "Config Files" state. + a "Config-Files" state. Otherwise (i.e., the package was completely purged): @@ -3833,7 +3845,7 @@ Files: new-postrm abort-install If the error-unwind fails, the package is in a - "Half Installed" phase, and requires a + "Half-Installed" phase, and requires a reinstall. If the error unwind works, the package is in a not installed state. @@ -3913,14 +3925,14 @@ Files: old-preinst abort-upgrade new-version - If this fails, the old version is left in an - "Half Installed" state. If it works, dpkg now + If this fails, the old version is left in a + "Half-Installed" state. If it works, dpkg now calls: new-postrm abort-upgrade old-version - If this fails, the old version is left in an - "Half Installed" state. If it works, dpkg now + If this fails, the old version is left in a + "Half-Installed" state. If it works, dpkg now calls: old-postinst abort-upgrade new-version @@ -4079,7 +4091,7 @@ Files:

- If this fails, the package is in a "Failed-Config" + If this fails, the package is in a "Half-Configured" state, or else it remains "Installed".

@@ -4415,12 +4427,12 @@ Build-Depends: foo [!i386] | bar [!amd64] be unpacked the pre-dependency can be satisfied if the depended-on package is either fully configured, or even if the depended-on - package(s) are only unpacked or half-configured, - provided that they have been configured correctly at - some point in the past (and not removed or partially - removed since). In this case, both the + package(s) are only unpacked or in the "Half-Configured" + state, provided that they have been configured + correctly at some point in the past (and not removed + or partially removed since). In this case, both the previously-configured and currently unpacked or - half-configured versions must satisfy any version + "Half-Configured" versions must satisfy any version clause in the Pre-Depends field.

@@ -4477,7 +4489,7 @@ Build-Depends: foo [!i386] | bar [!amd64]

A package will not be regarded as causing breakage merely because its configuration files are still installed; it must - be at least half-installed. + be at least "Half-Installed".

@@ -4531,7 +4543,7 @@ Build-Depends: foo [!i386] | bar [!amd64]

A package will not cause a conflict merely because its configuration files are still installed; it must be at least - half-installed. + "Half-Installed".

@@ -5337,10 +5349,10 @@ dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* \

- If you are creating a udeb for use in the Debian Installer, you - will need to specify that dpkg-shlibdeps should use - the dependency line of type udeb by adding - -tudeb as option + If you are creating a udeb for use in the Debian Installer, + you will need to specify that dpkg-shlibdeps + should use the dependency line of type udeb by + adding the -tudeb option dh_shlibdeps from the debhelper suite will automatically add this option if it knows it is processing a udeb. @@ -5582,6 +5594,40 @@ libbar 1 bar1 (>= 1.0-1) for 64 bit binaries is removed.

+ +

+ The requirement for object files, internal binaries, and + libraries, including libc.so.*, to be located + directly under /lib{,32} and + /usr/lib{,32} is amended, permitting files + to instead be installed to + /lib/triplet and + /usr/lib/triplet, where + triplet is the value returned by + dpkg-architecture -qDEB_HOST_GNU_TYPE for the + architecture of the package. Packages may not + install files to any triplet path other + than the one matching the architecture of that package; + for instance, an Architecture: amd64 package + containing 32-bit x86 libraries may not install these + libraries to /usr/lib/i486-linux-gnu. + + This is necessary in order to reserve the directories for + use in cross-installation of library packages from other + architectures, as part of the planned deployment of + multiarch. + +

+

+ Applications may also use a single subdirectory under + /usr/lib/triplet. +

+

+ The execution time linker/loader, ld*, must still be made + available in the existing location under /lib or /lib64 + since this is part of the ELF ABI for the architecture. +

+

The requirement that @@ -5605,6 +5651,15 @@ libbar 1 bar1 (>= 1.0-1) symlinked there, is relaxed to a recommendation.

+ +

+ The following directories in the root filesystem are + additionally allowed: /sys and + /selinux. These directories + are used as mount points to mount virtual filesystems + to get access to kernel information. +

+

@@ -5650,13 +5705,15 @@ libbar 1 bar1 (>= 1.0-1)

- Note, that this applies only to directories below - /usr/local, not in /usr/local. - Packages must not create sub-directories in the directory - /usr/local itself, except those listed in FHS, - section 4.5. However, you may create directories below - them as you wish. You must not remove any of the - directories listed in 4.5, even if you created them. + Note that this applies only to + directories below /usr/local, + not in /usr/local. Packages must + not create sub-directories in the + directory /usr/local itself, except those + listed in FHS, section 4.5. However, you may create + directories below them as you wish. You must not remove + any of the directories listed in 4.5, even if you created + them.

@@ -5717,9 +5774,10 @@ rmdir /usr/local/share/emacs 2>/dev/null || true The system-wide mail directory

- The system-wide mail directory is /var/mail. This - directory is part of the base system and should not owned - by any particular mail agents. The use of the old + The system-wide mail directory + is /var/mail. This directory is part of the + base system and should not be owned by any particular mail + agents. The use of the old location /var/spool/mail is deprecated, even though the spool may still be physically located there.

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

- 1000-29999: + 1000-59999:

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

- 30000-59999: - -

Reserved.

- - 60000-64999:

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

- + Writing the scripts

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

+

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

+

If a service reloads its configuration automatically (as in the case of cron, for example), the @@ -6504,13 +6574,48 @@ Reloading description configuration...done. anacron. Thus, you should only use this directory for jobs which may be skipped if the system is not running.)

+

+ Unlike crontab files described in the IEEE Std + 1003.1-2008 (POSIX.1) available from + , the files in + /etc/cron.d and the file + /etc/crontab have seven fields; namely: + + Minute [0,59] + Hour [0,23] + Day of the month [1,31] + Month of the year [1,12] + Day of the week ([0,6] with 0=Sunday) + Username + Command to be run + + Ranges of numbers are allowed. Ranges are two numbers + separated with a hyphen. The specified range is inclusive. + Lists are allowed. A list is a set of numbers (or ranges) + separated by commas. Step values can be used in conjunction + with ranges. +

- The scripts or crontab entries in these directories should + The scripts or crontab entries in these directories should check if all necessary programs are installed before they try to execute them. Otherwise, problems will arise when a package was removed but not purged since configuration files - are kept on the system in this situation.

+ are kept on the system in this situation. +

+ +

+ Any cron daemon must provide + /usr/bin/crontab and support normal + crontab entries as specified in POSIX. The daemon + must also support names for days and months, ranges, and + step values. It has to support /etc/crontab, + and correctly execute the scripts in + /etc/cron.d. The daemon must also correctly + execute scripts in + /etc/cron.{hourly,daily,weekly,monthly}. +

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

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

+

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

-

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

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

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

+ +

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

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

Customization of programs' X resources may also be supported with the provision of a file with the same name - as that of the package placed in the - /etc/X11/Xresources/ directory, which must - registered as a conffile or handled as a + as that of the package placed in + the /etc/X11/Xresources/ directory, which + must be registered as a conffile or handled as a configuration file. Note that this mechanism is not the same as using app-defaults; app-defaults are tied to the client @@ -8959,7 +9079,7 @@ END-INFO-DIR-ENTRY

Please note that this does not override the section on changelog files below, so the file - /usr/share/package/changelog.Debian.gz + /usr/share/doc/package/changelog.Debian.gz must refer to the changelog for the current version of package in question. In practice, this means that the sources of the target and the destination of the @@ -9013,7 +9133,7 @@ END-INFO-DIR-ENTRY

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

@@ -9419,9 +9539,9 @@ END-INFO-DIR-ENTRY

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

@@ -9893,120 +10013,6 @@ END-INFO-DIR-ENTRY

- - - debian/changelog - -

- See . -

- - Defining alternative changelog formats - - -

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

- -

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

- -

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

- -

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

- -

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

- -

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

- -

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

- -

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

- -

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

- -

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

- -

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

- - - debian/substvars and variable substitutions