X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=policy.sgml;h=aa42b5d078c84b822aa89a1b04eeb7b931713432;hb=26a61738d2b9a9d5fb9610a2da0086c808836e11;hp=1b5b217f4d5e7b58bb3316d0cf2e338429959e82;hpb=6c7592c8a77d410ce314c8095d4fd1a3155fe164;p=debian%2Fdebian-policy.git
diff --git a/policy.sgml b/policy.sgml
index 1b5b217..aa42b5d 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -258,7 +258,6 @@
-
@@ -280,6 +279,14 @@
.
+
+
+ Finally, a specification for
+ machine-readable copyright files is maintained as part of
+ the debian-policy package using the same
+ procedure as the other policy documents. Use of this format is
+ optional.
+
@@ -488,11 +495,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 +716,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,
@@ -1943,7 +1951,7 @@
-
- A package may also provide both of the targets
+ A package may also provide one or both of the targets
build-arch and build-indep.
The build-arch target, if provided, should
perform all the configuration and compilation required for
@@ -1956,9 +1964,13 @@
architecture-independent binary packages (those packages
for which the body of the Architecture field
in debian/control is all).
- The build target should depend on those of the
- targets build-arch and build-indep that
- are provided in the rules file.
+
+
+
+ If build-arch or build-indep targets are
+ provided in the rules file, 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
@@ -2491,18 +2503,21 @@ endif
- Each paragraph consists of a series of data fields; each
- field consists of the field name, followed by a colon and
- then the data/value associated with that field. The field
- name is composed of printable ASCII characters (i.e.,
- characters that have values between 33 and 126, inclusive)
- except colon and must not with a begin with #. The
- field ends at the end of the line or at the end of the
- last continuation line (see below). Horizontal whitespace
- (spaces and tabs) may occur immediately before or after the
- value and is ignored there; it is conventional to put a
- single space after the colon. For example, a field might
- be:
+ Each paragraph consists of a series of data fields. Each field
+ consists of the field name followed by a colon and then the
+ data/value associated with that field. The field name is
+ 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, #.
+
+
+
+ The field ends at the end of the line or at the end of the last
+ continuation line (see below). Horizontal whitespace (spaces
+ and tabs) may occur immediately before or after the value and is
+ ignored there; it is conventional to put a single space after
+ the colon. For example, a field might be:
Package: libc6
@@ -2543,7 +2558,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.
@@ -2631,6 +2646,7 @@ Package: libc6
- Depends et al
- Description (mandatory)
- Homepage
+ - Built-Using
@@ -2686,6 +2702,7 @@ Package: libc6
- Maintainer (mandatory)
- Description (mandatory)
- Homepage
+ - Built-Using
@@ -2696,7 +2713,7 @@ Package: libc6
This file consists of a single paragraph, possibly surrounded by
a PGP signature. The fields of that paragraph are listed below.
- Their syntax is described above, in [.
+ Their syntax is described above, in ][.
]
- Format (mandatory)
@@ -2717,7 +2734,7 @@ Package: libc6
- The source package control file is generated by
+ The Debian source control file is generated by
dpkg-source when it builds the source
archive, from other files in the source package,
described above. When unpacking, it is checked against
@@ -2974,34 +2991,42 @@ Package: libc6
- In the source package control file .dsc, this
- field may contain either the architecture
- wildcard any or a list of architectures and
- architecture wildcards separated by spaces. If a list is
- given, it may include (or consist solely of) the special
+ In the Debian source control file .dsc, this
+ field contains a list of architectures and architecture
+ wildcards separated by spaces. When the list contains the
+ architecture wildcard any, the only other value
+ allowed in the list is all.
+
+
+
+ The list may include (or consist solely of) the special
value all. In other words, in .dsc
files unlike the debian/control, all may
occur in combination with specific architectures.
- The Architecture field in the source package control
+ The Architecture field in the Debian source control
file .dsc is generally constructed from
the Architecture fields in
the debian/control in the source package.
- Specifying any indicates that the source package
+ Specifying only any indicates that the source package
isn't dependent on any particular architecture and should
compile fine on any one. The produced binary package(s)
- will either be specific to whatever the current build
- architecture is or will be architecture-independent.
+ will be specific to whatever the current build architecture is.
Specifying only all indicates that the source package
- will only build architecture-independent packages. If this is
- the case, all must be used rather than any;
- any implies that the source package will build at
- least one architecture-dependent package.
+ will only build architecture-independent packages.
+
+
+
+ Specifying any all indicates that the source package
+ isn't dependent on any particular architecture. The set of
+ produced binary packages will include at least one
+ architecture-dependant package and one architecture-independent
+ package.
@@ -3294,6 +3319,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.
-
@@ -3304,7 +3330,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.
-
@@ -3700,11 +3727,13 @@ Checksums-Sha256:
DM-Upload-Allowed
- The most recent version of a package uploaded to unstable or
- experimental must include the field DM-Upload-Allowed:
- yes in the source section of its source control file for
- the Debian archive to accept uploads signed with a key in the
- Debian Maintainer keyring. See the General
+ 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.
@@ -3719,7 +3748,7 @@ Checksums-Sha256:
Additional user-defined fields may be added to the
source package control file. Such fields will be
ignored, and not copied to (for example) binary or
- source package control files or upload control files.
+ Debian source control files or upload control files.
@@ -3736,7 +3765,7 @@ Checksums-Sha256:
field name after the hyphen will be used in the output
file. Where the letter B is used the field
will appear in binary package control files, where the
- letter S is used in source package control
+ letter S is used in Debian source control
files and where C is used in upload control
(.changes) files.
@@ -3747,7 +3776,7 @@ Checksums-Sha256:
XBS-Comment: I stand between the candle and the star.
- then the binary and source package control files will contain the
+ then the binary and Debian source control files will contain the
field
Comment: I stand between the candle and the star.
@@ -4580,13 +4609,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).
@@ -4618,7 +4647,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.)
@@ -4649,7 +4679,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
@@ -4686,7 +4717,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:
@@ -5372,6 +5404,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)
+
+
+
@@ -6149,11 +6228,11 @@ install -m644 debian/shlibs.package debian/package/DEBIAN/
File System Structure
- The location of all installed files and directories must
- comply with the Filesystem Hierarchy Standard (FHS),
- version 2.3, with the exceptions noted below, and except
- where doing so would violate other terms of Debian
- Policy. The following exceptions to the FHS apply:
+ The location of all files and directories must comply with the
+ Filesystem Hierarchy Standard (FHS), version 2.3, with the
+ exceptions noted below, and except where doing so would
+ violate other terms of Debian Policy. The following
+ exceptions to the FHS apply:
-
@@ -6234,6 +6313,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
@@ -6324,12 +6422,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
@@ -6377,6 +6474,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.
+
+
@@ -6751,15 +6871,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.
]
@@ -7128,18 +7247,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
@@ -7149,7 +7270,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
@@ -7160,15 +7282,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
@@ -7211,6 +7336,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.
+
+
@@ -7486,9 +7649,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
@@ -7865,10 +8027,13 @@ fname () {
You may wish to restrict your script to SUSv3 features plus the
above set when possible so that it may use /bin/sh
- as its interpreter. If your script works with dash
- (originally called ash), it probably complies with
- the above requirements, but if you are in doubt, use
- /bin/bash.
+ as its interpreter. Checking your script
+ with checkbashisms from
+ the devscripts package or running your script
+ with an alternate shell such as posh may help
+ uncover violations of the above requirements. If in doubt
+ whether a script complies with these requirements,
+ use /bin/bash.
@@ -7907,11 +8072,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.
+
@@ -9382,41 +9559,6 @@ name ["syshostname"]:
policy (such as for [).
]
-
-
- The OSF/Motif and OpenMotif libraries
-
-
- Programs that require the non-DFSG-compliant OSF/Motif or
- OpenMotif libraries
- OSF/Motif and OpenMotif are collectively referred to as
- "Motif" in this policy document.
-
- should be compiled against and tested with LessTif (a free
- re-implementation of Motif) instead. If the maintainer
- judges that the program or programs do not work
- sufficiently well with LessTif to be distributed and
- supported, but do so when compiled against Motif, then two
- versions of the package should be created; one linked
- statically against Motif and with -smotif
- appended to the package name, and one linked dynamically
- against Motif and with -dmotif appended to the
- package name.
-
-
-
- Both Motif-linked versions are dependent
- upon non-DFSG-compliant software and thus cannot be
- uploaded to the main distribution; if the
- software is itself DFSG-compliant it may be uploaded to
- the contrib distribution. While known existing
- versions of Motif permit unlimited redistribution of
- binaries linked against the library (whether statically or
- dynamically), it is the package maintainer's
- responsibility to determine whether this is permitted by
- the license of the copy of Motif in their possession.
-
-
@@ -9781,9 +9923,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.
@@ -9802,8 +9943,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.
@@ -9842,7 +9983,31 @@ END-INFO-DIR-ENTRY
You should not use the copyright file as a general README
file. If your package has such a file it should be
installed in /usr/share/doc/package/README or
- README.Debian or some other appropriate place.
+ README.Debian or some other appropriate place.
+
+
+
+ All copyright files must be encoded in UTF-8.
+
+
+
+ Machine-readable copyright information
+
+
+ A specification for a standard, machine-readable format
+ for debian/copyright files is maintained as part
+ of the debian-policy package. This
+ document may be found in the copyright-format
+ files in the debian-policy package. It is
+ also available from the Debian web mirrors at
+ .
+
+
+
+ Use of this format is optional.
+
+
@@ -10372,10 +10537,10 @@ END-INFO-DIR-ENTRY
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 take no
- special action to gain root privilege, so that for
- most packages it will have to be invoked as root to
- start with.
+ then dpkg-buildpackage will use
+ the fakeroot command, which is sufficient
+ to build most packages without actually requiring root
+ privileges.
-b, -B
-
@@ -11298,7 +11463,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
@@ -11319,4 +11484,4 @@ END-INFO-DIR-ENTRY
-
+