system, but not every package we want to make accessible is
<em>free</em> in our sense (see the Debian Free Software
Guidelines, below), or may be imported/exported without
- restrictions. Thus, the archive is split into the distribution
- areas or categories based on their licenses and other restrictions.
+ restrictions. Thus, the archive is split into areas<footnote>
+ The Debian archive software uses the term "component" internally
+ and in the Release file format to refer to the division of an
+ archive. The Debian Social Contract simply refers to "areas."
+ This document uses terminology similar to the Social Contract.
+ </footnote> based on their licenses and other restrictions.
</p>
<p>
</p>
<p>
- The <em>main</em> category forms the
- <em>Debian GNU/Linux distribution</em>.
+ The <em>main</em> archive area forms the <em>Debian GNU/Linux
+ distribution</em>.
</p>
<p>
- Packages in the other distribution areas (<tt>contrib</tt>,
+ Packages in the other archive areas (<tt>contrib</tt>,
<tt>non-free</tt>) are not considered to be part of the Debian
distribution, although we support their use and provide
infrastructure for them (such as our bug-tracking system and
</sect>
<sect id="sections">
- <heading>Categories</heading>
+ <heading>Archive areas</heading>
<sect1 id="main">
- <heading>The main category</heading>
+ <heading>The main archive area</heading>
<p>
Every package in <em>main</em> must comply with the DFSG
</sect1>
<sect1 id="contrib">
- <heading>The contrib category</heading>
+ <heading>The contrib archive area</heading>
<p>
Every package in <em>contrib</em> must comply with the DFSG.
</sect1>
<sect1 id="non-free">
- <heading>The non-free category</heading>
+ <heading>The non-free archive area</heading>
<p>
Packages must be placed in <em>non-free</em> if they are
<heading>Sections</heading>
<p>
- The packages in the categories <em>main</em>,
- <em>contrib</em> and <em>non-free</em> are grouped further
- into <em>sections</em> to simplify handling.
+ The packages in the archive areas <em>main</em>,
+ <em>contrib</em> and <em>non-free</em> are grouped further into
+ <em>sections</em> to simplify handling.
</p>
<p>
- The category and section for each package should be
- specified in the package's <tt>Section</tt> control record
- (see <ref id="f-Section">). However, the maintainer of the
- Debian archive may override this selection to ensure the
- consistency of the Debian distribution. The
- <tt>Section</tt> field should be of the form:
+ The archive area and section for each package should be
+ specified in the package's <tt>Section</tt> control record (see
+ <ref id="f-Section">). However, the maintainer of the Debian
+ archive may override this selection to ensure the consistency of
+ the Debian distribution. The <tt>Section</tt> field should be
+ of the form:
<list compact="compact">
<item>
<em>section</em> if the package is in the
- <em>main</em> category,
+ <em>main</em> archive area,
</item>
<item>
- <em>segment/section</em> if the package is in
+ <em>area/section</em> if the package is in
the <em>contrib</em> or <em>non-free</em>
- distribution areas.
+ archive areas.
</item>
</list>
</p>
<p>
The Debian archive maintainers provide the authoritative
list of sections. At present, they are:
- <em>admin</em>, <em>comm</em>,
- <em>devel</em>, <em>doc</em>,
- <em>editors</em>, <em>electronics</em>, <em>embedded</em>,
- <em>games</em>, <em>gnome</em>, <em>graphics</em>,
- <em>hamradio</em>, <em>interpreters</em>, <em>kde</em>,
- <em>libs</em>, <em>libdevel</em>, <em>mail</em>,
- <em>math</em>, <em>misc</em>, <em>net</em>, <em>news</em>,
- <em>oldlibs</em>,
- <em>otherosfs</em>, <em>perl</em>, <em>python</em>,
- <em>science</em>, <em>shells</em>,
- <em>sound</em>, <em>tex</em>, <em>text</em>,
- <em>utils</em>, <em>web</em>, <em>x11</em>.
+ <em>admin</em>, <em>cli-mono</em>, <em>comm</em>, <em>database</em>,
+ <em>devel</em>, <em>debug</em>, <em>doc</em>, <em>editors</em>,
+ <em>electronics</em>, <em>embedded</em>, <em>fonts</em>,
+ <em>games</em>, <em>gnome</em>, <em>graphics</em>, <em>gnu-r</em>,
+ <em>gnustep</em>, <em>hamradio</em>, <em>haskell</em>,
+ <em>httpd</em>, <em>interpreters</em>, <em>java</em>, <em>kde</em>,
+ <em>kernel</em>, <em>libs</em>, <em>libdevel</em>, <em>lisp</em>,
+ <em>localization</em>, <em>mail</em>, <em>math</em>, <em>misc</em>,
+ <em>net</em>, <em>news</em>, <em>ocaml</em>, <em>oldlibs</em>,
+ <em>otherosfs</em>, <em>perl</em>, <em>php</em>, <em>python</em>,
+ <em>ruby</em>, <em>science</em>, <em>shells</em>, <em>sound</em>,
+ <em>tex</em>, <em>text</em>, <em>utils</em>, <em>vcs</em>,
+ <em>video</em>, <em>web</em>, <em>x11</em>, <em>xfce</em>,
+ <em>zope</em>.
</p>
</sect>
with required, important, standard or optional
priorities, or are only likely to be useful if you
already know what they are or have specialized
- requirements.
+ requirements (such as packages containing only detached
+ debugging symbols).
</item>
</taglist>
</p>
(see below), and should not do so unless they depend on a
particular version of that package.<footnote>
<p>
- Essential is defined as the minimal set of functionality
- that must be available and usable on the system even
- when packages are in an unconfigured (but unpacked)
- state. This is needed to avoid unresolvable dependency
- loops on upgrade. If packages add unnecessary
- dependencies on packages in this set, the chances that
- there <strong>will</strong> be an unresolvable
- dependency loop caused by forcing these Essential
- packages to be configured first before they need to be
- is greatly increased. It also increases the chances
- that frontends will be unable to
- <strong>calculate</strong> an upgrade path, even if one
- exists.
+ Essential is needed in part to avoid unresolvable dependency
+ loops on upgrade. If packages add unnecessary dependencies
+ on packages in this set, the chances that there
+ <strong>will</strong> be an unresolvable dependency loop
+ caused by forcing these Essential packages to be configured
+ first before they need to be is greatly increased. It also
+ increases the chances that frontends will be unable to
+ <strong>calculate</strong> an upgrade path, even if one
+ exists.
</p>
<p>
- Also, it's pretty unlikely that functionality from
- Essential shall ever be removed (which is one reason why
- care must be taken before adding to the Essential
- packages set), but <em>packages</em> have been removed
- from the Essential set when the functionality moved to a
- different package. So depending on these packages
- <em>just in case</em> they stop being essential does way
- more harm than good.
+ Also, functionality is rarely ever removed from the
+ Essential set, but <em>packages</em> have been removed from
+ the Essential set when the functionality moved to a
+ different package. So depending on these packages <em>just
+ in case</em> they stop being essential does way more harm
+ than good.
</p>
</footnote>
</p>
<heading>Essential packages</heading>
<p>
- Some packages are tagged <tt>essential</tt> for a system
- using the <tt>Essential</tt> control file field.
- The format of the <tt>Essential</tt> control field is
- described in <ref id="f-Essential">.
+ Essential is defined as the minimal set of functionality that
+ must be available and usable on the system at all times, even
+ when packages are in an unconfigured (but unpacked) state.
+ Packages are tagged <tt>essential</tt> for a system using the
+ <tt>Essential</tt> control file field. The format of the
+ <tt>Essential</tt> control field is described in <ref
+ id="f-Essential">.
</p>
<p>
appropriate.
</p>
+ <p>
+ Maintainers should take great care in adding any programs,
+ interfaces, or functionality to <tt>essential</tt> packages.
+ Packages may assume that functionality provided by
+ <tt>essential</tt> packages is always available without
+ declaring explicit dependencies, which means that removing
+ functionality from the Essential set is very difficult and is
+ almost never done. Any capability added to an
+ <tt>essential</tt> package therefore creates an obligation to
+ support that capability as part of the Essential set in
+ perpetuity.
+ </p>
+
<p>
You must not tag any packages <tt>essential</tt> before
this has been discussed on the <tt>debian-devel</tt>
<heading>Prompting in maintainer scripts</heading>
<p>
Package maintainer scripts may prompt the user if
- necessary. Prompting should be done by communicating
+ necessary. Prompting must be done by communicating
through a program, such as <prgn>debconf</prgn>, which
- conforms to the Debian Configuration management
- specification, version 2 or higher. Prompting the user by
- other means, such as by hand<footnote>
- 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
- (<em>debconf, in this instance</em>) routine ought
- to have been available.
- </footnote>, is now deprecated.
+ conforms to the Debian Configuration Management
+ Specification, version 2 or higher.
+ </p>
+
+ <p>
+ Packages which are essential, or which are dependencies of
+ essential packages, may fall back on another prompting method
+ if no such interface is available when they are executed.
</p>
<p>
- The Debian Configuration management specification is included
+ The Debian Configuration Management Specification is included
in the <file>debconf_specification</file> files in the
<package>debian-policy</package> package.
It is also available from the Debian web mirrors at
</p>
<p>
- Packages which use the Debian Configuration management
- specification may contain an additional
+ Packages which use the Debian Configuration Management
+ Specification may contain an additional
<prgn>config</prgn> script and a <tt>templates</tt>
file in their control archive<footnote>
The control.tar.gz inside the .deb.
Therefore it must work using only the tools present in
<em>essential</em> packages.<footnote>
<package>Debconf</package> or another tool that
- implements the Debian Configuration management
- specification will also be installed, and any
+ implements the Debian Configuration Management
+ Specification will also be installed, and any
versioned dependencies on it will be satisfied
before preconfiguration begins.
</footnote>
</p>
<p>
- Packages which use the Debian Configuration management
- specification must allow for translation of their messages
- by using a gettext-based system such as the one provided by
- the <package>po-debconf</package> package.
+ Packages which use the Debian Configuration Management
+ Specification must allow for translation of their user-visible
+ messages by using a gettext-based system such as the one
+ provided by the <package>po-debconf</package> package.
</p>
<p>
</p>
<p>
- The <var>date</var> should be in RFC822 format<footnote>
+ The <var>date</var> must be in RFC822 format<footnote>
This is generated by <tt>date -R</tt>.
- </footnote>; it should include the time zone specified
+ </footnote>; it must include the time zone specified
numerically, with the time zone name or abbreviation
optionally present as a comment in parentheses.
</p>
<p>
- The first "title" line with the package name should start
- at the left hand margin; the "trailer" line with the
- maintainer and date details should be preceded by exactly
+ The first "title" line with the package name must start
+ at the left hand margin. The "trailer" line with the
+ maintainer and date details must be preceded by exactly
one space. The maintainer details and the date must be
separated by exactly two spaces.
</p>
For more information on placement of the changelog files
within binary packages, please see <ref id="changelogs">.
</p>
-
- <sect1><heading>Alternative changelog formats</heading>
-
- <p>
- In non-experimental packages you must use a format for
- <file>debian/changelog</file> which is supported by the most
- recent released version of <prgn>dpkg</prgn>.
- </p>
-
- <p>
- It is possible to use a format different from the standard
- one by providing a changelog parser for the format you wish
- to use. The parser must have an API compatible with that
- expected by <prgn>dpkg-genchanges</prgn> and
- <prgn>dpkg-gencontrol</prgn>, and it must not interact with
- the user at all.
- <footnote>
- If there is general interest in the new format, you should
- contact the <package>dpkg</package> maintainer to have the
- parser script for it included in the <prgn>dpkg</prgn>
- package. (You will need to agree that the parser and its
- man page may be distributed under the GNU GPL, just as the rest
- of <prgn>dpkg</prgn> is.)
- </footnote>
- </p>
- </sect1>
</sect>
+
<sect id="dpkgcopyright">
<heading>Copyright: <file>debian/copyright</file></heading>
<p>
<p>
The meaning of the following tags has been standardized:
<taglist>
+ <tag>nocheck</tag>
+ <item>
+ This tag says to not run any build-time test suite
+ provided by the package.
+ </item>
<tag>noopt</tag>
<item>
The presence of this tag means that the package should
NUMJOBS = $(patsubst parallel=%,%,$(filter parallel=%,$(DEB_BUILD_OPTIONS)))
MAKEFLAGS += -j$(NUMJOBS)
endif
+
+build:
+ # ...
+ifeq (,$(filter nocheck,$(DEB_BUILD_OPTIONS)))
+ # Code to run the package test suite.
+endif
</example>
</p>
</sect1>
would mean a new paragraph.
</p>
+ <p>
+ All control files must be encoded in UTF-8.
+ </p>
</sect>
<sect id="sourcecontrolfiles">
See <ref id="substvars"> for details.
</p>
+ <p>
+ In addition to the control file syntax described <qref
+ id="controlsyntax">above</qref>, this file may also contain
+ comment lines starting with <tt>#</tt> without any preceding
+ whitespace. All such lines are ignored, even in the middle of
+ continuation lines for a multiline field, and do not end a
+ multiline field.
+ </p>
+
</sect>
<sect id="binarycontrolfiles">
scripts this means that you <em>almost always</em> need to
use <tt>set -e</tt> (this is usually true when writing shell
scripts, in fact). It is also important, of course, that
- they don't exit with a non-zero status if everything went
- well.
+ they exit with a zero status if everything went well.
</p>
<p>
Build-Depends: kernel-headers-2.2.10 [!hurd-i386],
hurd-dev [hurd-i386], gnumach-dev [hurd-i386]
</example>
+ requires <tt>kernel-headers-2.2.10</tt> on all architectures
+ other than hurd-i386 and requires <tt>hurd-dev</tt> and
+ <tt>gnumach-dev</tt> only on hurd-i386.
+ </p>
+
+ <p>
+ If the architecture-restricted dependency is part of a set of
+ alternatives using <tt>|</tt>, that alternative is ignored
+ completely on architectures that do not match the restriction.
+ For example:
+ <example compact="compact">
+Build-Depends: foo [!i386] | bar [!amd64]
+ </example>
+ is equivalent to <tt>bar</tt> on the i386 architecture, to
+ <tt>foo</tt> on the amd64 architecture, and to <tt>foo |
+ bar</tt> on all other architectures.
</p>
<p>
<tt>K</tt> prefix, but they too are called with the single
argument <tt>stop</tt>.
</p>
-
- <p>
- Also, if the script name ends in <tt>.sh</tt>, the script
- will be sourced in runlevel <tt>S</tt> rather than being
- run in a forked subprocess, but will be explicitly run by
- <prgn>sh</prgn> in all other runlevels.
- </p>
</sect1>
<sect1>
script must behave sensibly and not fail if the
<file>/etc/default</file> file is deleted.
</p>
+
+ <p>
+ <file>/var/run</file> and <file>/var/lock</file> may be mounted
+ as temporary filesystems<footnote>
+ For example, using the <tt>RAMRUN</tt> and <tt>RAMLOCK</tt>
+ options in <file>/etc/default/rcS</file>.
+ </footnote>, so the <file>init.d</file> scripts must handle this
+ correctly. This will typically amount to creating any required
+ subdirectories dynamically when the <file>init.d</file> script
+ is run, rather than including them in the package and relying on
+ <prgn>dpkg</prgn> to create them.
+ </p>
</sect1>
<sect1>
support <tt>-a</tt> and <tt>-o</tt> as binary logical
operators.</item>
<item><tt>local</tt> to create a scoped variable must be
- supported; however, <tt>local</tt> may or may not preserve
- the variable value from an outer scope and may or may not
- support arguments more complex than simple variables. Only
- uses such as:
+ supported, including listing multiple variables in a single
+ local command and assigning a value to a variable at the
+ same time as localizing it. <tt>local</tt> may or
+ may not preserve the variable value from an outer scope if
+ no assignment is present. Uses such as:
<example compact>
fname () {
- local a
- a=''
- # ... use a ...
+ local a b c=delta d
+ # ... use a, b, c, d ...
}
</example>
- must be supported.
+ must be supported and must set the value of <tt>c</tt> to
+ <tt>delta</tt>.
</item>
</list>
If a shell script requires non-SUSv3 features from the shell
</p>
<p>
- Mailboxes are generally mode 660
- <tt><var>user</var>:mail</tt> unless the system
- administrator has chosen otherwise. A MUA may remove a
- mailbox (unless it has nonstandard permissions) in which
- case the MTA or another MUA must recreate it if needed.
- Mailboxes must be writable by group mail.
+ Mailboxes are generally either mode 600 and owned by
+ <var>user</var> or mode 660 and owned by
+ <tt><var>user</var>:mail</tt><footnote>
+ There are two traditional permission schemes for mail spools:
+ mode 600 with all mail delivery done by processes running as
+ the destination user, or mode 660 and owned by group mail with
+ mail delivery done by a process running as a system user in
+ group mail. Historically, Debian required mode 660 mail
+ spools to enable the latter model, but that model has become
+ increasingly uncommon and the principle of least privilege
+ indicates that mail systems that use the first model should
+ use permissions of 600. If delivery to programs is permitted,
+ it's easier to keep the mail system secure if the delivery
+ agent runs as the destination user. Debian Policy therefore
+ permits either scheme.
+ </footnote>. The local system administrator may choose a
+ different permission scheme; packages should not make
+ assumptions about the permission and ownership of mailboxes
+ unless required (such as when creating a new mailbox). A MUA
+ may remove a mailbox (unless it has nonstandard permissions) in
+ which case the MTA or another MUA must recreate it if needed.
</p>
<p>
</p>
<p>
- Packages in the <em>contrib</em> or <em>non-free</em> categories
- should state in the copyright file that the package is not part
- of the Debian GNU/Linux distribution and briefly explain why.
+ Packages in the <em>contrib</em> or <em>non-free</em> archive
+ areas should state in the copyright file that the package is not
+ part of the Debian GNU/Linux distribution and briefly explain
+ why.
</p>
<p>
<p>
Packages distributed under the UCB BSD license, the Apache
license (version 2.0), the Artistic license, the GNU GPL
- (version 2 or 3), the GNU LGPL (versions 2, 2.1, or 3), and
- the GNU FDL (version 1.2) should refer to the corresponding
+ (version 2 or 3), the GNU LGPL (versions 2, 2.1, or 3), and the
+ GNU FDL (versions 1.2 or 1.3) should refer to the corresponding
files under <file>/usr/share/common-licenses</file>,<footnote>
<p>
In particular,
<file>/usr/share/common-licenses/GPL-3</file>,
<file>/usr/share/common-licenses/LGPL-2</file>,
<file>/usr/share/common-licenses/LGPL-2.1</file>,
- <file>/usr/share/common-licenses/LGPL-3</file>, and
- <file>/usr/share/common-licenses/GFDL-1.2</file>
+ <file>/usr/share/common-licenses/LGPL-3</file>,
+ <file>/usr/share/common-licenses/GFDL-1.2</file>, and
+ <file>/usr/share/common-licenses/GFDL-1.3</file>
respectively.
</p>
</footnote> rather than quoting them in the copyright
</example>
To view the copyright file for a package you could use this command:
<example>
- dpkg --fsys-tarfile <var>filename</var>.deb | tar xOf - \*/copyright | pager
+ dpkg --fsys-tarfile <var>filename</var>.deb | tar xOf - --wildcards \*/copyright | pager
</example>
</p>
</sect>
supposing that a <prgn>smailwrapper</prgn> package wishes to
install a wrapper around <file>/usr/sbin/smail</file>:
<example>
- if [ install = "$1" ]; then
- dpkg-divert --package smailwrapper --add --rename \
- --divert /usr/sbin/smail.real /usr/sbin/smail
- fi
- </example> Testing <tt>$1</tt> is necessary so that the script
- doesn't try to add the diversion again when
- <prgn>smailwrapper</prgn> is upgraded. The <tt>--package
- smailwrapper</tt> ensures that <prgn>smailwrapper</prgn>'s
- copy of <file>/usr/sbin/smail</file> can bypass the diversion and
- get installed as the true version.
+ dpkg-divert --package smailwrapper --add --rename \
+ --divert /usr/sbin/smail.real /usr/sbin/smail
+ </example> The <tt>--package smailwrapper</tt> ensures that
+ <prgn>smailwrapper</prgn>'s copy of <file>/usr/sbin/smail</file>
+ can bypass the diversion and get installed as the true version.
+ It's safe to add the diversion unconditionally on upgrades since
+ it will be left unchanged if it already exists, but
+ <prgn>dpkg-divert</prgn> will display a message. To suppress that
+ message, make the command conditional on the version from which
+ the package is being upgraded:
+ <example>
+ if [ upgrade != "$1" ] || dpkg --compare-versions "$2" lt 1.0-2; then
+ dpkg-divert --package smailwrapper --add --rename \
+ --divert /usr/sbin/smail.real /usr/sbin/smail
+ fi
+ </example> where <tt>1.0-2</tt> is the version at which the
+ diversion was first added to the package. Running the command
+ during abort-upgrade is pointless but harmless.
</p>
<p>
The postrm has to do the reverse:
<example>
- if [ remove = "$1" ]; then
+ if [ remove = "$1" -o abort-install = "$1" -o disappear = "$1" ]; then
+ dpkg-divert --package smailwrapper --remove --rename \
+ --divert /usr/sbin/smail.real /usr/sbin/smail
+ fi
+ </example> If the diversion was added at a particular version, the
+ postrm should also handle the failure case of upgrading from an
+ older version (unless the older version is so old that direct
+ upgrades are no longer supported):
+ <example>
+ if [ abort-upgrade = "$1" ] && dpkg --compare-versions "$2" lt 1.0-2; then
dpkg-divert --package smailwrapper --remove --rename \
--divert /usr/sbin/smail.real /usr/sbin/smail
fi
- </example>
+ </example> where <tt>1.02-2</tt> 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
+ postrm of the old package is run after unpacking so the removal of
+ the diversion will fail.
</p>
<p>