<url id="http://www.gnu.org/copyleft/gpl.html"
name="the GNU General Public Licence">. You can also
obtain it by writing to the Free Software Foundation, Inc.,
- 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+ 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.
</p>
</copyright>
</titlepag>
<p>
This manual is distributed via the Debian package
- <package><url name="debian-policy" id="http://packages.debian.org/debian-policy"></package>.
+ <package><url name="debian-policy"
+ id="http://packages.debian.org/debian-policy"></package>
+ (<httpsite>packages.debian.org</httpsite>
+ <httppath>/debian-policy</httppath>).
</p>
<p>
the Debian web mirrors at
<tt><url name="/doc/debian-policy/"
id="http://www.debian.org/doc/debian-policy/"></tt>.
+ (
+ <httpsite>www.debian.org</httpsite>
+ <httppath>/doc/debian-policy/</httppath>)
Also available from the same directory are several other
- formats: <file>policy.html.tar.gz</file>, <file>policy.pdf.gz</file>
- and <file>policy.ps.gz</file>.
+ formats: <file>policy.html.tar.gz</file>
+ (<httppath>/doc/debian-policy/policy.html.tar.gz</httppath>),
+ <file>policy.pdf.gz</file>
+ (<httppath>/doc/debian-policy/policy.pdf.gz</httppath>)
+ and <file>policy.ps.gz</file>
+ (<httppath>/doc/debian-policy/policy.ps.gz</httppath>).
</p>
<p>
The <package>debian-policy</package> package also includes the file
- <file>upgrading-checklist.txt</file> which indicates policy
+ <file>upgrading-checklist.txt.gz</file> which indicates policy
changes between versions of this document.
</p>
</sect>
is the Debian Developer's Reference. This document describes
procedures and resources for Debian developers, but it is
<em>not</em> normative; rather, it includes things that don't
- belong into the Policy, such as best practices for developers.
+ belong in the Policy, such as best practices for developers.
</p>
<p>
<p>
The Debian GNU/Linux system is maintained and distributed as a
collection of <em>packages</em>. Since there are so many of
- them (currently well over 6000), they are split into
+ them (currently well over 15000), they are split into
<em>sections</em> and given <em>priorities</em> to simplify
the handling of them.
</p>
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 sections
- based on their licenses and other restrictions.
+ restrictions. Thus, the archive is split into the distribution
+ areas or categories based on their licenses and other restrictions.
</p>
<p>
</p>
<p>
- The <em>main</em> and the <em>non-US/main</em> sections
- together form the <em>Debian GNU/Linux distribution</em>.
+ The <em>main</em> category forms the
+ <em>Debian GNU/Linux distribution</em>.
</p>
<p>
- Packages in the other sections 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 mailing lists). This Debian Policy Manual applies
- to these packages as well.
+ Packages in the other distribution 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
+ mailing lists). This Debian Policy Manual applies to these
+ packages as well.
</p>
<sect id="dfsg">
</sect>
<sect id="sections">
- <heading>Sections</heading>
+ <heading>Categories</heading>
<sect1 id="main">
- <heading>The main section</heading>
+ <heading>The main category</heading>
<p>
- Every package in <em>main</em> and <em>non-US/main</em>
- must comply with the DFSG (Debian Free Software
- Guidelines).
+ Every package in <em>main</em> must comply with the DFSG
+ (Debian Free Software Guidelines).
</p>
<p>
</list>
</p>
- <p>
- Similarly, the packages in <em>non-US/main</em>
- <list compact="compact">
- <item>
- must not require a package outside of <em>main</em>
- or <em>non-US/main</em> for compilation or
- execution,
- </item>
- <item>
- must not be so buggy that we refuse to support them,
- </item>
- <item>
- must meet all policy requirements presented in this
- manual.
- </item>
- </list>
- </p>
-
</sect1>
<sect1 id="contrib">
- <heading>The contrib section</heading>
+ <heading>The contrib category</heading>
<p>
- Every package in <em>contrib</em> and
- <em>non-US/contrib</em> must comply with the DFSG.
+ Every package in <em>contrib</em> must comply with the DFSG.
</p>
<p>
- In addition, the packages in <em>contrib</em> and
- <em>non-US/contrib</em>
+ In addition, the packages in <em>contrib</em>
<list compact="compact">
<item>
must not be so buggy that we refuse to support them,
</list>
</p>
- <p>
- Furthermore, packages in <em>contrib</em> must not require
- a package in a <em>non-US</em> section for compilation or
- execution.
- </p>
<p>
Examples of packages which would be included in
- <em>contrib</em> or <em>non-US/contrib</em> are:
+ <em>contrib</em> are:
<list compact="compact">
<item>
free packages which require <em>contrib</em>,
</sect1>
<sect1 id="non-free">
- <heading>The non-free section</heading>
+ <heading>The non-free category</heading>
<p>
- Packages must be placed in <em>non-free</em> or
- <em>non-US/non-free</em> if they are not compliant with
- the DFSG or are encumbered by patents or other legal
- issues that make their distribution problematic.
+ Packages must be placed in <em>non-free</em> if they are
+ not compliant with the DFSG or are encumbered by patents
+ or other legal issues that make their distribution
+ problematic.
</p>
<p>
- In addition, the packages in <em>non-free</em> and
- <em>non-US/non-free</em>
+ In addition, the packages in <em>non-free</em>
<list compact="compact">
<item>
must not be so buggy that we refuse to support them,
</p>
</sect1>
- <sect1 id="non-US">
- <heading>The non-US sections</heading>
-
- <p>
- Non-free programs with cryptographic program code need to
- be stored on the <em>non-us</em> server because of export
- restrictions of the U.S.
- </p>
-
- <p>
- Programs which use patented algorithms that have a
- restricted license also need to be stored on "non-us",
- since that is located in a country where it is not allowed
- to patent algorithms.
- </p>
-
- <p>
- A package depends on another package which is distributed
- via the non-us server has to be stored on the non-us
- server as well.
- </p>
- </sect1>
</sect>
<sect id="pkgcopyright">
</sect>
<sect id="subsections">
- <heading>Subsections</heading>
+ <heading>Sections</heading>
<p>
- The packages in the sections <em>main</em>,
+ The packages in the categories <em>main</em>,
<em>contrib</em> and <em>non-free</em> are grouped further
- into <em>subsections</em> to simplify handling.
+ into <em>sections</em> to simplify handling.
</p>
<p>
- The section and subsection 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 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:
<list compact="compact">
<item>
- <em>subsection</em> if the package is in the
- <em>main</em> section,
+ <em>section</em> if the package is in the
+ <em>main</em> category,
</item>
<item>
- <em>section/subsection</em> if the package is in
- the <em>contrib</em> or <em>non-free</em> section,
- and
- </item>
- <item>
- <tt>non-US</tt>, <tt>non-US/contrib</tt> or
- <tt>non-US/non-free</tt> if the package is in
- <em>non-US/main</em>, <em>non-US/contrib</em> or
- <em>non-US/non-free</em> respectively.
+ <em>segment/section</em> if the package is in
+ the <em>contrib</em> or <em>non-free</em>
+ distribution areas.
</item>
</list>
</p>
<p>
The Debian archive maintainers provide the authoritative
- list of subsections. At present, they are:
- <em>admin</em>, <em>base</em>, <em>comm</em>,
- <em>contrib</em>, <em>devel</em>, <em>doc</em>,
+ 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>non-US</em>, <em>non-free</em>, <em>oldlibs</em>,
- <em>otherosfs</em>, <em>perl</em>, <em>python</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>.
</p>
<p>
- The following <em>priority levels</em> are recognised by the
+ The following <em>priority levels</em> are recognized by the
Debian package management tools.
<taglist>
<tag><tt>required</tt></tag>
<item>
Packages which are necessary for the proper
- functioning of the system. You must not remove these
- packages or your system may become totally broken and
- you may not even be able to use <prgn>dpkg</prgn> to
- put things back. Systems with only the
- <tt>required</tt> packages are probably unusable, but
- they do have enough functionality to allow the
- sysadmin to boot and install more software.
+ functioning of the system (usually, this means that
+ dpkg functionality depends on these packages).
+ Removing a <tt>required</tt> package may cause your
+ system to become totally broken and you may not even
+ be able to use <prgn>dpkg</prgn> to put things back,
+ so only do so if you know what you are doing. Systems
+ with only the <tt>required</tt> packages are probably
+ unusable, but they do have enough functionality to
+ allow the sysadmin to boot and install more software.
</item>
<tag><tt>important</tt></tag>
<item>
This contains all packages that conflict with others
with required, important, standard or optional
priorities, or are only likely to be useful if you
- already know what they are or have specialised
+ already know what they are or have specialized
requirements.
</item>
</taglist>
<p>
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
+ they want to bother the upstream maintainer to change
+ the version numbers upstream, too.
</p>
<p>
The maintainer must be specified in the
<tt>Maintainer</tt> control field with their correct name
and a working email address. If one person maintains
- several packages, he/she should try to avoid having
+ several packages, they should try to avoid having
different forms of their name and email address in
the <tt>Maintainer</tt> fields of those packages.
</p>
If the maintainer of a package quits from the Debian
project, "Debian QA Group"
<email>packages@qa.debian.org</email> takes over the
- maintainership of the package until someone else
+ maintainer-ship of the package until someone else
volunteers for that task. These packages are called
<em>orphaned packages</em>.<footnote>
The detailed procedure for doing this gracefully can
Packages are not required to declare any dependencies they
have on other packages which are marked <tt>Essential</tt>
(see below), and should not do so unless they depend on a
- particular version of that package.
+ 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.
+ </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.
+ </p>
+ </footnote>
</p>
<p>
package names can be found in the <tt>debian-policy</tt> package.
It is also available from the Debian web mirrors at
<tt><url name="/doc/packaging-manuals/virtual-package-names-list.txt"
- id="http://www.debian.org/doc/packaging-manuals/virtual-package-names-list.txt"></tt>
- and from the Debian archive mirrors at
- <tt><url name="/doc/package-developer/virtual-package-names-list.txt"
- id="http://ftp.debian.org/debian/doc/package-developer/virtual-package-names-list.txt"></tt>.
+ id="http://www.debian.org/doc/packaging-manuals/virtual-package-names-list.txt"></tt>.
</p>
<p>
<p>
The <tt>base system</tt> is a minimum subset of the Debian
GNU/Linux system that is installed before everything else
- on a new system. Thus, only very few packages are allowed
- to go into the <tt>base</tt> section to keep the required
- disk usage very small.
+ on a new system. Only very few packages are allowed to form
+ part of the base system, in order to keep the required disk
+ usage very small.
</p>
<p>
- Most of these packages will have the priority value
- <tt>required</tt> or at least <tt>important</tt>, and many
- of them will be tagged <tt>essential</tt> (see below).
+ The base system consists of all those packages with priority
+ <tt>required</tt> or <tt>important</tt>. Many of them will
+ be tagged <tt>essential</tt> (see below).
</p>
</sect>
</p>
</sect>
- <sect>
- <heading>Tasks</heading>
-
- <p>
- The Debian install process allows the user to choose from
- a number of common tasks which a Debian system can be used to
- perform. Selecting a task with <prgn>tasksel</prgn> causes
- a set of packages that are useful in performing that task to be
- installed.
- </p>
-
- <p>
- This set of packages is all available packages which have the
- name of the selected task in the <tt>Task</tt> field of their
- control file. The format of this field is a list of tasks,
- separated by commas.
- </p>
-
- <p>
- You should not tag any packages as belonging to a task
- before this has been discussed on the
- <em>debian-devel</em> mailing list and a consensus about
- doing that has been reached.
- </p>
-
- <p>
- For third parties (and historical reasons), tasksel also
- supports constructing tasks based on <em>task
- packages</em>. These are packages whose names begin with
- <em>task-</em>. Task packages should not be included in the
- Debian archive.
- </p>
- </sect>
-
<sect id="maintscripts">
<heading>Maintainer Scripts</heading>
<p>
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 <prgn>dpkg</prgn> to stave off boredom on
the part of a user installing many packages. This means,
amongst other things, using the <tt>--quiet</tt> option on
<package>debian-policy</package> package.
It is also available from the Debian web mirrors at
<tt><url name="/doc/packaging-manuals/debconf_specification.html"
- id="http://www.debian.org/doc/packaging-manuals/debconf_specification.html"></tt>
- and from the Debian archive mirrors at
- <tt><url name="/doc/package-developer/debconf_specification.txt.gz"
- id="http://ftp.debian.org/debian/doc/package-developer/debconf_specification.txt.gz"></tt>.
+ id="http://www.debian.org/doc/packaging-manuals/debconf_specification.html"></tt>.
</p>
<p>
</footnote>.
The <prgn>config</prgn> script might be run before the
<prgn>preinst</prgn> script, and before the package is unpacked
- or any of its dependencies or pre-dependancies are satisfied.
+ or any of its dependencies or pre-dependencies are satisfied.
Therefore it must work using only the tools present in
<em>essential</em> packages.<footnote>
<package>Debconf</package> or another tool that
</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.
+ </p>
+
<p>
Packages should try to minimize the amount of prompting
they need to do, and they should ensure that the user
</p>
<p>
- If you need to edit a <prgn>Makefile</prgn> where
- GNU-style <prgn>configure</prgn> scripts are used, you
- should edit the <file>.in</file> files rather than editing the
+ If you need to edit a <prgn>Makefile</prgn> where GNU-style
+ <prgn>configure</prgn> scripts are used, you should edit the
+ <file>.in</file> files rather than editing the
<prgn>Makefile</prgn> directly. This allows the user to
reconfigure the package if necessary. You should
<em>not</em> configure the package and edit the generated
- <prgn>Makefile</prgn>! This makes it impossible for
- someone else to later reconfigure the package.
+ <prgn>Makefile</prgn>! This makes it impossible for someone
+ else to later reconfigure the package without losing the
+ changes you made.
</p>
</sect>
<p>
Changes in the Debian version of the package should be
briefly explained in the Debian changelog file
- <file>debian/changelog</file>. This includes modifications
+ <file>debian/changelog</file>.<footnote>
+ <p>
+ Mistakes in changelogs are usually best rectified by
+ making a new changelog entry rather than "rewriting
+ history" by editing old changelog entries.
+ </p>
+ </footnote>
+ This includes modifications
made in the Debian package compared to the upstream one
as well as other changes and updates to the package.
<footnote>
</p>
<p>
- Mistakes in changelogs are usually best rectified by making
- a new changelog entry rather than "rewriting history" by
- editing old changelog entries.
+
</p>
<p>
<tt><var>keyword</var>=<var>value</var></tt> settings in the
<prgn>dpkg</prgn> changelog format (though there is
currently only one useful <var>keyword</var>,
- <tt>urgency</tt>).<footnote>
- Recognised urgency values are <tt>low</tt>,
- <tt>medium</tt>, <tt>high</tt> and <tt>emergency</tt>.
- They have an effect on how quickly a package will be
- considered for inclusion into the <tt>testing</tt>
- distribution, and give an indication of the importance
- of any fixes included in this upload.
- </footnote>
+ <tt>urgency</tt>).
</p>
<p>
<p>
The <var>date</var> should be in RFC822 format<footnote>
- This is generated by the <prgn>822-date</prgn>
- program.
+ This is generated by <tt>date -R</tt>.
</footnote>; it should include the time zone specified
numerically, with the time zone name or abbreviation
optionally present as a comment in parentheses.
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
- 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 <prgn>dpkg</prgn> is.)
</footnote>
</p>
</sect1>
</sect>
-
+ <sect id="dpkgcopyright">
+ <heading>Copyright: <file>debian/copyright</file></heading>
+ <p>
+ Every package must be accompanied by a verbatim copy of
+ its copyright and distribution license in the file
+ <file>/usr/share/doc/<var>package</var>/copyright</file>
+ (see <ref id="copyrightfile"> for further details). Also see
+ <ref id="pkgcopyright"> for further considerations relayed
+ to copyrights for packages.
+ </p>
+ </sect>
<sect>
<heading>Error trapping in makefiles</heading>
possible is a good idea.
</p>
</item>
+
+ <tag><tt>patch</tt> (optional)</tag>
+ <item>
+ <p>
+ This target performs whatever additional actions are
+ required to make the source ready for editing (unpacking
+ additional upstream archives, applying patches, etc.).
+ It is recommended to be implemented for any package where
+ <tt>dpkg-source -x</tt> does not result in source ready
+ for additional modification. See
+ <ref id="readmesource">.
+ </p>
+ </item>
</taglist>
<p>
or system information; the GNU style variables should be
used for that.
</p>
+
+ <sect1 id="debianrules-options">
+ <heading><file>debian/rules</file> and
+ <tt>DEB_BUILD_OPTIONS</tt></heading>
+
+ <p>
+ Supporting the standardized environment variable
+ <tt>DEB_BUILD_OPTIONS</tt> is recommended. This variable can
+ contain several flags to change how a package is compiled and
+ built. Each flag must be in the form <var>flag</var> or
+ <var>flag</var>=<var>options</var>. If multiple flags are
+ given, they must be separated by whitespace.<footnote>
+ Some packages support any delimiter, but whitespace is the
+ easiest to parse inside a makefile and avoids ambiguity with
+ flag values that contain commas.
+ </footnote>
+ <var>flag</var> must start with a lowercase letter
+ (<tt>a-z</tt>) and consist only of lowercase letters,
+ numbers (<tt>0-9</tt>), and the characters
+ <tt>-</tt> and <tt>_</tt> (hyphen and underscore).
+ <var>options</var> must not contain whitespace. The same
+ tag should not be given multiple times with conflicting
+ values. Package maintainers may assume that
+ <tt>DEB_BUILD_OPTIONS</tt> will not contain conflicting tags.
+ </p>
+
+ <p>
+ The meaning of the following tags has been standardized:
+ <taglist>
+ <tag>noopt</tag>
+ <item>
+ The presence of this tag means that the package should
+ be compiled with a minimum of optimization. For C
+ programs, it is best to add <tt>-O0</tt> to
+ <tt>CFLAGS</tt> (although this is usually the default).
+ Some programs might fail to build or run at this level
+ of optimization; it may be necessary to use
+ <tt>-O1</tt>, for example.
+ </item>
+ <tag>nostrip</tag>
+ <item>
+ This tag means that the debugging symbols should not be
+ stripped from the binary during installation, so that
+ debugging information may be included in the package.
+ </item>
+ <tag>parallel=n</tag>
+ <item>
+ This tag means that the package should be built using up
+ to <tt>n</tt> parallel processes if the package build
+ system supports this.<footnote>
+ Packages built with <tt>make</tt> can often implement
+ this by passing the <tt>-j</tt><var>n</var> option to
+ <tt>make</tt>.
+ </footnote>
+ If the package build system does not support parallel
+ builds, this string must be ignored. If the package
+ build system only supports a lower level of concurrency
+ than <var>n</var>, the package should be built using as
+ many parallel processes as the package build system
+ supports. It is up to the package maintainer to decide
+ whether the package build times are long enough and the
+ package build system is robust enough to make supporting
+ parallel builds worthwhile.
+ </item>
+ </taglist>
+ </p>
+
+ <p>
+ Unknown flags must be ignored by <file>debian/rules</file>.
+ </p>
+
+ <p>
+ The following makefile snippet is an example of how one may
+ implement the build options; you will probably have to
+ massage this example in order to make it work for your
+ package.
+ <example compact="compact">
+CFLAGS = -Wall -g
+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 (,$(filter noopt,$(DEB_BUILD_OPTIONS)))
+ CFLAGS += -O0
+else
+ CFLAGS += -O2
+endif
+ifeq (,$(filter nostrip,$(DEB_BUILD_OPTIONS)))
+ INSTALL_PROGRAM += -s
+endif
+ifneq (,$(filter parallel=%,$(DEB_BUILD_OPTIONS)))
+ NUMJOBS = $(patsubst parallel=%,%,$(filter parallel=%,$(DEB_BUILD_OPTIONS)))
+ MAKEFLAGS += -j$(NUMJOBS)
+endif
+ </example>
+ </p>
+ </sect1>
</sect>
<!-- FIXME: section pkg-srcsubstvars is the same as substvars -->
format of <file>debian/substvars</file>.</p>
</sect>
+ <sect id="debianwatch">
+ <heading>Optional upstream source location: <file>debian/watch</file></heading>
+
+ <p>
+ This is an optional, recommended control file for the
+ <tt>uscan</tt> utility which defines how to automatically
+ scan ftp or http sites for newly available updates of the
+ package. This is used by <url id="
+ http://dehs.alioth.debian.org/"> and other Debian QA tools
+ to help with quality control and maintenance of the
+ distribution as a whole.
+ </p>
+
+ </sect>
+
<sect id="debianfiles">
<heading>Generated files list: <file>debian/files</file></heading>
the file to the list in <file>debian/files</file>.</p>
</sect>
+ <sect id="embeddedfiles">
+ <heading>Convenience copies of code</heading>
+
+ <p>
+ Some software packages include in their distribution convenience
+ copies of code from other software packages, generally so that
+ users compiling from source don't have to download multiple
+ packages. Debian packages should not make use of these
+ convenience copies unless the included package is explicitly
+ intended to be used in this way.<footnote>
+ For example, parts of the GNU build system work like this.
+ </footnote>
+ If the included code is already in the Debian archive in the
+ form of a library, the Debian packaging should ensure that
+ binary packages reference the libraries already in Debian and
+ the convenience copy is not used. If the included code is not
+ already in Debian, it should be packaged separately as a
+ prerequisite if possible.
+ <footnote>
+ Having multiple copies of the same code in Debian is
+ inefficient, often creates either static linking or shared
+ library conflicts, and, most importantly, increases the
+ difficulty of handling security vulnerabilities in the
+ duplicated code.
+ </footnote>
+ </p>
+ </sect>
+
+ <sect id="readmesource">
+ <heading>Source package handling:
+ <file>debian/README.source</file></heading>
+
+ <p>
+ If running <prgn>dpkg-source -x</prgn> on a source package
+ doesn't produce the source of the package, ready for editing,
+ and allow one to make changes and run
+ <prng>dpkg-buildpackage</prgn> to produce a modified package
+ without taking any additional steps, creating a
+ <file>debian/README.source</file> documentation file is
+ recommended. This file should explain how to do all of the
+ following:
+ <enumlist>
+ <item>Generate the fully patched source, in a form ready for
+ editing, that would be built to create Debian
+ packages. Doing this with a <tt>patch</tt> target in
+ <file>debian/rules</file> is recommended; see
+ <ref id="debianrules">.</item>
+ <item>Modify the source and save those modifications so that
+ they will be applied when building the package.</item>
+ <item>Remove source modifications that are currently being
+ applied when building the package.</item>
+ <item>Optionally, document what steps are necessary to
+ upgrade the Debian source package to a new upstream version,
+ if applicable.</item>
+ </enumlist>
+ This explanation should include specific commands and mention
+ any additional required Debian packages. It should not assume
+ familiarity with any specific Debian packaging system or patch
+ management tools.
+ </p>
+
+ <p>
+ This explanation may refer to a documentation file installed by
+ one of the package's build dependencies provided that the
+ referenced documentation clearly explains these tasks and is not
+ a general reference manual.
+ </p>
+
+ <p>
+ <file>debian/README.source</file> may also include any other
+ information that would be helpful to someone modifying the
+ source package. Even if the package doesn't fit the above
+ description, maintainers are encouraged to document in a
+ <file>debian/README.source</file> file any source package with a
+ particularly complex or unintuitive source layout or build
+ system (for example, a package that builds the same source
+ multiple times to generate different binary packages).
+ </p>
+ </sect>
</chapt>
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. It ends at
- the end of the line. 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:
+ the end of the (logical) line. 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:
<example compact="compact">
Package: libc6
</example>
</p>
<p>
- Some fields' values may span several lines; in this case
+ Many fields' values may span several lines; in this case
each continuation line must start with a space or a tab.
Any trailing spaces or tabs at the end of individual
- lines of a field value are ignored.
+ lines of a field value are ignored.
</p>
<p>
- Except where otherwise stated, only a single line of data is
- allowed and whitespace is not significant in a field body.
- Whitespace must not appear inside names (of packages,
- architectures, files or anything else) or version numbers,
- or between the characters of multi-character version
- relationships.
+ In fields where it is specified that lines may not wrap,
+ only a single line of data is allowed and whitespace is not
+ significant in a field body. Whitespace must not appear
+ inside names (of packages, architectures, files or anything
+ else) or version numbers, or between the characters of
+ multi-character version relationships.
</p>
<p>
<list compact="compact">
<item><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</item>
<item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
+ <item><qref id="f-Uploaders"><tt>Uploaders</tt></qref></item>
<item><qref id="f-Section"><tt>Section</tt></qref> (recommended)</item>
<item><qref id="f-Priority"><tt>Priority</tt></qref> (recommended)</item>
<item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
<item><qref id="f-Standards-Version"><tt>Standards-Version</tt></qref> (recommended)</item>
+ <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
</list>
</p>
<item><qref id="f-Essential"><tt>Essential</tt></qref></item>
<item><qref id="binarydeps"><tt>Depends</tt> et al</qref></item>
<item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
+ <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
</list>
</p>
generate control files for binary packages (see below), by
<prgn>dpkg-genchanges</prgn> to generate the
<tt>.changes</tt> file to accompany the upload, and by
- <prgn>dpkg-source</prgn> when it creates the <file>.dsc</file>
- source control file as part of a source archive.
+ <prgn>dpkg-source</prgn> when it creates the
+ <file>.dsc</file> source control file as part of a source
+ archive. Many fields are permitted to span multiple lines in
+ <file>debian/control</file> but not in any other control
+ file. These tools are responsible for removing the line
+ breaks from such fields when using fields from
+ <file>debian/control</file> to generate other control files.
</p>
<p>
<item><qref id="f-Installed-Size"><tt>Installed-Size</tt></qref></item>
<item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
<item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
+ <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
</list>
</p>
</sect>
syntax is described above, in <ref id="pkg-controlfields">.
<list compact="compact">
+ <item><qref id="f-Format"><tt>Format</tt></qref> (mandatory)</item>
<item><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</item>
<item><qref id="f-Version"><tt>Version</tt></qref> (mandatory)</item>
<item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
+ <item><qref id="f-Uploaders"><tt>Uploaders</tt></qref></item>
<item><qref id="f-Binary"><tt>Binary</tt></qref></item>
<item><qref id="f-Architecture"><tt>Architecture</tt></qref></item>
<item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
<item><qref id="f-Standards-Version"><tt>Standards-Version</tt></qref> (recommended)</item>
<item><qref id="f-Files"><tt>Files</tt></qref> (mandatory)</item>
+ <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
</list>
</p>
</p>
<p>
- In a main source control information, a <file>.changes</file>
- or a <file>.dsc</file> file this may contain only the name
- of the source package.
+ In <file>debian/control</file> or a <file>.dsc</file> file,
+ this field must contain only the name of the source package.
</p>
<p>
- In the control file of a binary package it may be followed
- by a version number in parentheses<footnote>
+ In a binary package control file or a <file>.changes</file>
+ file, the source package name may be followed by a version
+ number in parentheses<footnote>
It is customary to leave a space after the package name
if a version number is specified.
</footnote>.
</p>
</sect1>
+ <sect1 id="f-Uploaders">
+ <heading><tt>Uploaders</tt></heading>
+
+ <p>
+ List of the names and email addresses of co-maintainers of
+ the package, if any. If the package has other maintainers
+ beside the one named in the
+ <qref id="f-Maintainer">Maintainer field</qref>, their
+ names and email addresses should be listed here. The
+ format is the same as that of the Maintainer tag, and
+ multiple entries should be comma separated. Currently,
+ this field is restricted to a single line of data. This
+ is an optional field.
+ </p>
+ <p>
+ Any parser that interprets the Uploaders field in
+ <file>debian/control</file> must permit it to span multiple
+ lines. Line breaks in an Uploaders field that spans multiple
+ lines are not significant and the semantics of the field are
+ the same as if the line breaks had not been present.
+ </p>
+ </sect1>
+
<sect1 id="f-Changed-By">
<heading><tt>Changed-By</tt></heading>
It also gives the default for the same field in the binary
packages.
</p>
-
- <p>
- By default, <prgn>dpkg-gencontrol</prgn> does not include this
- field in the control file of a binary package - use the
- <tt>-is</tt> (or <tt>-isp</tt>) options to achieve this effect.
- </p>
</sect1>
<sect1 id="f-Priority">
It also gives the default for the same field in the binary
packages.
</p>
-
- <p>
- By default, <prgn>dpkg-gencontrol</prgn> does not include this
- field in the control file of a binary package - use the
- <tt>-ip</tt> (or <tt>-isp</tt>) options to achieve this effect.
- </p>
</sect1>
<sect1 id="f-Package">
<sect1>
<heading>Package interrelationship fields:
<tt>Depends</tt>, <tt>Pre-Depends</tt>,
- <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Conflicts</tt>,
- <tt>Provides</tt>, <tt>Replaces</tt>
+ <tt>Recommends</tt>, <tt>Suggests</tt>,
+ <tt>Breaks</tt>, <tt>Conflicts</tt>,
+ <tt>Provides</tt>, <tt>Replaces</tt>, <tt>Enhances</tt>
</heading>
<p>
Alphanumerics are <tt>A-Za-z0-9</tt> only.
</footnote>
and the characters <tt>.</tt> <tt>+</tt> <tt>-</tt>
- <tt>:</tt> (full stop, plus, hyphen, colon) and should
- start with a digit. If there is no
+ <tt>:</tt> <tt>~</tt> (full stop, plus, hyphen, colon,
+ tilde) and should start with a digit. If there is no
<var>debian_revision</var> then hyphens are not allowed;
if there is no <var>epoch</var> then colons are not
allowed.
This part of the version number specifies the version of
the Debian package based on the upstream version. It
may contain only alphanumerics and the characters
- <tt>+</tt> and <tt>.</tt> (plus and full stop) and is
- compared in the same way as the
+ <tt>+</tt> <tt>.</tt> <tt>~</tt> (plus, full stop,
+ tilde) and is compared in the same way as the
<var>upstream_version</var> is.
</p>
<var>upstream_version</var> may not contain a hyphen.
This format represents the case where a piece of
software was written specifically to be turned into a
- Debian package, and so there is only one "debianization"
+ Debian package, and so there is only one "debianisation"
of it and therefore no revision indication is required.
</p>
which may be empty) are compared lexically. If a difference
is found it is returned. The lexical comparison is a
comparison of ASCII values modified so that all the letters
- sort earlier than all the non-letters.
+ sort earlier than all the non-letters and so that a tilde
+ sorts before anything, even the end of a part. For example,
+ the following parts are in sorted order from earliest to
+ latest: <tt>~~</tt>, <tt>~~a</tt>, <tt>~</tt>, the empty part,
+ <tt>a</tt>.<footnote>
+ One common use of <tt>~</tt> is for upstream pre-releases.
+ For example, <tt>1.0~beta1~svn1245</tt> sorts earlier than
+ <tt>1.0~beta1</tt>, which sorts earlier than <tt>1.0</tt>.
+ </footnote>
</p>
<p>
<item>
Those starting with two or more spaces. These will be
displayed verbatim. If the display cannot be panned
- horizontally, the displaying program will linewrap them "hard"
+ horizontally, the displaying program will line wrap them "hard"
(i.e., without taking account of word breaks). If it can they
will be allowed to trail off to the right. None, one or two
initial spaces may be deleted, but the number of spaces
<p>
This is a description of how important it is to upgrade to
this version from previous ones. It consists of a single
- keyword usually taking one of the values <tt>low</tt>,
- <tt>medium</tt> or <tt>high</tt> (not case-sensitive)
- followed by an optional commentary (separated by a space)
- which is usually in parentheses. For example:
+ keyword taking one of the values <tt>low</tt>,
+ <tt>medium</tt>, <tt>high</tt>, <tt>emergency</tt>, or
+ <tt>critical</tt><footnote>
+ Other urgency values are supported with configuration
+ changes in the archive software but are not used in Debian.
+ The urgency affects how quickly a package will be considered
+ for inclusion into the <tt>testing</tt> distribution and
+ gives an indication of the importance of any fixes included
+ in the upload. <tt>Emergency</tt> and <tt>critical</tt> are
+ treated as synonymous.
+ </footnote> (not case-sensitive) followed by an optional
+ commentary (separated by a space) which is usually in
+ parentheses. For example:
<example>
Urgency: low (HIGH for users of diversions)
There should be nothing in this field before the first
newline; all the subsequent lines must be indented by at
least one space; blank lines must be represented by a line
- consiting only of a space and a full stop.
+ consisting only of a space and a full stop.
</p>
<p>
</p>
</sect1>
+ <sect1 id="f-Homepage">
+ <heading><tt>Homepage</tt></heading>
+
+ <p>
+ The URL of the web site for this package, preferably (when
+ applicable) the site from which the original source can be
+ obtained and any additional upstream documentation or
+ information may be found. The content of this field is a
+ simple URL without any surrounding characters such as
+ <tt><></tt>.
+ </p>
+ </sect1>
+
</sect>
<sect>
<p>
These scripts are the files <prgn>preinst</prgn>,
- <prgn>postinst</prgn>, <prgn>prerm</prgn> and <prgn>postrm</prgn> in the
- control area of the package. They must be proper executable
- files; if they are scripts (which is recommended), they must
- start with the usual <tt>#!</tt> convention. They should be
- readable and executable by anyone, and not world-writable.
+ <prgn>postinst</prgn>, <prgn>prerm</prgn> and
+ <prgn>postrm</prgn> in the control area of the package.
+ They must be proper executable files; if they are scripts
+ (which is recommended), they must start with the usual
+ <tt>#!</tt> convention. They should be readable and
+ executable by anyone, and must not be world-writable.
</p>
<p>
well.
</p>
+ <p>
+ Additionally, packages interacting with users using
+ <tt>debconf</tt> in the <prgn>postinst</prgn> script should
+ install a <prgn>config</prgn> script in the control area,
+ see <ref id="maintscriptprompt"> for details.
+ </p>
+
<p>
When a package is upgraded a combination of the scripts from
the old and new packages is called during the upgrade
<prgn>start-stop-daemon</prgn>, <prgn>install-info</prgn>,
and <prgn>update-rc.d</prgn> can be found via the
<tt>PATH</tt> environment variable. Those programs, and any
- other program that one would expect to be on the
+ other program that one would expect to be in the
<tt>PATH</tt>, should thus be invoked without an absolute
pathname. Maintainer scripts should also not reset the
<tt>PATH</tt>, though they might choose to modify it by
</sect>
<sect id="idempotency">
- <heading>Maintainer scripts Idempotency</heading>
+ <heading>Maintainer scripts idempotency</heading>
<p>
It is necessary for the error recovery procedures that the
<p>
The maintainer scripts are guaranteed to run with a
controlling terminal and can interact with the user.
- If they need to prompt for passwords, do full-screen
- interaction or something similar you should do these
- things to and from <file>/dev/tty</file>, since
- <prgn>dpkg</prgn> will at some point redirect scripts'
- standard input and output so that it can log the
- installation process. Likewise, because these scripts
- may be executed with standard output redirected into a
- pipe for logging purposes, Perl scripts should set
- unbuffered output by setting <tt>$|=1</tt> so that the
- output is printed immediately rather than being
+ Because these scripts may be executed with standard output
+ redirected into a pipe for logging purposes, Perl scripts
+ should set unbuffered output by setting <tt>$|=1</tt> so
+ that the output is printed immediately rather than being
buffered.
</p>
+ </sect>
+ <sect id="exitstatus">
+ <heading>Exit status</heading>
<p>
- Each script should return a zero exit status for
- success, or a nonzero one for failure.
+ Each script must return a zero exit status for
+ success, or a nonzero one for failure, since the package
+ management system looks for the exit status of these scripts
+ and determines what action to take next based on that datum.
</p>
</sect>
<tt>in-favour</tt> <var>package</var>
<var>new-version</var>
</item>
+ <item>
+ <var>postinst</var> <tt>abort-remove</tt>
+ </item>
<item>
<var>deconfigured's-postinst</var>
<tt>abort-deconfigure</tt> <tt>in-favour</tt>
<var>failed-install-package</var> <var>version</var>
- <tt>removing</tt> <var>conflicting-package</var>
- <var>version</var>
+ [<tt>removing</tt> <var>conflicting-package</var>
+ <var>version</var>]
</item>
</list>
<item>
<var>deconfigured's-prerm</var> <tt>deconfigure</tt>
<tt>in-favour</tt> <var>package-being-installed</var>
- <var>version</var> <tt>removing</tt>
+ <var>version</var> [<tt>removing</tt>
<var>conflicting-package</var>
- <var>version</var>
+ <var>version</var>]
</item>
</list>
<example compact="compact">
<var>new-prerm</var> failed-upgrade <var>old-version</var>
</example>
- Error unwind, for both the above cases:
+ If this works, the upgrade continues. If this
+ does not work, the error unwind:
<example compact="compact">
<var>old-postinst</var> abort-upgrade <var>new-version</var>
</example>
+ If this works, then the old-version is
+ "Installed", if not, the old version is in a
+ "Failed-Config" state.
</item>
</enumlist>
</item>
<item>
- If a "conflicting" package is being removed at the same time:
+ If a "conflicting" package is being removed at the same time,
+ or if any package will be broken (due to <tt>Breaks</tt>):
<enumlist>
<item>
- If any packages depended on that conflicting
- package and <tt>--auto-deconfigure</tt> is
+ If <tt>--auto-deconfigure</tt> is
+ specified, call, for each package to be deconfigured
+ due to <tt>Breaks</tt>:
+ <example compact="compact">
+<var>deconfigured's-prerm</var> deconfigure \
+ in-favour <var>package-being-installed</var> <var>version</var>
+ </example>
+ Error unwind:
+ <example compact="compact">
+<var>deconfigured's-postinst</var> abort-deconfigure \
+ in-favour <var>package-being-installed-but-failed</var> <var>version</var>
+ </example>
+ The deconfigured packages are marked as
+ requiring configuration, so that if
+ <tt>--install</tt> is used they will be
+ configured again if possible.
+ </item>
+ <item>
+ If any packages depended on a conflicting
+ package being removed and <tt>--auto-deconfigure</tt> is
specified, call, for each such package:
<example compact="compact">
<var>deconfigured's-prerm</var> deconfigure \
configured again if possible.
</item>
<item>
- To prepare for removal of the conflicting package, call:
+ To prepare for removal of each conflicting package, call:
<example compact="compact">
<var>conflictor's-prerm</var> remove \
in-favour <var>package</var> <var>new-version</var>
<example compact="compact">
<var>new-preinst</var> upgrade <var>old-version</var>
</example>
+ If this fails, we call:
+ <example>
+<var>new-postrm</var> abort-upgrade <var>old-version</var>
+ </example>
+ <enumlist>
+ <item>
+ <p>
+ If that works, then
+ <example>
+<var>old-postinst</var> abort-upgrade <var>new-version</var>
+ </example>
+ is called. If this works, then the old version
+ is in an "Installed" state, or else it is left
+ in an "Unpacked" state.
+ </p>
+ </item>
+ <item>
+ <p>
+ If it fails, then the old version is left
+ in an "Half-Installed" state.
+ </p>
+ </item>
+ </enumlist>
+
</item>
<item>
Otherwise, if the package had some configuration
<example compact="compact">
<var>new-preinst</var> install <var>old-version</var>
</example>
+ Error unwind:
+ <example>
+<var>new-postrm</var> abort-install <var>old-version</var>
+ </example>
+ If this fails, the package is left in a
+ "Half-Installed" state, which requires a
+ reinstall. If it works, the packages is left in
+ a "Config Files" state.
</item>
<item>
Otherwise (i.e., the package was completely purged):
<example compact="compact">
<var>new-preinst</var> install
- </example>
- Error unwind actions, respectively:
- <example compact="compact">
-<var>new-postrm</var> abort-upgrade <var>old-version</var>
-<var>new-postrm</var> abort-install <var>old-version</var>
+ </example>
+ Error unwind:
+ <example compact="compact">
<var>new-postrm</var> abort-install
- </example>
+ </example>
+ If the error-unwind fails, the package is in a
+ "Half Installed" phase, and requires a
+ reinstall. If the error unwind works, the
+ package is in a not installed state.
</item>
- </enumlist>
+ </enumlist>
</item>
<item>
<example compact="compact">
<var>new-postrm</var> failed-upgrade <var>old-version</var>
</example>
- Error unwind, for both cases:
+ If this works, installation continues. If not,
+ Error unwind:
<example compact="compact">
<var>old-preinst</var> abort-upgrade <var>new-version</var>
</example>
- </item>
+ If this fails, the old version is left in an
+ "Half Installed" state. If it works, dpkg now
+ calls:
+ <example compact="compact">
+<var>new-postrm</var> abort-upgrade <var>old-version</var>
+ </example>
+ If this fails, the old version is left in an
+ "Half Installed" state. If it works, dpkg now
+ calls:
+ <example compact="compact">
+<var>old-postinst</var> abort-upgrade <var>new-version</var>
+ </example>
+ If this fails, the old version is in an
+ "Unpacked" state.
+ </item>
</enumlist>
</p>
<p>
No attempt is made to unwind after errors during
- configuration.
+ configuration. If the configuration fails, the package is in
+ a "Failed Config" state, and an error message is generated.
</p>
<p>
<p>
<enumlist>
<item>
+ <p>
<example compact="compact">
<var>prerm</var> remove
</example>
+ </p>
+ <p>
+ If prerm fails during replacement due to conflict
+ <example>
+<var>conflictor's-postinst</var> abort-remove \
+ in-favour <var>package</var> <var>new-version</var>
+ </example>
+ Or else we call:
+ <example>
+<var>postinst</var> abort-remove
+ </example>
+ </p>
+ <p>
+ If this fails, the package is in a "Failed-Config"
+ state, or else it remains "Installed".
+ </p>
</item>
<item>
The package's files are removed (except <tt>conffile</tt>s).
<example compact="compact">
<var>postrm</var> remove
</example>
+
+ <p>
+ If it fails, there's no error unwind, and the package is in
+ an "Half-Installed" state.
+ </p>
</item>
<item>
<p>
are removed.
</item>
<item>
+ <p>
<example compact="compact">
<var>postrm</var> purge
</example>
+ </p>
+ <p>
+ If this fails, the package remains in a "Config-Files"
+ state.
+ </p>
</item>
<item>
The package's file list is removed.
</item>
</enumlist>
- If there are problems during this process, we call
- <example compact="compact">postinst
- abort-remove</example>. No other attempt is made to unwind
- after errors during removal.
</p>
</sect>
</chapt>
Whitespace may appear at any point in the version
specification subject to the rules in <ref
id="controlsyntax">, and must appear where it's necessary to
- disambiguate; it is not otherwise significant. For
+ disambiguate; it is not otherwise significant. All of the
+ relationship fields may span multiple lines. For
consistency and in case of future changes to
<prgn>dpkg</prgn> it is recommended that a single space be
used after a version relationship and before a version
number; it is also conventional to put a single space after
each comma, on either side of each vertical bar, and before
- each open parenthesis.
+ each open parenthesis. When wrapping a relationship field, it
+ is conventional to do so after a comma and before the space
+ following that comma.
</p>
<p>
list of Debian architecture names 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 and others not.) If the current Debian
+ exclamation marks while others aren't.) If the current Debian
host architecture is not in this list and there are no
exclamation marks in the list, or it is in the list with a
prepended exclamation mark, the package name and the
<p>
This is done using the <tt>Depends</tt>, <tt>Pre-Depends</tt>,
- <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt> and
- <tt>Conflicts</tt> control file fields.
+ <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
+ <tt>Breaks</tt> and <tt>Conflicts</tt> control file fields.
</p>
<p>
- These six fields are used to declare a dependency
+ These seven fields are used to declare a dependency
relationship by one package on another. Except for
- <tt>Enhances</tt>, they appear in the depending (binary)
- package's control file. (<tt>Enhances</tt> appears in the
- recommending package's control file.)
+ <tt>Enhances</tt> and <tt>Breaks</tt>, they appear in the
+ depending (binary) package's control file.
+ (<tt>Enhances</tt> appears in the recommending package's
+ control file, and <tt>Breaks</tt> appears in the version of
+ depended-on package which causes the named package to
+ break).
</p>
<p>
in detail below. (The other three dependency fields,
<tt>Recommends</tt>, <tt>Suggests</tt> and
<tt>Enhances</tt>, are only used by the various front-ends
- to <prgn>dpkg</prgn> such as <prgn>dselect</prgn>.)
+ to <prgn>dpkg</prgn> such as <prgn>apt-get</prgn>,
+ <prgn>aptitude</prgn>, and <prgn>dselect</prgn>.)
</p>
<p>
dependencies satisfied.
</p>
+ <p>
+ In case of circular dependencies, since installation or
+ removal order honoring the dependency order can't be
+ established, dependency loops are broken at some point
+ (based on rules below), and some packages may not be able to
+ rely on their dependencies being present when being
+ installed or removed, depending on which side of the break
+ of the circular dependency loop they happen to be on. If one
+ of the packages in the loop has no postinst script, then the
+ cycle will be broken at that package, so as to ensure that
+ all postinst scripts run with the dependencies properly
+ configured if this is possible. Otherwise the breaking point
+ is arbitrary.
+ </p>
+
<p>
The <tt>Depends</tt> field thus allows package maintainers
to impose an order in which packages should be configured.
</p>
</sect>
+ <sect id="breaks">
+ <heading>Packages which break other packages - <tt>Breaks</tt></heading>
+
+ <p>
+ Using <tt>Breaks</tt> may cause problems for upgrades from older
+ versions of Debian and should not be used until the stable
+ release of Debian supports <tt>Breaks</tt>.
+ </p>
+
+ <p>
+ When one binary package declares that it breaks another,
+ <prgn>dpkg</prgn> will refuse to allow the package which
+ declares <tt>Breaks</tt> be installed unless the broken
+ package is deconfigured first, and it will refuse to
+ allow the broken package to be reconfigured.
+ </p>
+
+ <p>
+ A package will not be regarded as causing breakage merely
+ because its configuration files are still installed; it must
+ be at least half-installed.
+ </p>
+
+ <p>
+ A special exception is made for packages which declare that
+ they break their own package name or a virtual package which
+ they provide (see below): this does not count as a real
+ breakage.
+ </p>
+
+ <p>
+ Normally a <tt>Breaks</tt> entry will have an "earlier than"
+ version clause; such a <tt>Breaks</tt> is introduced in the
+ version of an (implicit or explicit) dependency which
+ violates an assumption or reveals a bug in earlier versions
+ of the broken package. This use of <tt>Breaks</tt> will
+ inform higher-level package management tools that broken
+ package must be upgraded before the new one.
+ </p>
+
+ <p>
+ If the breaking package also overwrites some files from the
+ older package, it should use <tt>Replaces</tt> (not
+ <tt>Conflicts</tt>) to ensure this goes smoothly.
+ </p>
+ </sect>
+
<sect id="conflicts">
<heading>Conflicting binary packages - <tt>Conflicts</tt></heading>
"earlier than" version clause. This would prevent
<prgn>dpkg</prgn> from upgrading or installing the package
which declared such a conflict until the upgrade or removal
- of the conflicted-with package had been completed.
+ of the conflicted-with package had been completed. Instead,
+ <tt>Breaks</tt> may be used (once <tt>Breaks</tt> is supported
+ by the stable release of Debian).
</p>
</sect>
As well as the names of actual ("concrete") packages, the
package relationship fields <tt>Depends</tt>,
<tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
- <tt>Pre-Depends</tt>, <tt>Conflicts</tt>,
+ <tt>Pre-Depends</tt>, <tt>Breaks</tt>, <tt>Conflicts</tt>,
<tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
<tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>
may mention "virtual packages".
<example compact="compact">
Package: foo
Depends: bar
- </example>
- and someone else releases an enhanced version of the
- <tt>bar</tt> package (for example, a non-US variant), they
- can say:
+ </example> and someone else releases an enhanced version of
+ the <tt>bar</tt> package they can say:
<example compact="compact">
Package: bar-plus
Provides: bar
</p>
<p>
- If a dependency or a conflict has a version number attached
+ If a relationship field has a version number attached
then only real packages will be considered to see whether
the relationship is satisfied (or the prohibition violated,
- for a conflict) - it is assumed that a real package which
- provides the virtual package is not of the "right" version.
- So, a <tt>Provides</tt> field may not contain version
- numbers, and the version number of the concrete package
- which provides a particular virtual package will not be
- looked at when considering a dependency on or conflict with
- the virtual package name.
+ for a conflict or breakage) - it is assumed that a real
+ package which provides the virtual package is not of the
+ "right" version. So, a <tt>Provides</tt> field may not
+ contain version numbers, and the version number of the
+ concrete package which provides a particular virtual package
+ will not be looked at when considering a dependency on or
+ conflict with the virtual package name.
</p>
<p>
you need both.
</p>
<p>
- There is no Build-Depends-Arch; the autobuilders will
- only need the Build-Depends if they know how to build
- only build-arch and binary-arch. Anyone building the
- build-indep/binary-indep targets is basically assumed to
- be building the whole package and so installs all build
- dependencies.
+ There is no Build-Depends-Arch; this role is essentially
+ met with Build-Depends. Anyone building the
+ <tt>build-indep</tt> and binary-indep<tt></tt> targets
+ is basically assumed to be building the whole package
+ anyway and so installs all build dependencies. The
+ autobuilders use <tt>dpkg-buildpackage -B</tt>, which
+ calls <tt>build</tt> (not <tt>build-arch</tt>, since it
+ does not yet know how to check for its existence) and
+ <tt>binary-arch</tt>.
</p>
<p>
The purpose of the original split, I recall, was so that
<heading>Run-time shared libraries</heading>
<p>
- The run-time shared library needs to be placed in a package called
- <package><var>libraryname</var><var>soversion</var></package>, where
- <file><var>soversion</var></file> is the version number in the
- soname of the shared library<footnote>
+ The run-time shared library needs to be placed in a package
+ whose name changes whenever the shared object version
+ changes.<footnote>
+ <p>
+ Since it is common place to install several versions of a
+ package that just provides shared libraries, it is a
+ good idea that the library package should not
+ contain any extraneous non-versioned files, unless they
+ happen to be in versioned directories.</p>
+ </footnote>
+ The most common mechanism is to place it in a package
+ called
+ <package><var>libraryname</var><var>soversion</var></package>,
+ where <file><var>soversion</var></file> is the version number
+ in the soname of the shared library<footnote>
The soname is the shared object name: it's the thing
that has to match exactly between building an executable
and running it for the dynamic linker to be able run the
instead.
</p>
+ <p>
+ If your package includes run-time support programs that
+ do not need to be invoked manually by users, but are
+ nevertheless required for the package to function, then it
+ is recommended that these programs are placed
+ (if they are binary) in a subdirectory of
+ <file>/usr/lib</file>, preferably under
+ <file>/usr/lib/</file><var>package-name</var>.
+ If the program is architecture independent, the
+ recommendation is for it to be placed in a subdirectory of
+ <file>/usr/share</file> instead, preferably under
+ <file>/usr/share/</file><var>package-name</var>.
+ </p>
+
+
<p>
If you have several shared libraries built from the same
source tree you may lump them all together into a single
listed in <file>/etc/ld.so.conf</file><footnote>
These are currently
<list compact="compact">
- <item>/usr/X11R6/lib/Xaw3d</item>
<item>/usr/local/lib</item>
<item>/usr/lib/libc5-compat</item>
<item>/lib/libc5-compat</item>
- <item>/usr/X11R6/lib</item>
</list>
</footnote>
must use <prgn>ldconfig</prgn> to update the shared library
</p>
<p>
- The package must call <prgn>ldconfig</prgn> in the
- <prgn>postinst</prgn> script if the first argument is
- <tt>configure</tt>; the <prgn>postinst</prgn> script may
- optionally invoke <prgn>ldconfig</prgn> at other times. The
- package should call <prgn>ldconfig</prgn> in the
- <prgn>postrm</prgn> script if the first argument is
- <tt>remove</tt>. The maintainer scripts must not invoke
- <prgn>ldconfig</prgn> under any circumstances other than those
- described in this paragraph.<footnote>
+ The package maintainer scripts must only call
+ <prgn>ldconfig</prgn> under these circumstances:
+ <list compact="compact">
+ <item>When the <prgn>postinst</prgn> script is run with a
+ first argument of <tt>configure</tt>, the script must call
+ <prgn>ldconfig</prgn>, and may optionally invoke
+ <prgn>ldconfig</prgn> at other times.
+ </item>
+ <item>When the <prgn>postrm</prgn> script is run with a
+ first argument of <tt>remove</tt>, the script should call
+ <prgn>ldconfig</prgn>.
+ </item>
+ </list>
+ <footnote>
<p>
During install or upgrade, the preinst is called before
the new files are installed, so calling "ldconfig" is
<p>
postrm, on the other hand, is called with the "remove"
- argument just after the files are removed, so this is the
- proper time to call "ldconfig" to notify the system of the
- fact shared libraries from the package are removed.
- The postrm can be called at several other times. At the
- time of "postrm purge", "postrm abort-install", or "postrm
- abort-upgrade", calling "ldconfig" is useless because the
- shared lib files are not on-disk. However, when "postrm"
- is invoked with arguments "upgrade", "failed-upgrade", or
- "disappear", a shared lib may exist on-disk under a
- temporary filename.
+ argument just after the files are removed, so this is
+ the proper time to call "ldconfig" to notify the system
+ of the fact that the shared libraries from the package
+ are removed. The postrm can be called at several other
+ times. At the time of "postrm purge", "postrm
+ abort-install", or "postrm abort-upgrade", calling
+ "ldconfig" is useless because the shared lib files are
+ not on-disk. However, when "postrm" is invoked with
+ arguments "upgrade", "failed-upgrade", or "disappear", a
+ shared lib may exist on-disk under a temporary filename.
</p>
</footnote>
</p>
Typically the development version should have an exact
version dependency on the runtime library, to make sure that
compilation and linking happens correctly. The
- <tt>${Source-Version}</tt> substitution variable can be
+ <tt>${binary:Version}</tt> substitution variable can be
useful for this purpose.
+ <footnote>
+ Previously, <tt>${Source-Version}</tt> was used, but its name
+ was confusing and it has been deprecated since dpkg 1.13.19.
+ </footnote>
</p>
</sect>
This command puts the dependency information into the
<file>debian/substvars</file> file, which is then used by
<prgn>dpkg-gencontrol</prgn>. You will need to place a
- <tt>${shlib:Depends}</tt> variable in the <tt>Depends</tt>
+ <tt>${shlibs:Depends}</tt> variable in the <tt>Depends</tt>
field in the control file for this to work.
</p>
utilities to specify a different <file>substvars</file> file.
</p>
+ <p>
+ If you are creating a udeb for use in the Debian Installer, you
+ will need to specify that <prgn>dpkg-shlibdeps</prgn> should use
+ the dependency line of type <tt>udeb</tt> by adding
+ <tt>-tudeb</tt> as option<footnote>
+ <prgn>dh_shlibdeps</prgn> from the <tt>debhelper</tt> suite
+ will automatically add this option if it knows it is
+ processing a udeb.
+ </footnote>. If there is no dependency line of type <tt>udeb</tt>
+ in the <file>shlibs</file> file, <prgn>dpkg-shlibdeps</prgn> will
+ fall back to the regular dependency line.
+ </p>
+
<p>
For more details on dpkg-shlibdeps, please see
<ref id="pkg-dpkg-shlibdeps"> and
beginning with <tt>#</tt> are considered to be comments and
are ignored. Each line is of the form:
<example compact="compact">
-<var>library-name</var> <var>soname-version-number</var> <var>dependencies ...</var>
+[<var>type</var>: ]<var>library-name</var> <var>soname-version</var> <var>dependencies ...</var>
</example>
</p>
installs the shared library <file>/usr/lib/libz.so.1.1.3</file>.
</p>
+ <p>
+ <var>type</var> is an optional element that indicates the type
+ of package for which the line is valid. The only type currently
+ in use is <tt>udeb</tt>. The colon and space after the type are
+ required.
+ </p>
+
<p>
<var>library-name</var> is the name of the shared library,
in this case <tt>libz</tt>. (This must match the name part
</p>
<p>
- <var>soname-version-number</var> is the version part of the
- soname of the library. The soname is the thing that must
- exactly match for the library to be recognized by the
- dynamic linker, and is usually of the form
+ <var>soname-version</var> is the version part of the soname of
+ the library. The soname is the thing that must exactly match
+ for the library to be recognized by the dynamic linker, and is
+ usually of the form
<tt><var>name</var>.so.<var>major-version</var></tt>, in our
example, <tt>libz.so.1</tt>.<footnote>
This can be determined using the command
the dynamic linker about using older shared libraries with
newer binaries.
</p>
+
+ <p>
+ As zlib1g also provides a udeb containing the shared library,
+ there would also be a second line:
+ <example compact="compact">
+udeb: libz 1 zlib1g-udeb (>= 1:1.1.3)
+ </example>
+ </p>
</sect1>
<sect1>
<heading>Providing a <file>shlibs</file> file</heading>
<p>
- If your package provides a shared library, you should create
+ If your package provides a shared library, you need to create
a <file>shlibs</file> file following the format described above.
It is usual to call this file <file>debian/shlibs</file> (but if
you have multiple binary packages, you might want to call it
<file>debian/rules</file> without using a <file>debian/shlibs</file>
file at all,<footnote>
This is what <prgn>dh_makeshlibs</prgn> in the
- <tt>debhelper</tt> suite does.
+ <tt>debhelper</tt> suite does. If your package also has a udeb
+ that provides a shared library, <prgn>dh_makeshlibs</prgn> can
+ automatically generate the <tt>udeb:</tt> lines if you specify
+ the name of the udeb with the <tt>--add-udeb</tt> option.
</footnote>
since the <file>debian/shlibs</file> file itself is ignored by
<prgn>dpkg-shlibdeps</prgn>.
<chapt id="opersys"><heading>The Operating System</heading>
<sect>
- <heading>Filesystem hierarchy</heading>
+ <heading>File system hierarchy</heading>
<sect1 id="fhs">
- <heading>Filesystem Structure</heading>
+ <heading>File system Structure</heading>
<p>
The location of all installed files and directories must
- comply with the Filesystem Hierarchy Standard (FHS),
- version 2.1, except where doing so would violate other
- terms of Debian Policy. The version of this document
- referred here can be found in the <tt>debian-policy</tt>
- package or on
- <url id="http://www.debian.org/doc/packaging-manuals/fhs/"
+ comply with the File system 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:
+
+ <enumlist>
+ <item>
+ <p>
+ Legacy XFree86 servers are permitted to retain the
+ configuration file location
+ <file>/etc/X11/XF86Config-4</file>.
+ </p>
+ </item>
+ <item>
+ <p>
+ The optional rules related to user specific
+ configuration files for applications are stored in
+ the user's home directory are relaxed. It is
+ recommended that such files start with the
+ '<tt>.</tt>' character (a "dot file"), and if an
+ application needs to create more than one dot file
+ then the preferred placement is in a subdirectory
+ with a name starting with a '.' character, (a "dot
+ directory"). In this case it is recommended the
+ configuration files not start with the '.'
+ character.
+ </p>
+ </item>
+ <item>
+ <p>
+ The requirement for amd64 to use <file>/lib64</file>
+ for 64 bit binaries is removed.
+ </p>
+ </item>
+ <item>
+ <p>
+ The requirement that
+ <file>/usr/local/share/man</file> be "synonymous"
+ with <file>/usr/local/man</file> is relaxed to a
+ recommendation</p>
+ </item>
+ <item>
+ <p>
+ The requirement that windowmanagers with a single
+ configuration file call it <file>system.*wmrc</file>
+ is removed, as is the restriction that the window
+ manager subdirectory be named identically to the
+ window manager name itself.
+ </p>
+ </item>
+ <item>
+ <p>
+ The requirement that boot manager configuration
+ files live in <file>/etc</file>, or at least are
+ symlinked there, is relaxed to a recommendation.
+ </p>
+ </item>
+ </enumlist>
+
+ </p>
+ <p>
+ The version of this document referred here can be
+ found in the <tt>debian-policy</tt> package or on <url
+ id="http://www.debian.org/doc/packaging-manuals/fhs/"
name="FHS (Debian copy)"> alongside this manual (or, if
you have the <package>debian-policy</package> installed,
you can try <url
<p>
However, the package may create empty directories below
<file>/usr/local</file> so that the system administrator knows
- where to place site-specific files. These directories
+ where to place site-specific files. These are not
+ directories <em>in</em> <file>/usr/local</file>, but are
+ children of directories in <file>/usr/local</file>. These
+ directories (<file>/usr/local/*/dir/</file>)
should be removed on package removal if they are
empty.
</p>
of simplicity, this document describes only the symbolic
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
+ manipulation of the various runlevel behaviors by
maintainer scripts must be performed using
<prgn>update-rc.d</prgn> as described below and not by
manually installing or removing symlinks. For information
</p>
<p>
- Also, if the script name ends <tt>.sh</tt>, the script
- will be sourced in runlevel <tt>S</tt> rather that being
+ 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>
</p>
<p>
- The <file>init.d</file> scripts should ensure that they will
+ The <file>init.d</file> scripts must ensure that they will
behave sensibly if invoked with <tt>start</tt> when the
service is already running, or with <tt>stop</tt> when it
isn't, and that they don't kill unfortunately-named user
the scripts to the local system, e.g., to disable a
service without de-installing the package, or to specify
some special command line options when starting a service,
- while making sure her changes aren't lost during the next
+ while making sure their changes aren't lost during the next
package upgrade.
</p>
<p>
Often there are some variables in the <file>init.d</file>
- scripts whose values control the behaviour of the scripts,
+ scripts whose values control the behavior of the scripts,
and which a system administrator is likely to want to
change. As the scripts themselves are frequently
<tt>conffile</tt>s, modifying them requires that the
<file>/etc/default</file>, which typically will have the same
base name as the <file>init.d</file> script. This extra file
should be sourced by the script when the script runs. It
- must contain only variable settings and comments in POSIX
+ must contain only variable settings and comments in SUSv3
<prgn>sh</prgn> format. It may either be a
<tt>conffile</tt> or a configuration file maintained by
the package maintainer scripts. See <ref id="config-files">
<p>
For more information about using <tt>update-rc.d</tt>,
- please consult its manpage <manref name="update-rc.d"
+ please consult its man page <manref name="update-rc.d"
section="8">.
</p>
</sect2>
</p>
<p>
- The use of <prgn>invoke-rc.d</prgn> to invoke the
- <file>/etc/init.d/*</file> initscripts is strongly
- recommended<footnote>
- In the future, the use of invoke-rc.d to invoke
- initscripts shall be made mandatory. Maintainers are
- advised to switch to invoke-rc.d as soon as
- possible.
- </footnote>, instead of calling them directly.
+ The package maintainer scripts must use
+ <prgn>invoke-rc.d</prgn> to invoke the
+ <file>/etc/init.d/*</file> initscripts, instead of
+ calling them directly.
</p>
<p>
<action></example> in their <prgn>postinst</prgn>
and <prgn>prerm</prgn> scripts to:
<example compact="compact">
- if command -v invoke-rc.d >/dev/null 2>&1; then
+ if which invoke-rc.d >/dev/null 2>&1; then
invoke-rc.d <var>package</var> <action>
else
/etc/init.d/<var>package</var> <action>
<p>
For more information about using
- <prgn>invoke-rc.d</prgn>, please consult its manpage
+ <prgn>invoke-rc.d</prgn>, please consult its man page
<manref name="invoke-rc.d" section="8">.
</p>
</sect2>
<heading>Example</heading>
<p>
- The <prgn>bind</prgn> DNS (nameserver) package wants to
- make sure that the nameserver is running in multiuser
- runlevels, and is properly shut down with the system. It
- puts a script in <file>/etc/init.d</file>, naming the script
- appropriately <tt>bind</tt>. As you can see, the script
- interprets the argument <tt>reload</tt> to send the
- nameserver a <tt>HUP</tt> signal (causing it to reload its
- configuration); this way the system administrator can say
- <tt>/etc/init.d/bind reload</tt> to reload the name
- server. The script has one configurable value, which can
- be used to pass parameters to the named program at
- startup; this value is read from
- <file>/etc/default/bind</file> (see below).
- </p>
-
- <p>
- <example compact="compact">
-#!/bin/sh
-#
-# Original version by Robert Leslie
-# <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 \
- -- $PARAMS
- echo "."
- ;;
-stop)
- echo -n "Stopping domain name service: named"
- start-stop-daemon --stop --quiet \
- --pidfile /var/run/named.pid --exec /usr/sbin/named
- echo "."
- ;;
-restart)
- echo -n "Restarting domain name service: named"
- start-stop-daemon --stop --quiet --oknodo \
- --pidfile /var/run/named.pid --exec /usr/sbin/named
- start-stop-daemon --start --verbose --exec /usr/sbin/named \
- -- $PARAMS
- echo "."
- ;;
-force-reload|reload)
- echo -n "Reloading configuration of domain name service: named"
- start-stop-daemon --stop --signal 1 --quiet \
- --pidfile /var/run/named.pid --exec /usr/sbin/named
- echo "."
- ;;
-*)
- echo "Usage: /etc/init.d/bind " \
- " {start|stop|restart|reload|force-reload}" >&2
- exit 1
- ;;
-esac
-
-exit 0
- </example>
- </p>
-
- <p>
- Complementing the above init script is a configuration
- file <file>/etc/default/bind</file>, which contains
- configurable parameters used by the script. This would be
- created by the <prgn>postinst</prgn> script if it was not
- already present, and removed on purge by the
- <prgn>postrm</prgn> script.
- <example compact="compact">
-# 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 you can base your
+ An example on which you can base your
<file>/etc/init.d</file> scripts is found in
<file>/etc/init.d/skeleton</file>.
</p>
- <p>
- If this package is happy with the default setup from
- <prgn>update-rc.d</prgn>, namely an ordering number of 20
- and having named running in all runlevels, it can say in
- its <prgn>postinst</prgn>:
- <example compact="compact">
-update-rc.d bind defaults >/dev/null
- </example>
- And in its <prgn>postrm</prgn>, to remove the links when the
- package is purged:
- <example compact="compact">
-if [ "$1" = purge ]; then
- update-rc.d bind remove >/dev/null
-fi
- </example>
- </p>
</sect1>
</sect>
</p>
<p>
- Here is a list of overall rules that you should use when you
- create output messages. They can be useful if you have a
- non-standard message that is not covered specifically in the
- sections below.
+ Here is a list of overall rules that should be used for
+ messages generated by <file>/etc/init.d</file> scripts.
</p>
<p>
<list>
<item>
- Every message should fit in one line (fewer than 80
+ The message should fit in one line (fewer than 80
characters), start with a capital letter and end with
a period (<tt>.</tt>) and line feed (<tt>"\n"</tt>).
</item>
<item>
- If you want to express that the computer is working on
- something (that is, performing a specific task, not
- starting or stopping a program), we use an "ellipsis"
- (three dots: <tt>...</tt>). Note that we don't insert
- spaces before or after the dots. If the task has been
- completed we write <tt>done.</tt> and a line feed.
+ If the script is performing some time consuming task in
+ the background (not merely starting or stopping a
+ program, for instance), an ellipsis (three dots:
+ <tt>...</tt>) should be output to the screen, with no
+ leading or tailing whitespace or line feeds.
</item>
<item>
- Design your messages as if the computer is telling you
- what he is doing (let him be polite :-), but don't
- mention "him" directly. For example, if you think of
- saying
+ The messages should appear as if the computer is telling
+ the user what it is doing (politely :-), but should not
+ mention "it" directly. For example, instead of:
<example compact="compact">
I'm starting network daemons: nfsd mountd.
</example>
- just say
+ the message should say
<example compact="compact">
Starting network daemons: nfsd mountd.
</example>
</p>
<p>
- There are standard message formats for the following
- situations. They should be used by the <tt>init.d</tt>
- scripts.
+ <tt>init.d</tt> script should use the following standard
+ message formats for the situations enumerated below.
</p>
<p>
<p>When daemons are started</p>
<p>
- If your script starts one or more daemons, the output
+ If the script starts one or more daemons, the output
should look like this (a single line, no leading
spaces):
<example compact="compact">
start-stop-daemon --start --quiet --exec /usr/sbin/lpd
echo "."
</example>
- in the script. If you have more than one daemon to
- start, you should do the following:
+ in the script. If there are more than one daemon to
+ start, the output should look like this:
<example compact="compact">
echo -n "Starting remote file system services:"
echo -n " nfsd"; start-stop-daemon --start --quiet nfsd
echo -n " ugidd"; start-stop-daemon --start --quiet ugidd
echo "."
</example>
- This makes it possible for the user to see what takes
- so long and when the final daemon has been started.
- You should be careful where to put spaces: in the
- example above the system administrator can easily
- comment out a line if he don't wants to start a
- specific daemon, while the displayed message still
+ This makes it possible for the user to see what is
+ happening and when the final daemon has been started.
+ Care should be taken in the placement of white spaces:
+ in the example above the system administrators can
+ easily comment out a line if they don't want to start
+ a specific daemon, while the displayed message still
looks good.
</p>
</item>
</p>
<p>
- For example, stopping the printer daemon will like
- like this:
+ For example, stopping the printer daemon will look like
+ this:
<example compact="compact">
Stopping printer spooler: lpd.
</example>
</example>
You should print the <tt>done.</tt> immediately after
the job has been completed, so that the user is
- informed why she has to wait. You can get this
+ informed why they have to wait. You can get this
behavior by saying
<example compact="compact">
echo -n "Doing something very useful..."
via cron, it should place a file with the name of the
package in one or more of the following directories:
<example compact="compact">
+/etc/cron.hourly
/etc/cron.daily
/etc/cron.weekly
/etc/cron.monthly
</example>
As these directory names imply, the files within them are
- executed on a daily, weekly, or monthly basis,
+ executed on an hourly, daily, weekly, or monthly basis,
respectively. The exact times are listed in
<file>/etc/crontab</file>.</p>
All files installed in any of these directories must be
scripts (e.g., shell scripts or Perl scripts) so that they
can easily be modified by the local system administrator.
- In addition, they should be treated as configuration
- files.
+ In addition, they must be treated as configuration files.
</p>
<p>
- If a certain job has to be executed more frequently than
- daily, the package should install a file
+ If a certain job has to be executed at some other frequency or
+ at a specific time, the package should install a file
<file>/etc/cron.d/<var>package</var></file>. This file uses the
same syntax as <file>/etc/crontab</file> and is processed by
<prgn>cron</prgn> automatically. The file must also be
<p>
The Debian <tt>menu</tt> package provides a standard
interface between packages providing applications and
- documents, and <em>menu programs</em> (either X window
- managers or text-based menu programs such as
- <prgn>pdmenu</prgn>).
+ <em>menu programs</em> (either X window managers or
+ text-based menu programs such as <prgn>pdmenu</prgn>).
</p>
<p>
files in the <tt>debian-policy</tt> package.
It is also available from the Debian web mirrors at
<tt><url name="/doc/packaging-manuals/menu-policy/"
- id="http://www.debian.org/doc/packaging-manuals/menu-policy/"></tt>
- and from the Debian archive mirrors at
- <tt><url name="/doc/package-developer/menu-policy.txt.gz"
- id="http://ftp.debian.org/debian/doc/package-developer/menu-policy.txt.gz"></tt>.
+ id="http://www.debian.org/doc/packaging-manuals/menu-policy/"></tt>.
</p>
<p>
Please also refer to the <em>Debian Menu System</em>
- documentation that comes with the <tt>menu</tt> package for
- information about how to register your applications and web
- documents.
+ documentation that comes with the <package>menu</package>
+ package for information about how to register your
+ applications.
</p>
</sect>
files in the <tt>debian-policy</tt> package.
It is also available from the Debian web mirrors at
<tt><url name="/doc/packaging-manuals/mime-policy/"
- id="http://www.debian.org/doc/packaging-manuals/mime-policy/"></tt>
- and from the Debian archive mirrors at
- <tt><url name="/doc/package-developer/mime-policy.txt.gz"
- id="http://ftp.debian.org/debian/doc/package-developer/mime-policy.txt.gz"></tt>.
+ id="http://www.debian.org/doc/packaging-manuals/mime-policy/"></tt>.
</p>
</sect>
</p>
</sect>
+ <sect id="doc-base">
+ <heading>Registering Documents using doc-base</heading>
+
+ <p>
+ The <package>doc-base</package> package implements a
+ flexible mechanism for handling and presenting
+ documentation. The recommended practice is for every Debian
+ package that provides online documentation (other than just
+ manual pages) to register these documents with
+ <package>doc-base</package> by installing a
+ <package>doc-base</package> control file via the
+ <prgn/install-docs/ script at installation time and
+ de-register the manuals again when the package is removed.
+ </p>
+ <p>
+ Please refer to the documentation that comes with the
+ <package>doc-base</package> package for information and
+ details.
+ </p>
+ </sect>
+
</chapt>
CC = gcc
CFLAGS = -O2 -g -Wall # sane warning options vary between programs
LDFLAGS = # none
-install -s # (or use strip on the files in debian/tmp)
+INSTALL = install -s # (or use strip on the files in debian/tmp)
</example>
</p>
<p>
Although binaries in the build tree should be compiled with
- debugging information by default, it can often be difficult
- to debug programs if they are also subjected to compiler
- optimization. For this reason, it is recommended to support
- the standardized environment
- variable <tt>DEB_BUILD_OPTIONS</tt>. This variable can
- contain several flags to change how a package is compiled
- and built.
- </p>
-
- <p>
- <taglist>
- <tag>noopt</tag>
- <item>
- The presence of this string means that the package
- should be compiled with a minimum of optimization.
- For C programs, it is best to add <tt>-O0</tt>
- to <tt>CFLAGS</tt> (although this is usually the
- default). Some programs might fail to build or run at
- this level of optimization; it may be necessary to
- use <tt>-O1</tt>, for example.
- </item>
- <tag>nostrip</tag>
- <item>
- This string means that the debugging symbols should
- not be stripped from the binary during installation,
- so that debugging information may be included in the package.
- </item>
- </taglist>
- </p>
-
- <p>
- The following makefile snippet is an example of how one may
- implement the build options; you will probably have to
- massage this example in order to make it work for your
- package.
- <example compact="compact">
-CFLAGS = -Wall -g
-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 noopt,$(DEB_BUILD_OPTIONS)))
-CFLAGS += -O0
-else
-CFLAGS += -O2
-endif
-ifeq (,$(findstring nostrip,$(DEB_BUILD_OPTIONS)))
-INSTALL_PROGRAM += -s
-endif
- </example>
+ debugging information by default, it can often be difficult to
+ debug programs if they are also subjected to compiler
+ optimization. For this reason, it is recommended to support the
+ standardized environment variable <tt>DEB_BUILD_OPTIONS</tt>
+ (see <ref id="debianrules-options">). This variable can contain
+ several flags to change how a package is compiled and built.
</p>
<p>
<sect id="libraries">
<heading>Libraries</heading>
+ <p>
+ If the package is <strong>architecture: any</strong>, then
+ the shared library compilation and linking flags must have
+ <tt>-fPIC</tt>, or the package shall not build on some of
+ the supported architectures<footnote>
+ <p>
+ If you are using GCC, <tt>-fPIC</tt> produces code with
+ relocatable position independent code, which is required for
+ most architectures to create a shared library, with i386 and
+ perhaps some others where non position independent code is
+ permitted in a shared library.
+ </p>
+ <p>
+ Position independent code may have a performance penalty,
+ especially on <tt>i386</tt>. However, in most cases the
+ speed penalty must be measured against the memory wasted on
+ the few architectures where non position independent code is
+ even possible.
+ </p>
+ </footnote>. Any exception to this rule must be discussed on
+ the mailing list <em>debian-devel@lists.debian.org</em>, and
+ a rough consensus obtained. The reasons for not compiling
+ with <tt>-fPIC</tt> flag must be recorded in the file
+ <tt>README.Debian</tt>, and care must be taken to either
+ restrict the architecture or arrange for <tt>-fPIC</tt> to
+ be used on architectures where it is required.<footnote>
+ <p>
+ Some of the reasons why this might be required is if the
+ library contains hand crafted assembly code that is not
+ relocatable, the speed penalty is excessive for compute
+ intensive libs, and similar reasons.
+ </p>
+ </footnote>
+ </p>
<p>
- The shared version of a library must be compiled with
- <tt>-fPIC</tt>, and the static version must not be. In other
- words, each source unit (<tt>*.c</tt>, for example, for C files)
- will need to be compiled twice.
+ As to the static libraries, the common case is not to have
+ relocatable code, since there is no benefit, unless in specific
+ cases; therefore the static version must not be compiled
+ with the <tt>-fPIC</tt> flag. Any exception to this rule
+ should be discussed on the mailing list
+ <em>debian-devel@lists.debian.org</em>, and the reasons for
+ compiling with the <tt>-fPIC</tt> flag must be recorded in
+ the file <tt>README.Debian</tt>. <footnote>
+ <p>
+ Some of the reasons for linking static libraries with
+ the <tt>-fPIC</tt> flag are if, for example, one needs a
+ Perl API for a library that is under rapid development,
+ and has an unstable API, so shared libraries are
+ pointless at this phase of the library's development. In
+ that case, since Perl needs a library with relocatable
+ code, it may make sense to create a static library with
+ relocatable code. Another reason cited is if you are
+ distilling various libraries into a common shared
+ library, like <tt>mklibs</tt> does in the Debian
+ installer project.
+ </p>
+ </footnote>
</p>
-
+ <p>
+ In other words, if both a shared and a static library is
+ being built, each source unit (<tt>*.c</tt>, for example,
+ for C files) will need to be compiled twice, for the normal
+ case.
+ </p>
<p>
You must specify the gcc option <tt>-D_REENTRANT</tt>
when building a library (either static or shared) to make
<tt>#!/usr/bin/perl</tt>.
</p>
+ <p>
+ When scripts are installed into a directory in the system
+ PATH, the script name should not include an extension such
+ as <tt>.sh</tt> or <tt>.pl</tt> that denotes the scripting
+ language currently used to implement it.
+ </p>
<p>
Shell scripts (<prgn>sh</prgn> and <prgn>bash</prgn>)
should almost certainly start with <tt>set -e</tt> so that
</p>
<p>
- The standard shell interpreter <file>/bin/sh</file> can be a
- symbolic link to any POSIX compatible shell, if <tt>echo
- -n</tt> does not generate a newline.<footnote>
- Debian policy specifies POSIX behavior for
- <file>/bin/sh</file>, but <tt>echo -n</tt> has widespread
- use in the Linux community (in particular including this
- policy, the Linux kernel source, many Debian scripts,
- etc.). This <tt>echo -n</tt> mechanism is valid but not
- required under POSIX, hence this explicit addition.
- Also, rumour has it that this shall be mandated under
- the LSB anyway.
+ Scripts may assume that <file>/bin/sh</file> implements the
+ SUSv3 Shell Command Language<footnote>
+ Single UNIX Specification, version 3, which is also IEEE
+ 1003.1-2004 (POSIX), and is available on the World Wide Web
+ from <url id="http://www.unix.org/version3/online.html"
+ name="The Open Group"> after free
+ registration.</footnote>
+ plus the following additional features not mandated by
+ SUSv3:<footnote>
+ These features are in widespread use in the Linux community
+ and are implemented in all of bash, dash, and ksh, the most
+ common shells users may wish to use as <file>/bin/sh</file>.
</footnote>
- Thus, shell scripts specifying <file>/bin/sh</file> as
- interpreter should only use POSIX features. If a script
- requires non-POSIX features from the shell interpreter, the
- appropriate shell must be specified in the first line of the
- script (e.g., <tt>#!/bin/bash</tt>) and the package must
- depend on the package providing the shell (unless the shell
- package is marked "Essential", as in the case of
- <prgn>bash</prgn>).
- </p>
-
- <p>
- You may wish to restrict your script to POSIX features when
- possible so that it may use <file>/bin/sh</file> as its
- interpreter. If your script works with <prgn>dash</prgn>
- (originally called <prgn>ash</prgn>), it's probably POSIX
- compliant, but if you are in doubt, use
+ <list>
+ <item><tt>echo -n</tt>, if implemented as a shell built-in,
+ must not generate a newline.</item>
+ <item><tt>test</tt>, if implemented as a shell built-in, must
+ 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:
+<example compact>
+fname () {
+ local a
+ a=''
+ # ... use a ...
+}
+</example>
+ must be supported.
+ </item>
+ </list>
+ If a shell script requires non-SUSv3 features from the shell
+ interpreter other than those listed above, the appropriate shell
+ must be specified in the first line of the script (e.g.,
+ <tt>#!/bin/bash</tt>) and the package must depend on the package
+ providing the shell (unless the shell package is marked
+ "Essential", as in the case of <prgn>bash</prgn>).
+ </p>
+
+ <p>
+ You may wish to restrict your script to SUSv3 features plus the
+ above set when possible so that it may use <file>/bin/sh</file>
+ as its interpreter. If your script works with <prgn>dash</prgn>
+ (originally called <prgn>ash</prgn>), it probably complies with
+ the above requirements, but if you are in doubt, use
<file>/bin/bash</file>.
</p>
<prgn>csh</prgn> and <prgn>tcsh</prgn> should be avoided as
scripting languages. See <em>Csh Programming Considered
Harmful</em>, one of the <tt>comp.unix.*</tt> FAQs, which
- can be found at <url id="http://language.perl.com/versus/csh.whynot">.
+ can be found at <url id="http://www.faqs.org/faqs/unix-faq/shell/csh-whynot/">.
If an upstream package comes with <prgn>csh</prgn> scripts
then you must make sure that they start with
<tt>#!/bin/csh</tt> and make your package depend on the
<p>
Any scripts which create files in world-writeable
directories (e.g., in <file>/tmp</file>) must use a
- mechanism which will fail if a file with the same name
- already exists.
+ mechanism which will fail atomically if a file with the same
+ name already exists.
</p>
<p>
</p>
<p>
- Note that a script that embeds configuration information
- (such as most of the files in <file>/etc/default</file> and
- <file>/etc/cron.{daily,weekly,monthly}</file>) is de-facto a
- configuration file and should be treated as such.
+ As noted elsewhere, <file>/etc/init.d</file> scripts,
+ <file>/etc/default</file> files, scripts installed in
+ <file>/etc/cron.{hourly,daily,weekly,monthly}</file>, and cron
+ configuration installed in <file>/etc/cron.d</file> must be
+ treated as configuration files. In general, any script that
+ embeds configuration information is de-facto a configuration
+ file and should be treated as such.
</p>
</sect1>
variety of ways <prgn>dpkg</prgn> can call maintainer
scripts, must not overwrite or otherwise mangle the user's
configuration without asking, must not ask unnecessary
- questions (particularly during upgrades), and otherwise be
- good citizens.
+ questions (particularly during upgrades), and must
+ otherwise be good citizens.
</p>
<p>
<p>
Furthermore, programs should be configured by the Debian
default installation to behave as closely to the upstream
- default behaviour as possible.
+ default behavior as possible.
</p>
<p>
mode 2775. The ownership of the directory should be
consistent with its mode: if a directory is mode 2775, it
should be owned by the group that needs write access to
- it.
+ it.<footnote>
+ <p>
+ When a package is upgraded, and the owner or permissions
+ of a file included in the package has changed, dpkg
+ arranges for the ownership and permissions to be
+ correctly set upon installation. However, this does not
+ extend to directories; the permissions and ownership of
+ directories already on the system does not change on
+ install or upgrade of packages. This makes sense, since
+ otherwise common directories like <tt>/usr</tt> would
+ always be in flux. To correctly change permissions of a
+ directory the package owns, explicit action is required,
+ usually in the <tt>postinst</tt> script. Care must be
+ taken to handle downgrades as well, in that case.
+ </p>
+ </footnote>
</p>
+
<p>
Setuid and setgid executables should be mode 4755 or 2755
respectively, and owned by the appropriate user or group.
normally have their permissions reset to the distributed
permissions when the package is reinstalled. However,
the use of <prgn>dpkg-statoverride</prgn> overrides this
- default behaviour. If you use this method, you should
+ default behavior. If you use this method, you should
remember to describe <prgn>dpkg-statoverride</prgn> in
the package documentation; being a relatively new
addition to Debian, it is probably not yet well-known.
description of the use of <prgn>dpkg-statoverride</prgn>.
</p>
- <p>
- <prgn>dpkg-statoverride</prgn> is a replacement for the
- deprecated <tt>suidmanager</tt> package. Packages which
- previously used <tt>suidmanager</tt> should have a
- <tt>Conflicts: suidmanager (<< 0.50)</tt> entry (or even
- <tt>(<< 0.52)</tt>), and calls to <tt>suidregister</tt>
- and <tt>suidunregister</tt> should now be simply removed
- from the maintainer scripts.
- </p>
-
<p>
If a system administrator wishes to have a file (or
directory or other such thing) installed with owner and
permissions different from those in the distributed Debian
- package,
he can use the <prgn>dpkg-statoverride</prgn>
+ package,
they can use the <prgn>dpkg-statoverride</prgn>
program to instruct <prgn>dpkg</prgn> to use the different
settings every time the file is installed. Thus the
package maintainer should distribute the files with their
maintainer can use <tt>debconf</tt> to find out the
preference, and call <prgn>dpkg-statoverride</prgn> in the
maintainer script if necessary to accommodate the system
- administrator's choice.
+ administrator's choice. Care must be taken during
+ upgrades to not override an existing setting.
</p>
<p>
<example>
for i in /usr/bin/foo /usr/sbin/bar
do
- if ! dpkg-statoverride --list $i >/dev/null
+ # only do something when no setting exists
+ if ! dpkg-statoverride --list $i >/dev/null 2>&1
then
- dpkg-statoverride --update --add sysuser root 4755 $i
+ #include: debconf processing, question about foo and bar
+ if [ "$RET" = "true" ] ; then
+ dpkg-statoverride --update --add sysuser root 4755 $i
+ fi
fi
done
</example>
<p>
If a program needs to specify an <em>architecture specification
- string</em> in some place, the following format should be
- used: <var>arch</var>-<var>os</var><footnote>
- The following architectures and operating systems are
- currently recognised by <prgn>dpkg-architecture</prgn>.
- The architecture, <tt><var>arch</var></tt>, is one of
- the following: <tt>alpha</tt>, <tt>arm</tt>,
- <tt>hppa</tt>, <tt>i386</tt>, <tt>ia64</tt>,
- <tt>m68k</tt>, <tt>mips</tt>, <tt>mipsel</tt>,
- <tt>powerpc</tt>, <tt>s390</tt>, <tt>sh</tt>,
- <tt>sheb</tt>, <tt>sparc</tt> and <tt>sparc64</tt>. The
- operating system, <tt><var>os</var></tt>, is one of:
- <tt>linux</tt>, <tt>gnu</tt>, <tt>freebsd</tt> and
- <tt>openbsd</tt>. Use of <tt>gnu</tt> in this string is
- reserved for the GNU/Hurd operating system.
- </footnote>.
+ string</em> in some place, it should select one of the
+ strings provided by <tt>dpkg-architecture -L</tt>. The
+ strings are in the format
+ <tt><var>os</var>-<var>arch</var></tt>, though the OS part
+ is sometimes elided, as when the OS is Linux.<footnote>
+ <p>Currently, the strings are:
+ i386 ia64 alpha amd64 armeb arm hppa m32r m68k mips
+ mipsel powerpc ppc64 s390 s390x sh3 sh3eb sh4 sh4eb
+ sparc darwin-i386 darwin-ia64 darwin-alpha darwin-amd64
+ darwin-armeb darwin-arm darwin-hppa darwin-m32r
+ darwin-m68k darwin-mips darwin-mipsel darwin-powerpc
+ darwin-ppc64 darwin-s390 darwin-s390x darwin-sh3
+ darwin-sh3eb darwin-sh4 darwin-sh4eb darwin-sparc
+ freebsd-i386 freebsd-ia64 freebsd-alpha freebsd-amd64
+ freebsd-armeb freebsd-arm freebsd-hppa freebsd-m32r
+ freebsd-m68k freebsd-mips freebsd-mipsel freebsd-powerpc
+ freebsd-ppc64 freebsd-s390 freebsd-s390x freebsd-sh3
+ freebsd-sh3eb freebsd-sh4 freebsd-sh4eb freebsd-sparc
+ kfreebsd-i386 kfreebsd-ia64 kfreebsd-alpha
+ kfreebsd-amd64 kfreebsd-armeb kfreebsd-arm kfreebsd-hppa
+ kfreebsd-m32r kfreebsd-m68k kfreebsd-mips
+ kfreebsd-mipsel kfreebsd-powerpc kfreebsd-ppc64
+ kfreebsd-s390 kfreebsd-s390x kfreebsd-sh3 kfreebsd-sh3eb
+ kfreebsd-sh4 kfreebsd-sh4eb kfreebsd-sparc knetbsd-i386
+ knetbsd-ia64 knetbsd-alpha knetbsd-amd64 knetbsd-armeb
+ knetbsd-arm knetbsd-hppa knetbsd-m32r knetbsd-m68k
+ knetbsd-mips knetbsd-mipsel knetbsd-powerpc
+ knetbsd-ppc64 knetbsd-s390 knetbsd-s390x knetbsd-sh3
+ knetbsd-sh3eb knetbsd-sh4 knetbsd-sh4eb knetbsd-sparc
+ netbsd-i386 netbsd-ia64 netbsd-alpha netbsd-amd64
+ netbsd-armeb netbsd-arm netbsd-hppa netbsd-m32r
+ netbsd-m68k netbsd-mips netbsd-mipsel netbsd-powerpc
+ netbsd-ppc64 netbsd-s390 netbsd-s390x netbsd-sh3
+ netbsd-sh3eb netbsd-sh4 netbsd-sh4eb netbsd-sparc
+ openbsd-i386 openbsd-ia64 openbsd-alpha openbsd-amd64
+ openbsd-armeb openbsd-arm openbsd-hppa openbsd-m32r
+ openbsd-m68k openbsd-mips openbsd-mipsel openbsd-powerpc
+ openbsd-ppc64 openbsd-s390 openbsd-s390x openbsd-sh3
+ openbsd-sh3eb openbsd-sh4 openbsd-sh4eb openbsd-sparc
+ hurd-i386 hurd-ia64 hurd-alpha hurd-amd64 hurd-armeb
+ hurd-arm hurd-hppa hurd-m32r hurd-m68k hurd-mips
+ hurd-mipsel hurd-powerpc hurd-ppc64 hurd-s390 hurd-s390x
+ hurd-sh3 hurd-sh3eb hurd-sh4 hurd-sh4eb hurd-sparc
+ </p>
+ </footnote>
</p>
<p>
<p>
The files <file>/var/run/utmp</file>, <file>/var/log/wtmp</file> and
- <file>/var/log/lastlog</file> must be installed writeable by
+ <file>/var/log/lastlog</file> must be installed writable by
group <tt>utmp</tt>. Programs which need to modify those
files must be installed setgid <tt>utmp</tt>.
</p>
program to edit or display a text document. Since there are
lots of different editors and pagers available in the Debian
distribution, the system administrator and each user should
- have the possibility to choose his/her preferred editor and
+ have the possibility to choose their preferred editor and
pager.
</p>
<example compact="compact">
http://localhost/cgi-bin/<var>cgi-bin-name</var>
</example>
+
</item>
<item>
</p>
</item>
+ <item>
+ <p>Access to images</p>
+ <p>
+ It is recommended that images for a package be stored
+ in <tt>/usr/share/images/<var>package</var></tt> and
+ may be referred to through an alias <tt>/images/</tt>
+ as
+ <example>
+ http://localhost/images/<package>/<filename>
+ </example>
+
+ </p>
+ </item>
+
<item>
<p>Web Document Root</p>
the Web Document Root. Instead they should use the
/usr/share/doc/<var>package</var> directory for
documents and register the Web Application via the
- menu package. If access to the web document root is
- unavoidable then use
+ <package>doc-base</package> package. If access to the
+ web document root is unavoidable then use
<example compact="compact">
/var/www
</example>
has put the real document root.
</p>
</item>
-
+ <item><p>Providing httpd and/or httpd-cgi</p>
+ <p>
+ All web servers should provide the virtual package
+ <tt>httpd</tt>. If a web server has CGI support it should
+ provide <tt>httpd-cgi</tt> additionally.
+ </p>
+ <p>
+ All web applications which do not contain CGI scripts should
+ depend on <tt>httpd</tt>, all those web applications which
+ <tt>do</tt> contain CGI scripts, should depend on
+ <tt>httpd-cgi</tt>.
+ </p>
+ </item>
</enumlist>
</p>
</sect>
</p>
<p>
- Such package should check for the existence of this file
+ Such a package should check for the existence of this file
when it is being configured. If it exists, it should be
used without comment, although an MTA's configuration script
may wish to prompt the user even if it finds that this file
"view" in a multiple-document interface (MDI).
</footnote>
and runs the specified <var>command</var>,
- interpreting the entirity of the rest of the command
+ interpreting the entirety of the rest of the command
line as a command to pass straight to exec, in the
manner that <tt>xterm</tt> does.
</item>
<item>
If the window manager complies with <url
- id="http://www.freedesktop.org/standards/wm-spec.html"
+ id="http://www.freedesktop.org/Standards/wm-spec"
name="The Window Manager Specification Project">,
written by the <url id="http://www.freedesktop.org/"
name="Free Desktop Group">, add 40 points.
For the purposes of Debian Policy, a "font for the X
Window System" is one which is accessed via X protocol
requests. Fonts for the Linux console, for PostScript
- renderers, or any other purpose, do not fit this
+ renderer, or any other purpose, do not fit this
definition. Any tool which makes such fonts available
to the X Window System, however, must abide by this
font policy.
be used. Packages must not Depend on font
packages.<footnote>
This is because the X server may retrieve fonts
- from the local filesystem or over the network
+ from the local file system or over the network
from an X font server; the Debian package system
is empowered to deal only with the local
- filesystem.
+ file system.
</footnote>
</item>
<item>
BDF fonts must be converted to PCF fonts with the
<prgn>bdftopcf</prgn> utility (available in the
- <tt>xutils</tt> package, <prgn>gzip</prgn>ped, and
+ <tt>x
fonts-utils</tt> package, <prgn>gzip</prgn>ped, and
placed in a directory that corresponds to their
resolution:
<list compact="compact">
<item>
100 dpi fonts must be placed in
- <file>/usr/X11R6/lib/X11/fonts/100dpi/</file>.
+ <file>/usr/share/fonts/X11/100dpi/</file>.
</item>
<item>
75 dpi fonts must be placed in
- <file>/usr/X11R6/lib/X11/fonts/75dpi/</file>.
+ <file>/usr/share/fonts/X11/75dpi/</file>.
</item>
<item>
Character-cell fonts, cursor fonts, and other
low-resolution fonts must be placed in
- <file>/usr/X11R6/lib/X11/fonts/misc/</file>.
+ <file>/usr/share/fonts/X11/misc/</file>.
</item>
</list>
</item>
<item>
Speedo fonts must be placed in
- <file>/usr/X11R6/lib/X11/fonts/Speedo/</file>.
+ <file>/usr/share/fonts/X11/Speedo/</file>.
</item>
<item>
Type 1 fonts must be placed in
- <file>/usr/X11R6/lib/X11/fonts/Type1/</file>. If font
+ <file>/usr/share/fonts/X11/Type1/</file>. If font
metric files are available, they must be placed here
as well.
</item>
<item>
- Subdirectories of <file>/usr/X11R6/lib/X11/fonts/</file>
+ Subdirectories of <file>/usr/share/fonts/X11/</file>
other than those listed above must be neither
created nor used. (The <file>PEX</file>, <file>CID</file>,
and <file>cyrillic</file> directories are excepted for
<file>/etc/X11/fonts/<var>fontdir</var>/<var>package</var>.<var>extension</var></file>,
where <var>fontdir</var> is the name of the
subdirectory of
- <file>/usr/X11R6/lib/X11/fonts/</file> where the
+ <file>/usr/share/fonts/X11/</file> where the
package's corresponding fonts are stored
(e.g., <tt>75dpi</tt> or <tt>misc</tt>),
<var>package</var> is the name of the package
<item>
Font packages must declare a dependency on
- <tt>xutils (>> 4.0.3)</tt> in their control
+ <tt>xfonts-utils</tt> in their control
data.
</item>
configuration file.<footnote>
Note that this mechanism is not the same as using
app-defaults; app-defaults are tied to the client
- binary on the local filesystem, whereas X resources
+ binary on the local file system, whereas X resources
are stored in the X server and affect all connecting
clients.
</footnote>
<p>
Packages using the X Window System should not be
- configured to install files under the <file>/usr/X11R6/</file>
- directory unless they use <prgn>imake</prgn>. The
+ configured to install files under the
+ <file>/usr/X11R6/</file> directory. The
<file>/usr/X11R6/</file> directory hierarchy should be
- regarded as deprecated for all packages except the X
- Window System itself, and those which use the
- <prgn>imake</prgn> program it provides, in which case the
- packages may transition out of the <file>/usr/X11R6/</file>
- directory at the maintainer's discretion.<footnote>
- <prgn>Imake</prgn>-using programs are exempt because,
- as long as they are written correctly, the pathnames
- they use to locate resources and install themselves
- are derived wholly from the X Window System
- configuration. Thus, in the event that the X Window
- System moves to <file>/usr/X11R7/</file>,
- <file>/usr/X12/</file>, or just plain <file>/usr/</file>, all
- that is required for these programs is a recompile
- against the corresponding X Window System library
- development packages.
- </footnote>
+ regarded as obsolete.
</p>
<p>
<p>
The installation of files into subdirectories
of <file>/usr/X11R6/include/X11/</file> and
- <file>/usr/X11R6/lib/X11/</file> is permitted but discouraged;
+ <file>/usr/X11R6/lib/X11/</file> is now prohibited;
package maintainers should determine if subdirectories of
<file>/usr/lib/</file> and <file>/usr/share/</file> can be used
- instead. (The use of symbolic links from the
- <file>X11R6</file> directories to other FHS-compliant
- locations is encouraged if the program is not easily
- configured to look elsewhere for its files.)
- </p>
-
- <p>
- Packages must not provide or install files into the directories
- <file>/usr/bin/X11/</file>, <file>/usr/include/X11/</file> or
- <file>/usr/lib/X11/</file>. Files within a package should,
- however, make reference to these directories, rather than
- their <tt>X11R6</tt>-named counterparts
- <file>/usr/X11R6/bin/</file>, <file>/usr/X11R6/include/X11/</file>
- and <file>/usr/X11R6/lib/X11/</file>, if the resources being
- referred to have not been moved to other FHS-compliant
- locations.
+ instead.
+ </p>
+
+ <p>
+ Packages should install any relevant files into the
+ directories <file>/usr/include/X11/</file> and
+ <file>/usr/lib/X11/</file>, but if they do so, they must
+ pre-depend on <tt>x11-common (>=
+ 1:7.0.0)</tt><footnote>
+ <p>
+ These libraries used to be all symbolic
+ links. However, with <tt>X11R7</tt>,
+ <tt>/usr/include/X11</tt> and <tt>/usr/lib/X11</tt>
+ are now real directories, and packages
+ <strong>should</strong> ship their files here instead
+ of in <tt>/usr/X11R6/{include,lib}/X11</tt>.
+ <tt>x11-common (>= 1:7.0.0) </tt> is the package
+ responsible for converting these symlinks into
+ directories.
+ </p>
+ </footnote>
</p>
</sect1>
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 his or her possession.
+ the license of the copy of Motif in their possession.
</p>
</sect1>
</sect>
files in the <tt>debian-policy</tt> package.
It is also available from the Debian web mirrors at
<tt><url name="/doc/packaging-manuals/perl-policy/"
- id="http://www.debian.org/doc/packaging-manuals/perl-policy/"></tt>
- and from the Debian archive mirrors at
- <tt><url name="/doc/package-developer/perl-policy.txt.gz"
- id="http://ftp.debian.org/debian/doc/package-developer/perl-policy.txt.gz"></tt>.
+ id="http://www.debian.org/doc/packaging-manuals/perl-policy/"></tt>.
</p>
</sect>
<p>
Games which require protected, privileged access to
- high-score files, savegames, etc., may be made
+ high-score files, saved games, etc., may be made
set-<em>group</em>-id (mode 2755) and owned by
<tt>root.games</tt>, and use files and directories with
appropriate permissions (770 <tt>root.games</tt>, for
You should install manual pages in <prgn>nroff</prgn> source
form, in appropriate places under <file>/usr/share/man</file>.
You should only use sections 1 to 9 (see the FHS for more
- details). You must not install a preformatted "cat page".
+ details). You must not install a pre-formatted "cat page".
</p>
<p>
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.<footnote>
+ until a proper man page is available.<footnote>
It is not very hard to write a man page. See the
<url id="http://www.schweikhardt.net/man_page_howto.html"
name="Man-Page-HOWTO">,
</p>
<p>
- 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.
</p>
<p>
- 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 <file>.so</file>
feature, but there is no need to fiddle with the relevant
parts of the upstream source to change from <file>.so</file> 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 <file>.so</file> directives. The filename
- in a <file>.so</file> in a manpage should be relative to the
- base of the manpage tree (usually
+ in a <file>.so</file> in a man page should be relative to the
+ base of the man page tree (usually
<file>/usr/share/man</file>). If you do not create any links
(whether symlinks, hard links, or <tt>.so</tt> directives)
- in the filesystem to the alternate names of the manpage,
+ in the file system to the alternate names of the man page,
then you should not rely on <prgn>man</prgn> finding your
- manpage under those names based solely on the information in
- the manpage's header.<footnote>
+ man page under those names based solely on the information in
+ the man page's header.<footnote>
Supporting this in <prgn>man</prgn> often requires
unreasonable processing time to find a manual page or to
report that none exists, and moves knowledge into man's
- database that would be better left in the filesystem.
+ database that would be better left in the file system.
This support is therefore deprecated and will cease to
be present in the future.
</footnote>
</p>
+
+ <p>
+ Manual pages in locale-specific subdirectories of
+ <file>/usr/share/man</file> should use either UTF-8 or the usual
+ legacy encoding for that language (normally the one corresponding
+ to the shortest relevant locale name in
+ <file>/usr/share/i18n/SUPPORTED</file>). For example, pages under
+ <file>/usr/share/man/fr</file> should use either UTF-8 or
+ ISO-8859-1.<footnote>
+ <prgn>man</prgn> will automatically detect whether UTF-8 is in
+ use. In future, all manual pages will be required to use
+ UTF-8.
+ </footnote>
+ </p>
+
+ <p>
+ A country name (the <tt>DE</tt> in <tt>de_DE</tt>) should not be
+ included in the subdirectory name unless it indicates a
+ significant difference in the language, as this excludes
+ speakers of the language in other countries.<footnote>
+ At the time of writing, Chinese and Portuguese are the main
+ languages with such differences, so <file>pt_BR</file>,
+ <file>zh_CN</file>, and <file>zh_TW</file> are all allowed.
+ </footnote>
+ </p>
+
+ <p>
+ Due to limitations in current implementations, all characters
+ in the manual page source should be representable in the usual
+ legacy encoding for that language, even if the file is
+ actually encoded in UTF-8. Safe alternative ways to write many
+ characters outside that range may be found in
+ <manref name="groff_char" section="7">.
+ </p>
</sect>
<sect>
<p>
Any additional documentation that comes with the package may
be installed at the discretion of the package maintainer.
- Text documentation should be installed in the directory
+ Plain text documentation should be installed in the directory
<file>/usr/share/doc/<var>package</var></file>, where
<var>package</var> is the name of the package, and
compressed with <tt>gzip -9</tt> unless it is small.
any programs to break.
</footnote>.
Any files that are referenced by programs but are also
- useful as standalone documentation should be installed under
+ useful as stand alone documentation should be installed under
<file>/usr/share/<var>package</var>/</file> with symbolic links from
<file>/usr/share/doc/<var>package</var></file>.
</p>
<file>/usr/share/doc/<var>package</var></file> may be a symbolic
link to another directory in <file>/usr/share/doc</file> only if
the two packages both come from the same source and the
- first package Depends on the second.
+ first package Depends on the second.<footnote>
+ <p>
+ Please note that this does not override the section on
+ changelog files below, so the file
+ <file>/usr/share/<var>package</var>/changelog.Debian.gz</file>
+ must refer to the changelog for the current version of
+ <var>package</var> in question. In practice, this means
+ that the sources of the target and the destination of the
+ symlink must be the same (same source package and
+ version).
+ </p>
+ </footnote>
</p>
<p>
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.</p>
+ involved with its creation.
+ </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.
+ </p>
<p>
A copy of the file which will be installed in
</p>
<p>
- Packages distributed under the UCB BSD license, the Artistic
- license, the GNU GPL, and the GNU LGPL should refer to the
- files <file>/usr/share/common-licenses/BSD</file>,
- <file>/usr/share/common-licenses/Artistic</file>,
- <file>/usr/share/common-licenses/GPL</file>, and
- <file>/usr/share/common-licenses/LGPL</file> respectively,
- rather than quoting them in the copyright file.
+ 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
+ files under <file>/usr/share/common-licenses</file>,<footnote>
+ <p>
+ In particular,
+ <file>/usr/share/common-licenses/BSD</file>,
+ <file>/usr/share/common-licenses/Apache-2.0</file>,
+ <file>/usr/share/common-licenses/Artistic</file>,
+ <file>/usr/share/common-licenses/GPL-2</file>,
+ <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>
+ respectively.
+ </p>
+ </footnote> rather than quoting them in the copyright
+ file.
</p>
<p>
<prgn>dpkg</prgn> is a suite of programs for creating binary
package files and installing and removing them on Unix
systems.<footnote>
- <prgn>dpkg</prgn> is targetted primarily at Debian
+ <prgn>dpkg</prgn> is targeted primarily at Debian
GNU/Linux, but may work on or be ported to other
systems.
</footnote>
<p>
This manual describes the technical aspects of creating Debian
binary packages (<file>.deb</file> files). It documents the
- behaviour of the package management programs
+ behavior of the package management programs
<prgn>dpkg</prgn>, <prgn>dselect</prgn> et al. and the way
they interact with packages.</p>
<p>
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.
+ should therefore be read in conjunction with those programs'
+ man pages.
</p>
<p>
for managing various system configuration and similar issues,
such as <prgn>update-rc.d</prgn> and
<prgn>install-info</prgn>, are not described in detail here -
- please see their manpages.
+ please see their man pages.
</p>
<p>
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
- <file>deb(5)</file> manpage.
+ <file>deb(5)</file> man page.
</p>
<p>
In order to create a binary package you must make a
directory tree which contains all the files and directories
- you want to have in the filesystem data part of the package.
+ you want to have in the file system data part of the package.
In Debian-format source packages this directory is usually
<file>debian/tmp</file>, relative to the top of the package's
source tree.
<p>
You need to add one special directory to the root of the
- miniature filesystem tree you're creating:
+ miniature file system tree you're creating:
<prgn>DEBIAN</prgn>. It should contain the control
information files, notably the binary package control file
(see <ref id="pkg-controlfile">).
<p>
The <prgn>DEBIAN</prgn> directory will not appear in the
- filesystem archive of the package, and so won't be installed
+ file system archive of the package, and so won't be installed
by <prgn>dpkg</prgn> when the package is installed.
</p>
</p>
<p>
- See the manpage <manref name="dpkg-deb" section="8"> for details of how
+ See the man page <manref name="dpkg-deb" section="8"> for details of how
to examine the contents of this newly-created file. You may find the
output of following commands enlightening:
<example>
</example>
To view the copyright file for a package you could use this command:
<example>
- dpkg --fsys-tarfile <var>filename</var>.deb | tar xof usr/share/doc/<var>\*</var>copyright | less
+ dpkg --fsys-tarfile <var>filename</var>.deb | tar xOf - \*/copyright | pager
</example>
</p>
</sect>
</tag>
<item>
<p>
- These are exectuable files (usually scripts) which
+ These are executable files (usually scripts) which
<prgn>dpkg</prgn> runs during installation, upgrade
and removal of packages. They allow the package to
deal with matters which are particular to that package
encoding of
<url id="http://www.unicode.org/"
name="Unicode">.<footnote>
- <p>
- Support for Unicode, and specifically UTF-8, is
- steadily increasing among popular applications in
- Debian. For example, in unstable, GNOME 2 has
- excellent support (almost level 2) in almost all its
- applications; the big remaining one is gnome-terminal,
- of which one requires development versions in order to
- support UTF-8 (available in Debian experimental now if
- you want to play). I think that by the time sarge is
- released, UTF-8 support will start to hit critical
- mass. </p>
<p>
I think it is fairly obvious that we need to
eventually transition to UTF-8 for our package
- infrastructure; it is really the only sane charset in
+ infrastructure; it is really the only sane char-set in
an international environment. Now, we can't switch to
using UTF-8 for package control fields and the like
until dpkg has better support, but one thing we can
<p>
If the changelog format does not contain date or package
name information this information should be omitted from
- the output. The parser should not attempt to synthesise
+ the output. The parser should not attempt to synthesize
it or find it from other sources.
</p>
This is the canonical temporary location for the
construction of binary packages by the <tt>binary</tt>
target. The directory <file>tmp</file> serves as the root of
- the filesystem tree as it is being constructed (for
+ the file system tree as it is being constructed (for
example, by using the package's upstream makefiles install
targets and redirecting the output there), and it also
contains the <tt>DEBIAN</tt> subdirectory. See <ref
</tag>
<item>
-
<p>
This is a compressed (with <tt>gzip -9</tt>)
<prgn>tar</prgn> file containing the source code from
- the upstream authors of the program. The tarfile
- unpacks into a directory
- <file><var>package</var>-<var>upstream-version</var>.orig</file>,
- and does not contain files anywhere other than in
- there or in its subdirectories.</p>
+ the upstream authors of the program.
+ </p>
</item>
<tag>
automatically make the <file>debian/rules</file> file
executable (see below).</p></item>
</taglist>
-
+ </p>
<p>
If there is no original source code - for example, if the
maintainer is the same as the upstream maintainer - the
format is slightly different: then there is no diff, and the
tarfile is named
- <file><var>package</var>_<var>version</var>.tar.gz</file> and
- contains a directory
+ <file><var>package</var>_<var>version</var>.tar.gz</file>,
+ and preferably contains a directory named
<file><var>package</var>-<var>version</var></file>.
</p>
</sect>
are handled specially by <prgn>dpkg-source</prgn> - before
applying the changes it will create the <file>debian</file>
directory, and afterwards it will make
- <file>debian/rules</file> world-exectuable.
+ <file>debian/rules</file> world-executable.
</p>
</sect1>
</sect>
This field in <prgn>dpkg</prgn>'s status file records
whether the user wants a package installed, removed or
left alone, whether it is broken (requiring
- reinstallation) or not and what its current state on the
+ re-installation) or not and what its current state on the
system is. Each of these pieces of information is a
single word.
</p>
<heading>Obsolete fields</heading>
<p>
- These are still recogni
sed by <prgn>dpkg</prgn> but should
+ These are still recogni
zed by <prgn>dpkg</prgn> but should
not appear anywhere any more.
<taglist compact="compact">
When a package is installed for the first time
<prgn>dpkg</prgn> will install the file that comes with it,
unless that would mean overwriting a file already on the
- filesystem.
+ file system.
</p>
<p>
</p>
<p>
- See the manpage <manref name="update-alternatives"
+ See the man page <manref name="update-alternatives"
section="8"> for details.
</p>
</book>
</debiandoc>
+<!-- Local variables: -->
+<!-- indent-tabs-mode: t -->
+<!-- End: -->
<!-- vim:set ai et sts=2 sw=2 tw=76: -->
projects / debian / debian-policy.git / blobdiff