X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=policy.sgml;h=8100da082bd123ab85cf97a6788b5cd656b99cb4;hb=001edcea5cdfc39e88382add063e9c90038f8af5;hp=7377752406f340721ab0370771ba478087060399;hpb=5427066a52101b5b19927d358433c69b759e1781;p=debian%2Fdebian-policy.git diff --git a/policy.sgml b/policy.sgml index 7377752..8100da0 100644 --- a/policy.sgml +++ b/policy.sgml @@ -258,7 +258,6 @@ - @@ -488,11 +487,11 @@ In addition, the packages in main - must not require a package outside of main - for compilation or execution (thus, the package must - not declare a "Depends", "Recommends", or - "Build-Depends" relationship on a non-main - package), + must not require or recommend a package outside + of main for compilation or execution (thus, the + package must not declare a "Pre-Depends", "Depends", + "Recommends", "Build-Depends", or "Build-Depends-Indep" + relationship on a non-main package), must not be so buggy that we refuse to support them, @@ -709,12 +708,13 @@ list of sections. At present, they are: admin, cli-mono, comm, database, devel, debug, doc, editors, - electronics, embedded, fonts, - games, gnome, graphics, gnu-r, - gnustep, hamradio, haskell, - httpd, interpreters, java, kde, - kernel, libs, libdevel, lisp, - localization, mail, math, misc, + 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, @@ -2543,7 +2543,7 @@ Package: libc6 lines. The first line of the value, the part on the same line as the field name, often has special significance or may have to be empty. Other lines are added following the same syntax as the - continuation lines the folded fields. Whitespace, including newlines, + continuation lines of the folded fields. Whitespace, including newlines, is significant in the values of multiline fields. @@ -3302,6 +3302,7 @@ Package: libc6 Those starting with a single space are part of a paragraph. Successive lines of this form will be word-wrapped when displayed. The leading space will usually be stripped off. + The line must contain at least one non-whitespace character. @@ -3312,7 +3313,8 @@ Package: libc6 will be allowed to trail off to the right. None, one or two initial spaces may be deleted, but the number of spaces deleted from each line will be the same (so that you can have - indenting work correctly, for example). + indenting work correctly, for example). The line must + contain at least one non-whitespace character. @@ -4626,7 +4628,8 @@ Depends: libc6 (>= 2.2.1), exim | mail-transport-agent Relationships may be restricted to a certain set of architectures. This is indicated in brackets after each individual package name and the optional version specification. - The brackets enclose a list of Debian architecture names + The brackets enclose a non-empty list of Debian architecture names + in the format described in , separated by whitespace. Exclamation marks may be prepended to each of the names. (It is not permitted for some names to be prepended with exclamation marks while others aren't.) @@ -4694,7 +4697,8 @@ Build-Depends: foo [!i386] | bar [!amd64]

Relationships may also be restricted to a certain set of - architectures using architecture wildcards. The syntax for + architectures using architecture wildcards in the format + described in . The syntax for declaring such restrictions is the same as declaring restrictions using a certain set of architectures without architecture wildcards. For example: @@ -6242,6 +6246,25 @@ install -m644 debian/shlibs.package debian/package/DEBIAN/ symlinked there, is relaxed to a recommendation.

+ +

+ The additional directory /run in the root + file system is allowed. /run + replaces /var/run, and the + subdirectory /run/lock + replaces /var/lock, with + the /var directories replaced by symlinks + for backwards compatibility. /run + and /run/lock must follow all of the + requirements in the FHS for /var/run + and /var/lock, respectively, such as file + naming conventions, file format requirements, or the + requirement that files be cleared during the boot + process. Files and directories residing + in /run should be stored on a temporary + file system. +

+

The following directories in the root filesystem are @@ -6332,12 +6355,11 @@ install -m644 debian/shlibs.package debian/package/DEBIAN/ For example, the emacsen-common package could contain something like -if [ ! -e /usr/local/share/emacs ] -then - if mkdir /usr/local/share/emacs 2>/dev/null - then - chown root:staff /usr/local/share/emacs - chmod 2775 /usr/local/share/emacs +if [ ! -e /usr/local/share/emacs ]; then + if mkdir /usr/local/share/emacs 2>/dev/null; then + if chown root:staff /usr/local/share/emacs; then + chmod 2775 /usr/local/share/emacs || true + fi fi fi @@ -6385,6 +6407,29 @@ rmdir /usr/local/share/emacs 2>/dev/null || true though the spool may still be physically located there.

+ + + /run and /run/lock + +

+ The directory /run is cleared at boot, normally + by being a mount point for a temporary file system. Packages + therefore must not assume that any files or directories + under /run other than /run/lock + exist unless the package has arranged to create those files or + directories since the last reboot. Normally, this is done by + the package via an init script. See + for more information. +

+ +

+ Packages must not include files or directories + under /run, or under the + older /var/run and /var/lock paths. + The latter paths will normally be symlinks or other + redirections to /run for backwards compatibility. +

+ @@ -6759,15 +6804,14 @@ test -f program-executed-later-in-script || exit 0

- /var/run and /var/lock may be mounted - as temporary filesystems - For example, using the RAMRUN and RAMLOCK - options in /etc/default/rcS. - , so the init.d scripts must handle this - correctly. This will typically amount to creating any required - subdirectories dynamically when the init.d script - is run, rather than including them in the package and relying on - dpkg to create them. + Files and directories under /run, including ones + referred to via the compatibility paths /var/run + and /var/lock, are normally stored on a temporary + filesystem and are normally not persistent across a reboot. + The init.d scripts must handle this correctly. + This will typically mean creating any required subdirectories + dynamically when the init.d script is run. + See for more information.

@@ -7136,18 +7180,20 @@ Reloading description configuration...done.

- + Cron jobs

Packages must not modify the configuration file /etc/crontab, and they must not modify the files in - /var/spool/cron/crontabs.

+ /var/spool/cron/crontabs. +

- If a package wants to install a job that has to be executed - via cron, it should place a file with the name of the - package in one or more of the following directories: + If a package wants to install a job that has to be executed via + cron, it should place a file named as specified + in into one or more of the following + directories: /etc/cron.hourly /etc/cron.daily @@ -7157,7 +7203,8 @@ Reloading description configuration...done. As these directory names imply, the files within them are executed on an hourly, daily, weekly, or monthly basis, respectively. The exact times are listed in - /etc/crontab.

+ /etc/crontab. +

All files installed in any of these directories must be @@ -7168,15 +7215,18 @@ Reloading description configuration...done.

If a certain job has to be executed at some other frequency or - at a specific time, the package should install a file - /etc/cron.d/package. This file uses the - same syntax as /etc/crontab and is processed by - cron automatically. The file must also be + at a specific time, the package should install a file in + /etc/cron.d with a name as specified + in . This file uses the same syntax + as /etc/crontab and is processed + by cron automatically. The file must also be treated as a configuration file. (Note that entries in the /etc/cron.d directory are not handled by anacron. Thus, you should only use this directory for jobs which may be skipped if the system is not - running.)

+ running.) +

