X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=policy.sgml;h=733e1f0c6f39c9c025a9f5cf8f1e10b75d1e2816;hb=8005797abdddb3b4762ed13d88ef22bc15ad8c75;hp=d1589b83b9a3f7b2f06e5596c9b1be154e9b52ad;hpb=73fd57396f4bd6aa8ccad5f6d3d99a91e348017d;p=debian%2Fdebian-policy.git
diff --git a/policy.sgml b/policy.sgml
index d1589b8..733e1f0 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -157,17 +157,14 @@
This manual is distributed via the Debian package
- debian-policy.
+ .
The current version of this document is also available from
the Debian web mirrors at
- and from the Debian archive mirrors at
- .
+ id="http://www.debian.org/doc/debian-policy/">.
Also available from the same directory are several other
formats: policy.html.tar.gz, policy.pdf.gz
and policy.ps.gz.
@@ -691,12 +688,12 @@
admin, base, comm,
contrib, devel, doc,
editors, electronics, embedded,
- games, gnome graphics,
+ games, gnome, graphics,
hamradio, interpreters, kde,
libs, libdevel, mail,
math, misc, net, news,
non-US, non-free, oldlibs,
- otherosfs, perl, python
+ otherosfs, perl, python,
science, shells,
sound, tex, text,
utils, web, x11.
@@ -859,11 +856,11 @@
To prevent having to use epochs for every new upstream
- version, the version number should be changed to the
- following format in such cases: "19960501", "19961224". It
- is up to the maintainer whether he/she wants to bother the
- upstream maintainer to change the version numbers upstream,
- too.
+ version, the date based portion of the version number
+ should be changed to the following format in such cases:
+ "19960501", "19961224". It is up to the maintainer whether
+ he/she wants to bother the upstream maintainer to change
+ the version numbers upstream, too.
@@ -1082,10 +1079,7 @@
package names can be found in the debian-policy package.
It is also available from the Debian web mirrors at
- and from the Debian archive mirrors at
- .
+ id="http://www.debian.org/doc/packaging-manuals/virtual-package-names-list.txt">.
@@ -1191,7 +1185,7 @@
The package installation scripts should avoid producing
- output which it is unnecessary for the user to see and
+ 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
@@ -1234,42 +1228,17 @@
Prompting in maintainer scripts
Package maintainer scripts may prompt the user if
- necessary. Prompting may be accomplished by hand
- From the Jargon file: by hand 2. By extension,
- writing code which does something in an explicit or
- low-level way for which a presupplied library
- (debconf, in this instance) routine ought
- to have been available.
-
- (but this is deprecated), or by communicating through a program
- which conforms to the Debian Configuration management
- specification, version 2 or higher, such as
- debconf
-
- 6% of Debian packages [see ] currently use
- debconf to prompt the user at
- install time, and this number is growing daily. The
- benefits of using debconf are briefly explained at
- ; they include
- preconfiguration, (mostly) noninteractive
- installation, elimination of redundant prompting,
- consistency of user interface, etc.
-
-
-
- With this increasing number of packages using
- debconf, plus the existence of a
- nascent second implementation of the Debian
- configuration management system
- (cdebconf), and the stabilization
- of the protocol these things use, the time has
- finally come to reflect the use of these things in
- policy.
-
- .
+ necessary. Prompting should be done by communicating
+ through a program, such as debconf, which
+ conforms to the Debian Configuration management
+ specification, version 2 or higher. Prompting the user by
+ other means, such as by hand
+ From the Jargon file: by hand 2. By extension,
+ writing code which does something in an explicit or
+ low-level way for which a presupplied library
+ (debconf, in this instance) routine ought
+ to have been available.
+ , is now deprecated.
@@ -1278,10 +1247,7 @@
debian-policy package.
It is also available from the Debian web mirrors at
- and from the Debian archive mirrors at
- .
+ id="http://www.debian.org/doc/packaging-manuals/debconf_specification.html">.
@@ -1511,14 +1477,15 @@
- If you need to edit a Makefile where
- GNU-style configure scripts are used, you
- should edit the .in files rather than editing the
+ If you need to edit a Makefile where GNU-style
+ configure scripts are used, you should edit the
+ .in files rather than editing the
Makefile directly. This allows the user to
reconfigure the package if necessary. You should
not configure the package and edit the generated
- Makefile! This makes it impossible for
- someone else to later reconfigure the package.
+ Makefile! This makes it impossible for someone
+ else to later reconfigure the package without losing the
+ changes you made.
@@ -1686,7 +1653,7 @@
contact the dpkg maintainer to have the
parser script for it included in the dpkg
package. (You will need to agree that the parser and its
- manpage may be distributed under the GNU GPL, just as the rest
+ man page may be distributed under the GNU GPL, just as the rest
of dpkg is.)
@@ -2014,7 +1981,7 @@
The architectures we build on and build for are determined
by make variables using the utility
- dpkg-architecture.
+ dpkg-architecture.
You can determine the
Debian architecture and the GNU style architecture
specification string for the build machine (the machine type
@@ -2314,6 +2281,7 @@ Package: libc6
syntax is described above, in [.
]
+ - Format
- Source (mandatory)
- Version (mandatory)
- Maintainer (mandatory)
@@ -2497,31 +2465,54 @@ Package: libc6
Architecture
- This is the architecture string; it is a single word for
- the Debian architecture. The special value all
- indicates that the package is architecture-independent.
+ Depending on context and the control file used, the
+ Architecture field can include the following sets of
+ values:
+
+ - A unique single word identifying a Debian machine
+ architecture, see
[.
+ ]- all, which indicates an
+ architecture-independent package.
+
- any, which indicates a package available
+ for building on any architecture.
+
- source, which indicates a source package.
+
In the main debian/control file in the source
package, or in the source package control file
- .dsc, a list of architectures (separated by
- spaces) is also allowed, as is the special value
- any. A list indicates that the source will build
- an architecture-dependent package, and will only work
- correctly on the listed architectures. any
- indicates that though the source package isn't dependent
- on any particular architecture and should compile fine on
- any one, the binary package(s) produced are not
- architecture-independent but will instead be specific to
- whatever the current build architecture is.
+ .dsc, one may specify a list of architectures
+ separated by spaces, or the special values any or
+ all.
+
+
+
+ Specifying 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 be specific to whatever the current build architecture
+ is.
+ This is the most often used setting, and is recommended
+ for new packages that aren't Architecture: all.
+
- In a .changes file the Architecture
+ Specifying a list of architectures indicates that the source
+ will build an architecture-dependent package, and will only
+ work correctly on the listed architectures.
+ This is a setting used for a minority of cases where the
+ program is not portable. Generally, it should not be used
+ for new packages.
+
+
+
+
+ In a .changes file, the Architecture
field lists the architecture(s) of the package(s)
currently being uploaded. This will be a list; if the
- source for the package is being uploaded too the special
+ source for the package is also being uploaded, the special
entry source is also present.
@@ -2552,7 +2543,7 @@ Package: libc6
Package interrelationship fields:
Depends, Pre-Depends,
Recommends, Suggests, Conflicts,
- Provides, Replaces
+ Provides, Replaces, Enhances
@@ -3673,10 +3664,18 @@ Package: libc6
If there is no most recently configured version
- dpkg will pass a null argument; older versions
- of dpkg may pass <unknown> (including the
- angle brackets) in this case. Even older ones do not pass a
- second argument at all, under any circumstances.
+ dpkg will pass a null argument.
+
+
+ Historical note: Truly ancient (pre-1997) versions of
+ dpkg passed <unknown>
+ (including the angle brackets) in this case. Even older
+ ones did not pass a second argument at all, under any
+ circumstance. Note that upgrades using such an old dpkg
+ version are unlikely to work for other reasons, even if
+ this old argument behavior is handled by your postinst script.
+
+
@@ -3728,8 +3727,10 @@ Package: libc6
- No attempt is made to unwind after errors during
- removal.
+ If there are problems during this process, we call
+ postinst
+ abort-remove. No other attempt is made to unwind
+ after errors during removal.
@@ -4602,9 +4603,9 @@ Replaces: mail-transport-agent
libraries, it must provide a shlibs file for other
packages to use, and when a package is built which contains
any shared libraries or compiled binaries, it must run
- dpkg-shlibdeps on these to determine the
- libraries used and hence the dependencies needed by this
- package.
+ dpkg-shlibdeps
+ on these to determine the libraries used and hence the
+ dependencies needed by this package.
In the past, the shared libraries linked to were
determined by calling ldd, but now
@@ -4658,9 +4659,9 @@ Replaces: mail-transport-agent
In the following sections, we will first describe where the
various shlibs files are to be found, then how to
- use dpkg-shlibdeps, and finally the
- shlibs file format and how to create them if your
- package contains a shared library.
+ use dpkg-shlibdeps, and finally the shlibs
+ file format and how to create them if your package contains a
+ shared library.
@@ -4669,8 +4670,9 @@ Replaces: mail-transport-agent
There are several places where shlibs files are
found. The following list gives them in the order in which
- they are read by dpkg-shlibdeps. (The first
- one which gives the required information is used.)
+ they are read by
+ dpkg-shlibdeps.
+ (The first one which gives the required information is used.)
@@ -4764,10 +4766,11 @@ Replaces: mail-transport-agent
shlibs files
- Put a call to dpkg-shlibdeps into your
- debian/rules file. If your package contains only
- compiled binaries and libraries (but no scripts), you can
- use a command such as:
+ Put a call to
+ dpkg-shlibdeps
+ into your debian/rules file. If your package
+ contains only compiled binaries and libraries (but no scripts),
+ you can use a command such as:
dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* \
debian/tmp/usr/lib/*
@@ -4802,8 +4805,12 @@ dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* \
compiled libraries or binaries. In such a case, you will
need to use the -T option to the dpkg
utilities to specify a different substvars file.
- For more details on this and other options, see .
+
+
+
+ For more details on dpkg-shlibdeps, please see
+ [ and
+ .
]
@@ -5491,7 +5498,7 @@ test -f program-executed-later-in-script || exit 0
Directly managing the /etc/rc?.d links and directly
invoking the /etc/init.d/ initscripts should
be done only by packages providing the initscript
- subsystem (such as sysvinit and
+ subsystem (such as sysv-rc and
file-rc).
@@ -5560,7 +5567,7 @@ test -f program-executed-later-in-script || exit 0
For more information about using update-rc.d,
- please consult its manpage .
@@ -5601,11 +5608,11 @@ test -f program-executed-later-in-script || exit 0
<action> in their postinst
and prerm scripts to:
- if [ -x /usr/sbin/invoke-rc.d ] ; then
+ if command -v invoke-rc.d >/dev/null 2>&1; then
invoke-rc.d package <action>
- else
- /etc/init.d/package <action>
- fi
+ else
+ /etc/init.d/package <action>
+ fi
@@ -5618,7 +5625,7 @@ test -f program-executed-later-in-script || exit 0
For more information about using
- invoke-rc.d, please consult its manpage
+ invoke-rc.d, please consult its man page
.
@@ -6029,10 +6036,7 @@ Reloading description configuration...done.
files in the debian-policy package.
It is also available from the Debian web mirrors at
- and from the Debian archive mirrors at
- .
+ id="http://www.debian.org/doc/packaging-manuals/menu-policy/">.
@@ -6071,10 +6075,7 @@ Reloading description configuration...done.
files in the debian-policy package.
It is also available from the Debian web mirrors at
- and from the Debian archive mirrors at
- .
+ id="http://www.debian.org/doc/packaging-manuals/mime-policy/">.
@@ -6591,7 +6592,7 @@ strip --strip-unneeded your-lib
csh and tcsh should be avoided as
scripting languages. See Csh Programming Considered
Harmful, one of the comp.unix.* FAQs, which
- can be found at .
+ can be found at .
If an upstream package comes with csh scripts
then you must make sure that they start with
#!/bin/csh and make your package depend on the
@@ -7230,7 +7231,7 @@ done
string in some place, the following format should be
used: arch-os
The following architectures and operating systems are
- currently recognised by dpkg-archictecture.
+ currently recognised by dpkg-architecture.
The architecture, arch, is one of
the following: alpha, arm,
hppa, i386, ia64,
@@ -7706,7 +7707,7 @@ name ["syshostname"]:
-
If the window manager complies with ,
written by the , add 40 points.
@@ -8063,10 +8064,7 @@ name ["syshostname"]:
files in the debian-policy package.
It is also available from the Debian web mirrors at
- and from the Debian archive mirrors at
- .
+ id="http://www.debian.org/doc/packaging-manuals/perl-policy/">.
@@ -8163,7 +8161,7 @@ name ["syshostname"]:
and should be reported to the Debian Bug Tracking System (the
maintainer of the package is allowed to write this bug report
themselves, if they so desire). Do not close the bug report
- until a proper manpage is available.
+ until a proper man page is available.
It is not very hard to write a man page. See the
,
@@ -8175,10 +8173,10 @@ name ["syshostname"]:
- You may forward a complaint about a missing manpage to the
+ You may forward a complaint about a missing man page to the
upstream authors, and mark the bug as forwarded in the
Debian bug tracking system. Even though the GNU Project do
- not in general consider the lack of a manpage to be a bug,
+ not in general consider the lack of a man page to be a bug,
we do; if they tell you that they don't consider it a bug
you should leave the bug in our bug tracking system open
anyway.
@@ -8189,21 +8187,21 @@ name ["syshostname"]:
- If one manpage needs to be accessible via several names it
+ If one man page needs to be accessible via several names it
is better to use a symbolic link than the .so
feature, but there is no need to fiddle with the relevant
parts of the upstream source to change from .so to
symlinks: don't do it unless it's easy. You should not
create hard links in the manual page directories, nor put
absolute filenames in .so directives. The filename
- in a .so in a manpage should be relative to the
- base of the manpage tree (usually
+ in a .so in a man page should be relative to the
+ base of the man page tree (usually
/usr/share/man). If you do not create any links
(whether symlinks, hard links, or .so directives)
- in the filesystem to the alternate names of the manpage,
+ in the filesystem to the alternate names of the man page,
then you should not rely on man finding your
- manpage under those names based solely on the information in
- the manpage's header.
+ man page under those names based solely on the information in
+ the man page's header.
Supporting this in man often requires
unreasonable processing time to find a manual page or to
report that none exists, and moves knowledge into man's
@@ -8535,7 +8533,7 @@ install-info --quiet --remove /usr/share/info/foobar.info
This manual does not go into detail about the options and
usage of the package building and installation tools. It
should therefore be read in conjuction with those programs'
- manpages.
+ man pages.
@@ -8543,7 +8541,7 @@ install-info --quiet --remove /usr/share/info/foobar.info
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 manpages.
+ please see their man pages.
@@ -8581,7 +8579,7 @@ install-info --quiet --remove /usr/share/info/foobar.info
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) manpage.
+ deb(5) man page.
@@ -8652,7 +8650,7 @@ install-info --quiet --remove /usr/share/info/foobar.info
- See the manpage for details of how
+ See the man page for details of how
to examine the contents of this newly-created file. You may find the
output of following commands enlightening:
@@ -8662,7 +8660,7 @@ install-info --quiet --remove /usr/share/info/foobar.info
To view the copyright file for a package you could use this command:
- dpkg --fsys-tarfile filename.deb | tar xof usr/share/doc/\*copyright | less
+ dpkg --fsys-tarfile filename.deb | tar xO ./usr/share/doc/\*/copyright | pager
@@ -8830,7 +8828,7 @@ install-info --quiet --remove /usr/share/info/foobar.info
package.
-
+
dpkg-source - packs and unpacks Debian source
packages
@@ -8879,7 +8877,7 @@ install-info --quiet --remove /usr/share/info/foobar.info
-
+
dpkg-buildpackage - overall package-building
control script
@@ -8890,8 +8888,8 @@ install-info --quiet --remove /usr/share/info/foobar.info
dpkg-source, the debian/rules
targets clean, build and
binary, dpkg-genchanges and
- pgp to build a signed source and binary
- package upload.
+ gpg (or pgp) to build a signed
+ source and binary package upload.
@@ -8902,16 +8900,16 @@ install-info --quiet --remove /usr/share/info/foobar.info
-uc, -us
-
- Do not PGP-sign the .changes file or the
+ Do not sign the .changes file or the
source package .dsc file, respectively.
- -ppgp-command
+ -psign-command
-
- Invoke pgp-command instead of finding
- pgp on the PATH.
- pgp-command must behave just like
- pgp.
+ Invoke sign-command instead of finding
+ gpg or pgp on the PATH.
+ sign-command must behave just like
+ gpg or pgp.
-rroot-command
-
@@ -8938,7 +8936,7 @@ install-info --quiet --remove /usr/share/info/foobar.info
-
+
dpkg-gencontrol - generates binary package
control files
@@ -9001,7 +8999,7 @@ install-info --quiet --remove /usr/share/info/foobar.info
dpkg-genchanges.
-
+
dpkg-shlibdeps - calculates shared library
dependencies
@@ -9051,19 +9049,24 @@ install-info --quiet --remove /usr/share/info/foobar.info
- For example, the procps package generates two
- kinds of binaries, simple C binaries like ps
- which require a predependency and full-screen ncurses
- binaries like top which require only a
- recommendation. It can say in its debian/rules:
+ For example, a package that generates an essential part
+ which requires dependencies, and optional parts that
+ which only require a recommendation, would separate those
+ two sets of dependencies into two different fields.
+ At the time of writing, an example for this was the
+
+ It can say in its debian/rules:
- dpkg-shlibdeps -dPre-Depends ps -dRecommends top
+ dpkg-shlibdeps -dDepends program anotherprogram ... \
+ -dRecommends optionalpart anotheroptionalpart
and then in its main control file debian/control:
...
- Package: procps
- Pre-Depends: ${shlibs:Pre-Depends}
+ Depends: ${shlibs:Pre-Depends}
Recommends: ${shlibs:Recommends}
...
@@ -9084,7 +9087,7 @@ install-info --quiet --remove /usr/share/info/foobar.info
-
+
dpkg-distaddfile - adds a file to
debian/files
@@ -9123,8 +9126,10 @@ install-info --quiet --remove /usr/share/info/foobar.info
- dpkg-genchanges - generates a .changes upload
- control file
+
+
+ dpkg-genchanges - generates a .changes
+ upload control file
@@ -9145,8 +9150,10 @@ install-info --quiet --remove /usr/share/info/foobar.info
- dpkg-parsechangelog - produces parsed representation of
- a changelog
+
+
+ dpkg-parsechangelog - produces parsed
+ representation of a changelog
@@ -9159,8 +9166,10 @@ install-info --quiet --remove /usr/share/info/foobar.info
- dpkg-architecture -
- information about the build and host system
+
+
+ dpkg-architecture - information about the build and
+ host system
@@ -9426,15 +9435,11 @@ install-info --quiet --remove /usr/share/info/foobar.info
-
-
This is a compressed (with gzip -9)
tar file containing the source code from
- the upstream authors of the program. The tarfile
- unpacks into a directory
- package-upstream-version.orig,
- and does not contain files anywhere other than in
- there or in its subdirectories.
+ the upstream authors of the program.
+
@@ -9468,7 +9473,7 @@ install-info --quiet --remove /usr/share/info/foobar.info
automatically make the debian/rules file
executable (see below).
-
+
If there is no original source code - for example, if the
@@ -9476,8 +9481,8 @@ install-info --quiet --remove /usr/share/info/foobar.info
maintainer is the same as the upstream maintainer - the
format is slightly different: then there is no diff, and the
tarfile is named
- package_version.tar.gz and
- contains a directory
+ package_version.tar.gz,
+ and preferably contains a directory named
package-version.
@@ -9920,7 +9925,7 @@ install-info --quiet --remove /usr/share/info/foobar.info
- See the manpage for details.