<p>
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),
+ declare a "Depends", "Recommends", or
+ "Build-Depends" relationship on a non-main package),
</p>
</item>
<item>
<sect1>
<heading>The maintainer of a package</heading>
-
- <p>
- Every package should have exactly one maintainer at a
- time. This person is responsible that the license of the
- package's software complies with the policy of the
- distribution this package is included in.</p>
-
+ <p>
+ Every package must have a maintainer (the maintainer may
+ be one person or a group of people reachable from a common
+ email address, such as a mailing list). The maintainer is
+ responsible for ensuring that the package is placed in
+ the appropriate distribution
+ </p>
+
<p>
The maintainer must be specified in the
<tt>Maintainer</tt> control field with the correct name
the part of a user installing many packages. This means,
amongst other things, using the <tt>--quiet</tt> option on
<prgn>install-info</prgn>.</p>
-
+
<p>
- Packages should try to minimize the amount of prompting
- they need to do, and they should ensure that the user will
- only ever be asked each question once. This means that
- packages should try to use appropriate shared
- configuration files (such as <tt>/etc/papersize</tt> and
- <tt>/etc/news/server</tt>), rather than each prompting for
- their own list of required pieces of information.</p>
-
+ Errors which occur during the execution of an installation
+ script must be checked and the installation must not
+ continue after an error.
+ </p>
+
+ <p>
+ Note, that <ref id="scripts">, in general applies to package
+ maintainer scripts, too.
+ </p>
+
<p>
+ You should not use <tt>dpkg-divert</tt>' on a file
+ belonging to another package without consulting the
+ maintainer of that package first.
+ </p>
+ <p>
+ All packages which supply an instance of a common command
+ name (or, in general, filename) should generally use
+ <prgn>update-alternatives</prgn>, so that they may be
+ installed together. If <prgn>update-alternatives</prgn>
+ is not used, then each package must use
+ <var>Conflicts</var> to ensure that other packages are
+ de-installed. (In this case, it may be appropriate to
+ specify a conflict against earlier versions of something
+ that previously did not use
+ <prgn>update-alternatives</prgn> - this is an exception to
+ the usual rule that this not allowed).
+ </p>
+
+
+ <sect2>
+ <heading>Prompting in maintainer scripts</heading>
+ <p>
+ Package maintainer scripts may prompt the user if
+ necessary. Prompting may be accomplished by hand, or by
+ communicating with a program, such as
+ <prgn>debconf</prgn>, which conforms to the Debian
+ Configuration management specification, version 2 or
+ higher. (Included in the
+ <file>debconf_specification</file> files in the
+ <package>debian-policy</package> package.)
+ You may also find this file on the FTP site
+ <ftpsite>ftp.debian.org</ftpsite> in
+ <ftppath>/debian/doc/package-developer/debconf_specification.txt.gz</ftppath>
+ or your local mirror.
+ <footnote>
+ <p>
+ 2.5% of Debian packages
+ [<url id="http://kitenet.net/programs/debconf/stats/">]
+ use debconf to prompt the user at install time, and
+ this number is growing daily. The benefits of using
+ debconf are briefly explained at
+ <url id="http://kitenet.net/doc/debconf-doc/introduction.html">;
+ they include preconfiguration, (mostly)
+ noninteractive installation, elimination of
+ redundant prompting, consistency of user interface,
+ etc.
+ </p>
+ <p>
+ With this increasing number of packages using
+ debconf, plus the existance of a nascent second
+ implementation of the Debian configuration
+ management system (<package>cdebconf</package>), and
+ the stabalization of the protocol these things use,
+ the time has finally come to reflect the use of
+ these things in policy.
+
+ </p>
+ </footnote>
+ </p>
+ <p>
+ Packages which use the Debian Configuration management
+ specification may contain an additional
+ <file>config</file> script and a <file>templates</file>
+ file in their control archive. The <prgn>config</prgn>
+ script can be run before the preinst, and before the
+ package is unpacked or any of its dependancies or
+ pre-dependancies are satisfied, so it must work using
+ only the tools present in the <em>Essential</em>
+ packages.
+ <footnote>
+ <p>
+ Debconf or another tool that implements the Debian
+ Configuration management specification will also be
+ installed, and any versioned dependancies on it will
+ be satisfied before preconfiguration begins.
+ </p>
+ </footnote>
+ </p>
+
+ <p>
+ Packages should try to minimize the amount of prompting
+ they need to do, and they should ensure that the user
+ will only ever be asked each question once. This means
+ that packages should try to use appropriate shared
+ configuration files (such as <tt>/etc/papersize</tt> and
+ <tt>/etc/news/server</tt>), and shared debconf variables
+ rather than each prompting for their own list of
+ required pieces of information.
+ </p>
+
+ <p>
It also means that an upgrade should not ask the same
questions again, unless the user has used <tt>dpkg
--purge</tt> to remove the package's configuration. The
documented.</p>
<p>
- If a package has a vitally important piece of information
- to pass to the user (such as "don't run me as I am, you
- must edit the following configuration files first or you
- risk your system emitting badly-formatted messages"), it
- should display this in the <prgn>postinst</prgn> script
- and prompt the user to hit return to acknowledge the
- message. Copyright messages do not count as vitally
- important (they belong in
- <tt>/usr/share/doc/<var>package</var>/copyright</tt>); neither
- do instructions on how to use a program (these should be
- in on line documentation, where all the users can see
- them).</p>
+ If a package has a vitally important piece of
+ information to pass to the user (such as "don't run me
+ as I am, you must edit the following configuration files
+ first or you risk your system emitting badly-formatted
+ messages"), it should display this in the
+ <prgn>config</prgn> or <prgn>postinst</prgn> script and
+ prompt the user to hit return to acknowledge the
+ message. Copyright messages do not count as vitally
+ important (they belong in
+ <tt>/usr/share/doc/<var>package</var>/copyright</tt>);
+ neither do instructions on how to use a program (these
+ should be in on line documentation, where all the users
+ can see them).</p>
<p>
Any necessary prompting should almost always be confined
- to the post-installation script, and should be protected
- with a conditional so that unnecessary prompting doesn't
- happen if a package's installation fails and the
- <prgn>postinst</prgn> is called with
+ to the <prgn>config</prgn> or <prgn>postinst</prgn>
+ script. If it is done in the <prgn>postinst</prgn>, it
+ should be protected with a conditional so that unnecessary
+ prompting doesn't happen if a package's installation fails
+ and the <prgn>postinst</prgn> is called with
<tt>abort-upgrade</tt>, <tt>abort-remove</tt> or
<tt>abort-deconfigure</tt>.</p>
- <p>
- Errors which occur during the execution of an installation
- script should be checked and the installation should not
- continue after an error.</p>
-
- <p>
- Note, that <ref id="scripts">, in general applies to
- package maintainer scripts, too.</p>
-
- <p>
- You should not use <prgn>dpkg-divert</prgn> on a file
- belonging to another package without consulting the maintainer
- of that package first.</p>
-
- <p>
- All packages which supply an instance of a common command
- name (or, in general, filename) should generally use
- <prgn>update-alternatives</prgn>, so that they may be
- installed together. If <prgn>update-alternatives</prgn>
- is not used, then each package must use <tt>Conflicts</tt>
- to ensure that other packages are de-installed. (In this
- case, it may be appropriate to specify a conflict against
- earlier versions of something that previously did not use
- <prgn>update-alternatives</prgn> -- this is an exception to
- the usual rule that this not allowed).
- </p>
</sect1>
</sect>
<sect>
making a new changelog entry rather than "rewriting history"
by editing old changelog entries)</p>
- <p>
- A copy of the file which will be installed in
- <tt>/usr/share/doc/<var>package</var>/copyright</tt> should be
- in <tt>debian/copyright</tt>.</p>
-
<p>
In non-experimental packages you must only use a format for
<tt>debian/changelog</tt> which is supported by the most
<p>
The version number format is:
- &lsqb<var>epoch</var><tt>:</tt>]<var>upstream-version</var>[<tt>-/<var>debian-revision</var>].</tt></var>
+ &lsqb<var>epoch</var><tt>:</tt>]<var>upstream-version</var>[<tt>-/<var>debian-revision</var>].</tt>
</p>
<p>
</p>
<p>
- Broadly speaking the <prgn></prgn> is called before
+ Broadly speaking the <prgn>preinst</prgn> is called before
(a particular version of) a package is installed, and the
<prgn>postinst</prgn> afterwards; the <prgn>prerm</prgn>
before (a version of) a package is removed and the
<p>
This is done using the <tt>Depends</tt>, <tt>Recommends</tt>,
- <tt>Suggests</tt>, <tt>Conflicts</tt>, <tt>Provides</tt> and
- <tt>Replaces</tt> control file fields.
+ <tt>Suggests</tt>, <tt>Enhances</tt>, <tt>Conflicts</tt>,
+ <tt>Provides</tt> and <tt>Replaces</tt> control file fields.
</p>
<p>
<sect>
<heading>Binary Dependencies - <tt>Depends</tt>,
- <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Pre-Depends</tt>
+ <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
+ <tt>Pre-Depends</tt>
</heading>
<p>
- These four fields are used to declare a dependency by one
- package on another. They appear in the depending package's
- control file.
+ These five fields are used to declare a dependency
+ relationship by one package on another. They appear in the
+ depending package's control file.
</p>
<p>
perhaps enhance its usefulness, but that installing
this one without them is perfectly reasonable.
</p>
+ </item>
+ <tag><tt>Enhances</tt></tag>
+ <item>
+ <p>
+ This field is similar to Suggests but works in the
+ opposite direction. It is used to declare that a
+ package can enhance the functionality of another
+ package.
+ </p>
</item>
<tag><tt>Pre-Depends</tt></tag>
The <prgn>foo</prgn> binary depends on the
<prgn>libbar</prgn> shared library, but no package seems
to provide a <tt>*.shlibs</tt> file in
- <tt></tt>var/lib/dpkg/info/. Let's determine the package
+ <tt>var/lib/dpkg/info/</tt>. Let's determine the package
responsible:
</p>
each system, should use `<tt>adduser --system</tt>' to
create the group and/or user. <prgn>adduser</prgn>
will check for the existence of the user or group, and
- if necessary choose an unused id based on the ranged
+ if necessary choose an unused id based on the ranges
specified in <tt>adduser.conf</tt>.</p></item>
<tag>65534:</tag>
<item>
- <p>User `<tt>nobody</tt>.'</p></item>
+ <p>User `<tt>nobody</tt>.' The corresponding gid refers
+ to the group `<tt>nogroup</tt>.'</p></item>
<tag>65535:</tag>
There are at least two different, yet functionally
equivalent, ways of handling these scripts. For the sake
of simplicity, this document describes only the symbolic
- link method. However, it must not be assumed that this
- method is being used, and any manipulation of the various
- runlevel behaviours must be performed using
- <prgn>update-rc.d</prgn> as described below and not by
- manually installing symlinks. For information on the
+ link method. However, it must not be assumed by maintainer
+ scripts that this method is being used, and any automated
+ manipulation of the various runlevel behaviours by
+ maintainer scripts must be performed using `update-rc.d'
+ as described below and not by manually installing or
+ removing symlinks. For information on the
implementation details of the other method, implemented in
the <tt>file-rc</tt> package, please refer to the
documentation of that package.</p>
<example>
test -f <var>program-executed-later-in-script</var> || exit 0
</example></p>
+
+ <p>
+ Often there are some values in the `<tt>init.d</tt>'
+ scripts that a system administrator will frequently want
+ to change. While the scripts are frequently conffiles,
+ modifying them requires that the administrator merge in
+ their changes each time the package is upgraded and the
+ conffile changes. To ease the burden on the system
+ administrator, such configurable values should not be
+ placed directly in the script. Instead, they should be
+ placed in a file in `<tt>/etc/default</tt>', which
+ typically will have the same base name as the
+ `<tt>init.d</tt>' script. This extra file can be sourced
+ by the script when the script runs. It must contain only
+ variable settings and comments.
+ </p>
+
+ <p>
+ To ensure that vital configurable values are always
+ available, the `<tt>init.d</tt>' script should set default
+ values for each of the shell variables it uses before
+ sourcing the <tt>/etc/default/</tt> file. Also, since the
+ `<tt>/etc/default/</tt>' file is often a conffile, the
+ `<tt>init.d</tt>' script must behave sensibly without
+ failing if it is deleted.
+ </p>
+
</sect1>
<sect1>
nameserver a <tt>HUP</tt> signal (causing it to reload its
configuration); this way the user can say
<tt>/etc/init.d/bind reload</tt> to reload the name
- server.</p>
+ server. The script has one configurable value, which can
+ be used to pass parameters to the named program at
+ startup.
+ </p>
<p>
<example>
# <rob@mars.org>, edited by iwj and cs
test -x /usr/sbin/named || exit 0
+
+ # Source defaults file.
+ PARAMS=''
+ if [ -f /etc/default/bind ]; then
+ . /etc/default/bind
+ fi
+
case "$1" in
start)
echo -n "Starting domain name service: named"
- start-stop-daemon --start --quiet --exec /usr/sbin/named
+ start-stop-daemon --start --quiet --exec /usr/sbin/named \
+ -- $PARAMS
echo "."
;;
stop)
echo -n "Restarting domain name service: named"
start-stop-daemon --stop --quiet \
--pidfile /var/run/named.pid --exec /usr/sbin/named
- start-stop-daemon --start --verbose --exec /usr/sbin/named
+ start-stop-daemon --start --verbose --exec /usr/sbin/named \
+ -- $PARAMS
echo "."
;;
force-reload|reload)
esac
exit 0
- </example></p>
-
+ </example>
+ </p>
+
+ <p>
+ Complementing the above init script is a file
+ '<tt>/etc/default/bind</tt>', which contains configurable
+ parameters used by the script.
+ </p>
+ <p>
+ <example>
+ # Specified parameters to pass to named. See named(8).
+ # You may uncomment the following line, and edit to taste.
+ #PARAMS="-u nobody"
+ </example>
+ </p>
+
<p>
Another example on which to base your <tt>/etc/init.d</tt>
scripts is in <tt>/etc/init.d/skeleton</tt>.</p>
<p>
Menu entries should follow the current menu policy as
defined in the file <ftpsite>ftp.debian.org</ftpsite> in
- <ftppath>/debian/doc/package-developer/menu-policy.txt</ftppath>
+ <ftppath>/debian/doc/package-developer/menu-policy.text.gz</ftppath>
or your local mirror. In addition, it is included in the
<tt>debian-policy</tt> package.
</p>
compose, edit or print MIME types should register themselves
as such following the current MIME support policy as defined
in the file found on <ftpsite>ftp.debian.org</ftpsite> in
- <ftppath>/debian/doc/package-developer/mime_policy.txt</ftppath>
+ <ftppath>/debian/doc/package-developer/mime-policy.text.gz</ftppath>
or your local mirror. In addition, it is included in the
<tt>debian-policy</tt> package.
</p>
</p>
</footnote>
+
<example>
CFLAGS = -O2 -Wall
INSTALL = install
+ INSTALL_FILE = $(INSTALL) -p -o root -g root -m 644
+ INSTALL_PROGRAM = $(INSTALL) -p -o root -g root -m 755
+ INSTALL_SCRIPT = $(INSTALL) -p -o root -g root -m 755
+ INSTALL_DIR = $(INSTALL) -p -d -o root -g root -m 755
ifneq (,$(findstring debug,$(DEB_BUILD_OPTIONS)))
CFLAGS += -g
endif
ifeq (,$(findstring nostrip,$(DEB_BUILD_OPTIONS)))
- INSTALL += -s
+ INSTALL_PROGRAM += -s
endif
- </example></p>
+ </example>
+
+ Please note that the above example is merely informative,
+ and is not a policy mandate. You may have to massage this
+ example in order to make it work for your package.
+
+ </p>
<p>
It is up to the package maintainer to decide what
<p>
If a package needs any special device files that are not
included in the base system, it must call
- <prgn>makedev</prgn> in the <tt>postinst</tt> script,
+ <prgn>MAKEDEV</prgn> in the <tt>postinst</tt> script,
after asking the user for permission to do so.</p>
<p>
<sect1>
<heading>Sharing configuration files</heading>
<p>
- Packages that are not tagged as <em>conflicting</em> with
- each other must not specify the same file as
- <tt>conffile</tt>.</p>
+ Packages which specify the same file as
+ `<tt>conffile</tt>' must be tagged as <em>conflicting</em>
+ with each other.
+ </p>
<p>
The maintainer scripts must not alter the conffile of
<tt>/usr/bin/sensible-editor</tt> does.</p>
<p>
- Since the Debian base system already provides an editor and
- a pager program, it is not required for a package to depend on
+ It is not required for a package to depend on
`editor' and `pager', nor is it required for a package to
- provide such virtual packages.</p></sect>
+ provide such virtual packages.
+ <footnote>
+ <p>
+ The Debian base system already provides an editor and
+ a pager program,
+ </p>
+ </footnote>
+ </p>
+
+ </sect>
<sect id="web-appl">
<sect>
- <heading>Mail transport agents</heading>
+ <heading>Mail transport, delivery and user agents</heading>
<p>
Debian packages which process electronic mail, whether
All Debian MUAs, MTAs, MDAs and other mailbox accessing
programs (like IMAP daemons) must lock the mailbox in an
NFS-safe way. This means that <tt>fcntl()</tt> locking must
- to be combined with dot locking. To avoid dead locks, a
+ be combined with dot locking. To avoid deadlocks, a
program should use <tt>fcntl()</tt> first and dot locking
after this or alternatively implement the two locking
methods in a non blocking way<footnote>
in question is of standard or higher priority, in which case
X-specific binaries may be split into a separate package, or
alternative versions of the package with X support may be
- provided.<footnote>
- <p>
- <strong>NOTE</strong> The forthcoming major X Window
- System release shall probably change this
- drastically.
- </p>
- <p>
- This seems to be more what people want. It will enable
- packages like vim-tty to become legal if they are
- promoted to standard priority. Also, that X client in
- mtools can be split into its own package and made
- optional.
- </p>
- <p>
- This paves the way for xlib6g and xfree86-common to be
- moved from standard to optional, <strong>if</strong> all
- Xlib dependent packages are moved from standard to
- optional priority (or if non-Xlib-linked versions are
- retained in standard). That, however is up to the
- affected package maintainers and the archive
- maintainers, and is not mandated by this policy.
- </p>
- </footnote>
+ provided.
</p>
virtual package <tt>xserver</tt>.
<footnote>
<p>
- Rationale: implement current practice, and provide an
- actual policy for usage of the "xserver" virtual package
- which appears in the virtual packages list.
- In a nutshell, X servers that interface directly with
- the display and input hardware or via another subsystem
- (e.g., GGI) should provide xserver. Things like Xvfb,
- Xnest, and Xprt should not. <strong>NOTE</strong> The
- forthcoming major X Window System release shall probably
- change this drastically.
+ This implements current practice, and provides an actual
+ policy for usage of the "xserver" virtual package which
+ appears in the virtual packages list. In a nutshell, X
+ servers that interface directly with the display and input
+ hardware or via another subsystem (e.g., GGI) should provide
+ xserver. Things like Xvfb, Xnest, and Xprt should not.
</p>
</footnote>
</p>
<item>
BDF fonts should be converted to PCF fonts with the
<tt>bdftopcf</tt> utility (available in the
- <tt>xbase-clients</tt> package, <tt>gzip</tt>ped, and
+ <tt>xutils</tt> package, <tt>gzip</tt>ped, and
placed in a directory that corresponds to their
resolution:
<list>
</item>
<item>
Font packages must declare a dependency on
- <tt>xbase-clients</tt> and, in the package
+ <tt>xutils</tt> and, in the package
post-installation and post-removal scripts, invoke the
<tt>mkfontdir</tt> command on each directory into
which they installed fonts.
<item>
Font packages that provide one or more
<tt>fonts.scale</tt> files as described above must declare a
- versioned dependency on <tt>xbase-clients (>=
- 3.3.3.1-5)</tt> and invoke <tt>update-fonts-scale</tt> on each
+ versioned dependency on <tt>xutils (>=
+ 4.0.2)</tt> and invoke <tt>update-fonts-scale</tt> on each
directory into which they installed fonts
<em>before</em> invoking <tt>mkfontdir</tt> on that
directory. This invocation must occur in both the
<item>
Font packages that provide one or more
<tt>fonts.alias</tt> files as described above must
- declare a versioned dependency on <tt>xbase-clients
- (>= 3.3.3.1-5)</tt> and, in the package
+ declare a versioned dependency on <tt>xutils
+ (>= 4.0.2)</tt> and, in the package
post-installation and post-removal scripts, invoke
<tt>update-fonts-alias</tt> on each directory into
which they installed fonts.
in the binary package. However, you don't need to install
the instructions for building and installing the package, of
course!</p>
+
+ <p>
+ Files in <tt>/usr/share/doc</tt> should not be referenced by
+ any program, and the system administrator should be able to
+ delete them without causing any programs to break. Any files
+ that are referenced by programs but are also useful as
+ standalone documentation should be installed under
+ <tt>/usr/share/<package$gt;/</tt> and symlinked in
+ <tt>/usr/share/doc/<package$gt;/</tt>.
+ </p>
+
</sect>
<sect id="usrdoc">
compared to the upstream one. It should name the original
authors of the package and the Debian maintainer(s) who were
involved with its creation.</p>
+
+ <p>
+ A copy of the file which will be installed in
+ <tt>/usr/share/doc/<var>package</var>/copyright</tt> should be
+ in <tt>debian/copyright</tt>.</p>
+
<p>
/usr/share/doc/<package-name> may be a symbolic link to a
relationship on the second. These rules are important
because copyrights must be extractable by mechanical
means.</p>
-
+
<p>
Packages distributed under the UCB BSD license, the Artistic
license, the GNU GPL, and the GNU LGPL should refer to the
projects / debian / debian-policy.git / blobdiff