+

Unlike crontab files described in the IEEE Std 1003.1-2008 (POSIX.1) available from @@ -7219,6 +7269,30 @@ Reloading description configuration...done. execute scripts in /etc/cron.{hourly,daily,weekly,monthly}.

+ + + Cron job file names + +

+ The file name of a cron job file should normally match the + name of the package from which it comes. +

+ +

+ If a package supplies multiple cron job files files in the + same directory, the file names should all start with the name + of the package (possibly modified as described below) followed + by a hyphen (-) and a suitable suffix. +

+ +

+ A cron job file name must not include any period or plus + characters (. or +) characters as this will + cause cron to ignore the file. Underscores (_) + should be used instead of . and + + characters. +

+ @@ -7267,7 +7341,7 @@ Reloading description configuration...done. MIME (Multipurpose Internet Mail Extensions, RFCs 2045-2049) is a mechanism for encoding files and data streams and providing meta-information about them, in particular their - type (e.g. audio or video) and format (e.g. PNG, HTML, + type (e.g. audio or video) and format (e.g. PNG, HTML, MP3).

@@ -7284,11 +7358,25 @@ Reloading description configuration...done.

- The MIME support policy can be found in the mime-policy - files in the debian-policy package. - It is also available from the Debian web mirrors at - . + 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 +

@@ -7494,9 +7582,8 @@ exec /usr/lib/foo/foo "$@" package that provides online documentation (other than just manual pages) to register these documents with doc-base by installing a - doc-base control file via the - doc-base control file in + /usr/share/doc-base/.

Please refer to the documentation that comes with the @@ -7915,11 +8002,23 @@ fname () { Symbolic links

- In general, symbolic links within a top-level directory - should be relative, and symbolic links pointing from one - top-level directory into another should be absolute. (A - top-level directory is a sub-directory of the root - directory /.) + In general, symbolic links within a top-level directory should + be relative, and symbolic links pointing from one top-level + directory to or into another should be absolute. (A top-level + directory is a sub-directory of the root + directory /.) For example, a symbolic link + from /usr/lib/foo to /usr/share/bar + should be relative (../share/bar), but a symbolic + link from /var/run to /run should be + absolute. + This is necessary to allow top-level directories to be + symlinks. If linking /var/run + to /run were done with the relative symbolic + link ../run, but /var were a + symbolic link to /srv/disk1, the symbolic link + would point to /srv/run rather than the intended + target. +

@@ -8172,22 +8271,6 @@ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq Sharing configuration files -

- Packages which specify the same file as a - conffile must be tagged as conflicting - with each other. (This is an instance of the general rule - about not sharing files. Note that neither alternatives - nor diversions are likely to be appropriate in this case; - in particular, dpkg does not handle diverted - conffiles well.) -

- -

- The maintainer scripts must not alter a conffile - of any package, including the one the scripts - belong to. -

-

If two or more packages use the same configuration file and it is reasonable for both to be installed at the same @@ -8237,6 +8320,34 @@ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq and which manages the shared configuration files. (The sgml-base package is a good example.)

+ +

+ If the configuration file cannot be shared as described above, + the packages must be marked as conflicting with each other. + Two packages that specify the same file as + a conffile must conflict. This is an instance of the + general rule about not sharing files. Neither alternatives + nor diversions are likely to be appropriate in this case; in + particular, dpkg does not handle diverted + conffiles well. +

+ +

+ When two packages both declare the same conffile, they + may see left-over configuration files from each other even + though they conflict with each other. If a user removes + (without purging) one of the packages and installs the other, + the new package will take over the conffile from the + old package. If the file was modified by the user, it will be + treated the same as any other locally + modified conffile during an upgrade. +

+ +

+ The maintainer scripts must not alter a conffile + of any package, including the one the scripts + belong to. +

@@ -9742,9 +9853,8 @@ END-INFO-DIR-ENTRY

In addition, the copyright file must say where the upstream - sources (if any) were obtained. It should name the original - authors of the package and the Debian maintainer(s) who were - involved with its creation. + sources (if any) were obtained, and should name the original + authors.

@@ -9763,8 +9873,8 @@ END-INFO-DIR-ENTRY /usr/share/doc/package may be a symbolic link to another directory in /usr/share/doc only if the two packages both come from the same source and the - first package Depends on the second. These rules are - important because copyrights must be extractable by + first package Depends on the second. These rules are important + because copyright files must be extractable by mechanical means.

@@ -11259,7 +11369,7 @@ END-INFO-DIR-ENTRY dpkg-divert --package smailwrapper --remove --rename \ --divert /usr/sbin/smail.real /usr/sbin/smail fi - where 1.02-2 is the version at which the + where 1.0-2 is the version at which the diversion was first added to the package. The postrm should not remove the diversion on upgrades both because there's no reason to remove the diversion only to immediately re-add it and since the