<!entity % versiondata SYSTEM "version.ent"> %versiondata;
]>
<debiandoc>
- <!--
- Debian GNU/Linux Policy Manual.
- Copyright (C)1996,1997,1998 Ian Jackson and Christian Schwarz;
- released under the terms of the GNU
- General Public License, version 2 or (at your option) any later.
- Initial version 1996, Ian Jackson, ijackson@gnu.ai.mit.edu
- Revised November 27, 1996, David A. Morris, bweaver@debian.org
- New sections March 15, 1997, Christian Schwarz, schwarz@debian.org
- Reworked/Restructured April-July 1997, Christian Schwarz, schwarz@debian.org
- Maintainer since 1997, Christian Schwarz, schwarz@debian.org
- Christoph Lameter contributed the "Web Standard"
- The debian-policy mailing list has taken responsibility for the
- contents of this document since September 1998, with the package
- maintainers responsible for packaging administrivia only.
- -->
<book>
<titlepag>
<title>Debian Policy Manual</title>
- <author>
- <name>Ian Jackson </name>
- <email>ijackson@gnu.ai.mit.edu</email>
- </author>
- <author>
- <name>Christian Schwarz</name>
- <email>schwarz@debian.org</email>
- </author>
- <author>
- <name>revised: David A. Morris</name>
- <email>bweaver@debian.org</email>
- </author>
- <author>
- <name>The Debian Policy mailing List</name>
- <email>debian-policy@lists.debian.org</email>
- </author>
+ <author><qref id="authors">The Debian Policy Mailing List</qref></author>
<version>version &version;, &date;</version>
<abstract>
This manual describes the policy requirements for the Debian
- GNU/Linux distribution. This includes the structure and
- contents of the Debian archive and several design issues of the
- operating system, as well as technical requirements that each
- package must satisfy to be included in the distribution. The
- policy package itself is maintained by a group of maintainers
- that have no editorial powers. At the moment, the list of
- maintainers is:
- <enumlist>
- <item>
- <p>Julian Gilbey <email>jdg@debian.org</email></p>
- </item>
- <item>
- <p>Manoj Srivastava <email>srivasta@debian.org</email></p>
- </item>
- </enumlist>
+ GNU/Linux distribution. This includes the structure and
+ contents of the Debian archive and several design issues of
+ the operating system, as well as technical requirements that
+ each package must satisfy to be included in the distribution.
</abstract>
-
<copyright>
<copyrightsummary>
- Copyright ©1996,1997,1998 Ian Jackson
+ Copyright © 1996,1997,1998 Ian Jackson
and Christian Schwarz.
</copyrightsummary>
<p>
<p>
A copy of the GNU General Public License is available as
- <tt>/usr/share/common-licenses/GPL</tt> in the Debian GNU/Linux
+ <file>/usr/share/common-licenses/GPL</file> in the Debian GNU/Linux
distribution or on the World Wide Web at
<url id="http://www.gnu.org/copyleft/gpl.html"
- name="The GNU General Public Licence">. You can also
+ 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.
</p>
</copyright>
</titlepag>
- <toc detail="sect">
+ <toc detail="sect1">
<chapt id="scope">
<heading>About this manual</heading>
distribution.
</p>
-
<p>
This manual also describes Debian policy as it relates to
creating Debian packages. It is not a tutorial on how to build
merely informative, and are not part of Debian policy itself.
</p>
+ <p>
+ The appendices to this manual are not necessarily normative,
+ either. Please see <ref id="pkg-scope"> for more information.
+ </p>
<p>
- In this manual, the words <em>must</em>, <em>should</em> and
+ In the normative part of this manual,
+ the words <em>must</em>, <em>should</em> and
<em>may</em>, and the adjectives <em>required</em>,
<em>recommended</em> and <em>optional</em>, are used to
distinguish the significance of the various guidelines in
only.
</p>
</sect>
+
<sect>
<heading>New versions of this document</heading>
+
<p>
- The current version of this document is always accessible
- from the Debian FTP server <ftpsite>ftp.debian.org</ftpsite>
- as
- <ftppath>/debian/doc/package-developer/policy.txt.gz</ftppath>
- (also available from the same directory are several other
- formats: <tt>policy.html.tar.gz</tt>, <tt>policy.pdf.gz</tt>
- and <tt>policy.ps.gz</tt>) or from the <url
- id="http://www.debian.org/doc/debian-policy/" name="Debian
- Policy Manual"> webpage.</p>
+ This manual is distributed via the Debian package
+ <package>debian-policy</package>.
+ </p>
<p>
- In addition, this manual is distributed via the Debian package
- <tt>debian-policy</tt>.
+ The current version of this document is also available from
+ the Debian web mirrors at
+ <tt><url name="/doc/debian-policy/"
+ id="http://www.debian.org/doc/debian-policy/"></tt>
+ and from the Debian archive mirrors at
+ <tt><url name="/doc/package-developer/policy.txt.gz"
+ id="http://ftp.debian.org/debian/doc/package-developer/policy.txt.gz"></tt>.
+ 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>.
</p>
<p>
- The <tt>debian-policy</tt> package also includes the file
- <tt>upgrading-checklist.txt</tt> which indicates policy
+ The <package>debian-policy</package> package also includes the file
+ <file>upgrading-checklist.txt</file> which indicates policy
changes between versions of this document.
</p>
</sect>
- <sect>
- <heading>Feedback</heading>
+
+ <sect id="authors">
+ <heading>Authors and Maintainers</heading>
<p>
- As the Debian GNU/Linux system is continuously evolving this
- manual does so too.
- </p>
+ Originally called "Debian GNU/Linux Policy Manual", this
+ manual was initially written in 1996 by Ian Jackson.
+ It was revised on November 27th, 1996 by David A. Morris.
+ Christian Schwarz added new sections on March 15th, 1997,
+ and reworked/restructured it in April-July 1997.
+ Christoph Lameter contributed the "Web Standard".
+ Julian Gilbey largely restructured it in 2001.
+ </p>
+
+ <p>
+ Since September 1998, the responsibility for the contents of
+ this document lies on the <url name="debian-policy mailing list"
+ id="mailto:debian-policy@lists.debian.org">. Proposals
+ are discussed there and inserted into policy after a certain
+ consensus is established.
+ <!-- insert shameless policy-process plug here eventually -->
+ The actual editing is done by a group of maintainers that have
+ no editorial powers. These are the current maintainers:
+
+ <enumlist>
+ <item>Julian Gilbey</item>
+ <item>Branden Robinson</item>
+ <item>Josip Rodin</item>
+ <item>Manoj Srivastava</item>
+ </enumlist>
+ </p>
+
<p>
While the authors of this document have tried hard to avoid
typos and other errors, these do still occur. If you discover
<email>debian-policy@lists.debian.org</email>, or submit a
bug report against the <tt>debian-policy</tt> package.
</p>
+
+ <p>
+ Please do not try to reach the individual authors or maintainers
+ of the Policy Manual regarding changes to the Policy.
+ </p>
</sect>
</chapt>
<heading>The Debian Free Software Guidelines</heading>
<p>
The Debian Free Software Guidelines (DFSG) form our
- definition of `free software'. These are:
+ definition of "free software". These are:
<taglist>
<tag>Free Redistribution
</tag>
<p>
The license may restrict source-code from being
distributed in modified form <em>only</em> if the
- license allows the distribution of ``patch files''
+ license allows the distribution of "patch files"
with the source code for the purpose of modifying the
program at build time. The license must explicitly
permit distribution of software built from modified
</tag>
<item>
<p>
- The ``GPL,'' ``BSD,'' and ``Artistic'' licenses are
- examples of licenses that we consider <em>free</em>.
+ The "GPL," "BSD," and "Artistic" licenses are examples of
+ licenses that we consider <em>free</em>.
</p>
</item>
</taglist>
<sect1>
<heading>The non-US sections</heading>
<p>
- Some programs with cryptographic program code need to be
- stored on the <em>non-US</em> server because of United
- States export restrictions. Such programs must be
- distributed in the appropriate <em>non-US</em> section,
- either <em>non-US/main</em>, <em>non-US/contrib</em> or
- <em>non-US/non-free</em>.
+ 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
+ restrictied 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>
- This applies only to packages which contain cryptographic
- code. A package containing a program with an interface to
- a cryptographic program or a program that's dynamically
- linked against a cryptographic library should not be
- distributed via the <em>non-US</em> server if it is
- capable of running without the cryptographic library or
- program.
+ 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>
<sect1>
<p>
Every package must be accompanied by a verbatim copy of
its copyright and distribution license in the file
- <tt>/usr/share/doc/<var>package</var>/copyright</tt>
+ <file>/usr/share/doc/<var>package</var>/copyright</file>
(see <ref id="copyrightfile"> for further details).
</p>
<p>
<email>debian-legal@lists.debian.org</email>. Be prepared
to provide us with the copyright statement. Software
covered by the GPL, public domain software and BSD-like
- copyrights are safe; be wary of the phrases `commercial
- use prohibited' and `distribution restricted'.
+ copyrights are safe; be wary of the phrases "commercial
+ use prohibited" and "distribution restricted".
</p>
</sect1>
<sect1>
Important programs, including those which one would
expect to find on any Unix-like system. If the
expectation is that an experienced Unix person who
- found it missing would say `What on earth is going on,
- where is <prgn>foo</prgn>?', it must be an
+ found it missing would say "What on earth is going on,
+ where is <prgn>foo</prgn>?", it must be an
<tt>important</tt> package.<footnote>
<p>
This is an important criterion because we are
These packages provide a reasonably small but not too
limited character-mode system. This is what will be
installed by default if the user doesn't select anything
- else. It doesn't include many large applications, but
- it does include Emacs (this is more of a piece of
- infrastructure than an application) and a reasonable
- subset of TeX and LaTeX.</p>
+ else. It doesn't include many large applications.</p>
</item>
<tag><tt>optional</tt></tag>
<item>
archive.</p>
<p>
- Package names must consist of lower case letters
+ Package names must consist only of lower case letters
(<tt>a-z</tt>), digits (<tt>0-9</tt>), plus (<tt>+</tt>)
and minus (<tt>-</tt>) signs, and periods (<tt>.</tt>).
- They must be at least two characters long and must contain
- at least one letter.
+ They must be at least two characters long and must start
+ with an alphanumeric character.
</p>
<p>
statements and other administrivia should not be included
either (that is what the copyright file is for).
</p>
+
+ <p>
+ Please refer to <ref id="descriptions"> for more information.
+ </p>
+
</sect1>
doing that has been reached.</p></sect1>
- <sect1>
+ <sect1 id="virtual_pkg">
<heading>Virtual packages</heading>
<p>
They should not use virtual package names (except privately,
amongst a cooperating group of packages) unless they have
been agreed upon and appear in the list of virtual package
- names.</p>
+ names. (See also <ref id="virtual">)</p>
<p>
The latest version of the authoritative list of virtual
- package names can be found on
- <ftpsite>ftp.debian.org</ftpsite> in
- <ftppath>/debian/doc/package-developer/virtual-package-names-list.txt</ftppath>
- or your local mirror. In addition, it is included in the
- <tt>debian-policy</tt> package. The procedure for updating
- the list is described at the top of the file.</p></sect1>
+ package names can be found in the <tt>debian-policy</tt> package.
+ It's 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>.
+ </p>
+ <p>
+ The procedure for updating the list is described in the preface
+ to the list.
+ </p>
+
+ </sect1>
<sect1>
- <heading>Base packages</heading>
+ <heading>Base system</heading>
<p>
- The packages included in the <tt>base</tt> section have a
- special function. They form a minimum subset of the Debian
+ 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
<tt>required</tt> or at least <tt>important</tt>, and many
of them will be tagged <tt>essential</tt> (see below).</p>
- <p>
- You must not place any packages into the <tt>base</tt>
- section before this has been discussed on the
- <tt>debian-devel</tt> mailing list and a consensus about
- doing that has been reached.</p></sect1>
+
+ </sect1>
<sect1>
reached.
</p>
</sect1>
+ <sect1>
+ <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>
+ </sect1>
<sect1 id="maintscripts">
- <heading>Maintainer scripts</heading>
+ <heading>Maintainer Scripts</heading>
<p>
The package installation scripts should avoid producing
</p>
<p>
- You should not use <tt>dpkg-divert</tt> on a file
+ You should not use <prgn>dpkg-divert</prgn> on a file
belonging to another package without consulting the
maintainer of that package first.
</p>
<heading>Prompting in maintainer scripts</heading>
<p>
Package maintainer scripts may prompt the user if
- necessary. Prompting may be accomplished by hand, or by
- communicating with a program, such as
- <prgn>debconf</prgn>, which conforms to the Debian
- Configuration management specification, version 2 or
- higher. These are included in the
+ necessary. Prompting may be accomplished by
+ hand<footnote>
+ <p>From the Jasrgon file: by hand 2. By extension,
+ writing code which does something in an explicit or
+ low-level way for which a presupplied library
+ (<em>debconf, in this instance</em>) routine ought
+ to have been available.</p>
+ </footnote> (but this is deprecated), or by
+ communicating though a program, which conforms to the
+ Debian Configuration management specification, version 2
+ or higher (such as <prgn>debconf</prgn>). Thiss
+ specification is included in the
<file>debconf_specification</file> files in the
- <package>debian-policy</package> package.
- You may also find this file on the FTP site
+ <package>debian-policy</package> package. You may also
+ find this file on the FTP site
<ftpsite>ftp.debian.org</ftpsite> in
<ftppath>/debian/doc/package-developer/debconf_specification.txt.gz</ftppath>
or on your local mirror.<footnote>
<p>
- 2.5% of Debian packages [see <url
- id="http://kitenet.net/programs/debconf/stats/"
+ 6% of Debian packages [see <url
+ id="http://auric.debian.org/%7Ejoeyh/debconf-stats/data/"
name="Debconf stats">] currently use
<package>debconf</package> to prompt the user at
install time, and this number is growing daily. The
<package>debconf</package>, plus the existance of a
nascent second implementation of the Debian
configuration management system
- (<package>cdebconf</package>), and the stabalization
+ (<package>cdebconf</package>), and the stabilization
of the protocol these things use, the time has
finally come to reflect the use of these things in
policy.
<p>
Packages which use the Debian Configuration management
specification may contain an additional
- <file>config</file> script and a <file>templates</file>
+ <prgn>config</prgn> script and a <tt>templates</tt>
file in their control archive. The <prgn>config</prgn>
script might be run before the <prgn>preinst</prgn>
script, and before the package is unpacked or any of its
- dependancies or pre-dependancies are satisfied.
+ dependencies or pre-dependancies are satisfied.
Therefore it must work using only the tools present in
<em>essential</em> packages.<footnote>
<p>
they need to do, and they should ensure that the user
will only ever be asked each question once. This means
that packages should try to use appropriate shared
- configuration files (such as <tt>/etc/papersize</tt> and
- <tt>/etc/news/server</tt>), and shared
+ configuration files (such as <file>/etc/papersize</file> and
+ <file>/etc/news/server</file>), and shared
<package>debconf</package> variables rather than each
prompting for their own list of required pieces of
information.
questions again, unless the user has used <tt>dpkg
--purge</tt> to remove the package's configuration. The
answers to configuration questions should be stored in an
- appropriate place in <tt>/etc</tt> so that the user can
+ appropriate place in <file>/etc</file> so that the user can
modify them, and how this has been done should be
documented.</p>
prompt the user to hit return to acknowledge the
message. Copyright messages do not count as vitally
important (they belong in
- <tt>/usr/share/doc/<var>package</var>/copyright</tt>);
+ <file>/usr/share/doc/<var>package</var>/copyright</file>);
neither do instructions on how to use a program (these
should be in on-line documentation, where all the users
can see them).</p>
four components may be specified.<footnote>
<p>
In the past, people specified the full version number
- in the Standards-Version field, for example `2.3.0.0'.
+ in the Standards-Version field, for example "2.3.0.0".
Since minor patch-level changes don't introduce new
policy, it was thought it would be better to relax
policy and only require the first 3 components to be
- specified, in this example `2.3.0'. All four
+ specified, in this example "2.3.0". All four
components may still be used if someone wishes to do
so.
</p>
<tt>Standards-Version</tt> source package field and
release it.<footnote>
<p>
- See the file <tt>upgrading-checklist</tt> for
+ See the file <file>upgrading-checklist</file> for
information about policy which has changed between
different versions of this document.
</p>
</sect1>
- <sect1>
+ <sect1 id="pkg-relations">
<heading>Package relationships</heading>
<p>
standard "Hello World!" program written in C or C++. The
required packages are called <em>build-essential</em>, and
an informational list can be found in
- <tt>/usr/share/doc/build-essential/list</tt> (which is
+ <file>/usr/share/doc/build-essential/list</file> (which is
contained in the <tt>build-essential</tt>
package).<footnote>
<p>Rationale:
<p>
Having a separate package allows one to install
the build-essential packages on a machine, as
- well as allowing other packages such as task
- packages to require installation of the
- build-essential packages using the depends
- relation.
+ well as allowing other packages such as tasks to
+ require installation of the build-essential
+ packages using the depends relation.
</p>
</item>
<item>
you should list all those packages, and <em>only</em>
those packages that <em>you</em> need directly. What
others need is their business. For example, if you
- only link against <tt>libimlib</tt>, you will need to
+ only link against <file>libimlib</file>, you will need to
build-depend on <package>libimlib2-dev</package> but
not against any <tt>libjpeg*</tt> packages, even
though <tt>libimlib2-dev</tt> currently depends on
are properly satisfied.
</p>
+ <p>
+ <ref id="relationships"> explains the technical details.
+ </p>
+
<sect1>
<heading>Changes to the upstream sources</heading>
or <tt>#define</tt>) and send the patch to the upstream
authors, with the default set to the way they originally
had it. You can then easily override the default in your
- <tt>debian/rules</tt> or wherever is appropriate.</p>
+ <file>debian/rules</file> or wherever is appropriate.</p>
<p>
You should make sure that the <prgn>configure</prgn> utility
<p>
If you need to edit a <prgn>Makefile</prgn> where
GNU-style <prgn>configure</prgn> scripts are used, you
- should edit the <tt>.in</tt> files rather than editing the
+ 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.</p></sect1>
-
-
- <sect1>
- <heading>Documenting your changes</heading>
+ someone else to later reconfigure the package.</p>
<p>
You should document your changes and updates to the source
- package properly in the <tt>debian/changelog</tt> file. (Note
- that mistakes in changelogs are usually best rectified by
- making a new changelog entry rather than "rewriting history"
- by editing old changelog entries.)</p>
-
- <p>
- In non-experimental packages you must use a format for
- <tt>debian/changelog</tt> which is supported by the most
- recent released version of <prgn>dpkg</prgn>.<footnote>
- <p>
- If you wish to use an alternative format, you may do
- so as long as you include a parser for it in your
- source package. The parser must have an API
- compatible with that expected by
- <prgn>dpkg-genchanges</prgn> and
- <prgn>dpkg-gencontrol</prgn>. If there is general
- interest in the new format, you should contact the
- <package>dpkg</package> maintainer to have the parser
- script for it included in the <prgn>dpkg</prgn>
- package. (You will need to agree that the parser and
- its manpage may be distributed under the GNU GPL, just
- as the rest of `dpkg' is.)
- </p>
- </footnote>
+ package properly in the <file>debian/changelog</file> file.
+ For more information, please see <ref id="changelogs">.
</p>
</sect1>
<p>
When <prgn>make</prgn> invokes a command in a makefile
(including your package's upstream makefiles and
- <tt>debian/rules</tt>), it does so using <tt>sh</tt>. This
- means that <tt>sh</tt>'s usual bad error handling
+ <file>debian/rules</file>), it does so using <prgn>sh</prgn>. This
+ means that <prgn>sh</prgn>'s usual bad error handling
properties apply: if you include a miniature script as one
of the commands in your makefile you'll find that if you
don't do anything about it then errors are not detected
data represented in a common format, known as <em>control
data</em>. The data is often stored in <em>control
files</em>. Binary and source packages have control files,
- and the <tt>.changes</tt> files which control the installation
+ and the <file>.changes</file> files which control the installation
of uploaded files are also in control file format.
- <prgn>Dpkg</prgn>'s internal databases are in a similar
+ <prgn>dpkg</prgn>'s internal databases are in a similar
format.
</p>
<p>
The name of the binary package. Package names consist of
- the alphanumerics and <tt>+</tt> <tt>-</tt> <tt>.</tt>
- (plus, minus and full stop).
+ lower case letters (<tt>a-z</tt>), digits (<tt>0-9</tt>),
+ plus (<tt>+</tt>) and minus (<tt>-</tt>) signs, and
+ periods (<tt>.</tt>).
</p>
<p>
They must be at least two characters long and must start
- with an alphanumeric character and not be all digits. The
- use of lowercase package names is strongly recommended
- unless the package you're building (or referring to, in
- other fields) is already using uppercase.</p>
+ with an alphanumeric character. The use of lowercase
+ package names is required unless the package you're
+ building (or referring to, in other fields) is already
+ using uppercase characters.</p>
</sect1>
<sect1 id="f-Version"><heading><tt>Version</tt>
</heading>
<p>
- In a <tt>.changes</tt> file or parsed changelog output
+ In a <file>.changes</file> file or parsed changelog output
this contains the (space-separated) name(s) of the
distribution(s) where this version of the package should
be installed. Valid distributions are determined by the
<tag><em>stable</em></tag>
<item>
<p>
- This is the current `released' version of Debian
+ This is the current "released" version of Debian
GNU/Linux. Once the distribution is
<em>stable</em> only security fixes and other
major bug fixes are allowed. When changes are
<item>
<p>
From time to time, the <em>testing</em>
- distribution enters a state of `code-freeze' in
+ distribution enters a state of "code-freeze" in
anticipation of release as a <em>stable</em>
version. During this period of testing only
fixes for existing or newly-discovered bugs will
<p>
The version number format is:
- [<var>epoch</var><tt>:</tt>]<var>upstream_version</var>[<tt>-</tt><var>debian_revision</var>]
+ [<var>epoch</var><tt>:</tt>]<var>upstream_version</var>[<tt>-</tt><var>debian_revision</var>]
</p>
<p>
<item>
<p>
This is the main part of the version number. It is
- usually the version number of the original (`upstream')
- package from which the <tt>.deb</tt> file has been made,
+ usually the version number of the original ("upstream")
+ package from which the <file>.deb</file> file has been made,
if this is applicable. Usually this will be in the same
format as that specified by the upstream author(s);
however, it may need to be reformatted to fit into the
<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 "debianization"
of it and therefore no revision indication is required.
</p>
<p>
However, in some cases where the upstream version number is
- based on a date (e.g., a development `snapshot' release) the
+ based on a date (e.g., a development "snapshot" release) the
package management system cannot handle these version
numbers without epochs. For example, dpkg will consider
- `96May01' to be greater than `96Dec24'.</p>
+ "96May01" to be greater than "96Dec24".</p>
<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
+ 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.</p>
<p>
Native Debian packages (i.e., packages which have been
written especially for Debian) whose version numbers include
- dates should always use the `YYYYMMDD' format.</p>
+ dates should always use the "YYYYMMDD" format.</p>
</sect>
</chapt>
</p>
</sect>
- <sect id="debianrules"><heading><tt>debian/rules</tt> - the
+ <sect id="debianrules"><heading><file>debian/rules</file> - the
main building script</heading>
<p>
</p>
<p>
- Since an interactive <tt>debian/rules</tt> script makes it
+ Since an interactive <file>debian/rules</file> script makes it
impossible to auto-compile that package and also makes it
hard for other people to reproduce the same binary
package, all <em>required targets</em> MUST be
<p>
The required and optional targets are as follows:
<taglist>
- <tag><tt>build</tt></tag>
+ <tag><tt>build</tt>, <tt>build-arch</tt> (optional),
+ <tt>build-indep</tt> (optional)</tag>
<item>
<p>
- This should perform all non-interactive configuration
- and compilation of the package. If a package has an
- interactive pre-build configuration routine, the
- Debianized source package must either be built after
- this has taken place (so that the binary package can
- be built without rerunning the configuration) or the
- configuration routine modified to become
- non-interactive. (The latter is preferable if there
- are architecture-specific features detected by the
- configuration routine.)
+ The <tt>build</tt> target should perform all
+ non-interactive configuration and compilation of the
+ package. If a package has an interactive pre-build
+ configuration routine, the Debianized source package
+ must either be built after this has taken place (so
+ that the binary package can be built without rerunning
+ the configuration) or the configuration routine
+ modified to become non-interactive. (The latter is
+ preferable if there are architecture-specific features
+ detected by the configuration routine.)
</p>
<p>
For some packages, notably ones where the same
source tree is compiled in different ways to produce
- two binary packages, the <prgn>build</prgn> target
+ two binary packages, the <tt>build</tt> target
does not make much sense. For these packages it is
good enough to provide two (or more) targets
(<tt>build-a</tt> and <tt>build-b</tt> or whatever)
for each of the ways of building the package, and a
- <prgn>build</prgn> target that does nothing. The
- <prgn>binary</prgn> target will have to build the
+ <tt>build</tt> target that does nothing. The
+ <tt>binary</tt> target will have to build the
package in each of the possible ways and make the
binary package out of each.
</p>
<p>
- The <prgn>build</prgn> target must not do anything
+ The <tt>build</tt> target must not do anything
that might require root privilege.
</p>
<p>
- The <prgn>build</prgn> target may need to run the
- <prgn>clean</prgn> target first - see below.
+ The <tt>build</tt> target may need to run the
+ <tt>clean</tt> target first - see below.
</p>
<p>
When a package has a configuration and build routine
which takes a long time, or when the makefiles are
- poorly designed, or when <prgn>build</prgn> needs to
- run <prgn>clean</prgn> first, it is a good idea to
+ poorly designed, or when <tt>build</tt> needs to
+ run <tt>clean</tt> first, it is a good idea to
<tt>touch build</tt> when the build process is
complete. This will ensure that if <tt>debian/rules
build</tt> is run again it will not rebuild the whole
program.<footnote>
<p>
- Another common way to do this is for <prgn>build</prgn>
+ Another common way to do this is for <tt>build</tt>
to depend on <prgn>build-stamp</prgn> and to do
nothing else, and for the <prgn>build-stamp</prgn>
target to do the building and to <tt>touch
build-stamp</tt> on completion. This is
especially useful if the build routine creates a
file or directory called <tt>build</tt>; in such a
- case, <prgn>build</prgn> will need to be listed as
+ case, <tt>build</tt> will need to be listed as
a phony target (i.e., as a dependency of the
<tt>.PHONY</tt> target). See the documentation of
<prgn>make</prgn> for more information on phony
</tag>
<item>
<p>
- The <prgn>binary</prgn> target must be all that is
+ The <tt>binary</tt> target must be all that is
necessary for the user to build the binary package(s)
produced from this source package. All of these
targets are required to be non-interactive. It is
split into two parts: <prgn>binary-arch</prgn> builds
the binary packages which are specific to a particular
- architecture, and <prgn>binary-indep</prgn> builds
+ architecture, and <tt>binary-indep</tt> builds
those which are not.
</p>
-
<p>
- <prgn>binary</prgn> may be (and commonly is) a target
- with no commands which simply depends on
- <prgn>binary-arch</prgn> and
- <prgn>binary-indep</prgn>.
+ <tt>binary</tt> may be (and commonly is) a target with
+ no commands which simply depends on
+ <tt>binary-arch</tt> and <tt>binary-indep</tt>.
</p>
-
<p>
- Each <prgn>binary-*</prgn> target should depend on
- the <prgn>build</prgn> target, above, so that the
- package is built if it has not been already. It
- should then create the relevant binary package(s),
- using <prgn>dpkg-gencontrol</prgn> to make their
- control files and <prgn>dpkg-deb</prgn> to build
- them and place them in the parent of the top level
- directory.
+ Both <tt>binary-*</tt> targets should depend on the
+ <tt>build</tt> target, or on the appropriate
+ <tt>build-arch</tt> or <tt>build-indep</tt> target, if
+ provided, so that the package is built if it has not
+ been already. It should then create the relevant
+ binary package(s), using <prgn>dpkg-gencontrol</prgn> to
+ make their control files and <prgn>dpkg-deb</prgn> to
+ build them and place them in the parent of the top
+ level directory.
</p>
<p>
- Both the <prgn>binary-arch</prgn> and
- <prgn>binary-indep</prgn> targets <em>must</em> exist.
+ Both the <tt>binary-arch</tt> and
+ <tt>binary-indep</tt> targets <em>must</em> exist.
If one of them has nothing to do (which will always be
the case if the source generates only a single binary
package, whether architecture-dependent or not), it
</p>
<p>
- The <prgn>binary</prgn> targets must be invoked as
+ The <tt>binary</tt> targets must be invoked as
root.<footnote>
<p>
The <prgn>fakeroot</prgn> package often allows one
<tag><tt>clean</tt></tag>
<item>
<p>
- This must undo any effects that the <prgn>build</prgn>
- and <prgn>binary</prgn> targets may have had, except
+ This must undo any effects that the <tt>build</tt>
+ and <tt>binary</tt> targets may have had, except
that it should leave alone any output files created in
- the parent directory by a run of a <prgn>binary</prgn>
+ the parent directory by a run of a <tt>binary</tt>
target. This target must be non-interactive.
</p>
<p>
- If a <prgn>build</prgn> file is touched at the end of
- the <prgn>build</prgn> target, as suggested above, it
+ If a <tt>build</tt> file is touched at the end of
+ the <tt>build</tt> target, as suggested above, it
should be removed as the first action that
- <prgn>clean</prgn> performs, so that running
- <prgn>build</prgn> again after an interrupted
- <prgn>clean</prgn> doesn't think that everything is
+ <tt>clean</tt> performs, so that running
+ <tt>build</tt> again after an interrupted
+ <tt>clean</tt> doesn't think that everything is
already done.
</p>
<p>
- The <prgn>clean</prgn> target may need to be
- invoked as root if <prgn>binary</prgn> has been
- invoked since the last <prgn>clean</prgn>, or if
- <prgn>build</prgn> has been invoked as root (since
- <prgn>build</prgn> may create directories, for
+ The <tt>clean</tt> target may need to be
+ invoked as root if <tt>binary</tt> has been
+ invoked since the last <tt>clean</tt>, or if
+ <tt>build</tt> has been invoked as root (since
+ <tt>build</tt> may create directories, for
example).
</p>
</item>
</taglist>
<p>
- The <prgn>build</prgn>, <prgn>binary</prgn> and
- <prgn>clean</prgn> targets must be invoked with the current
+ The <tt>build</tt>, <tt>binary</tt> and
+ <tt>clean</tt> targets must be invoked with the current
directory being the package's top-level directory.
</p>
<p>
- Additional targets may exist in <tt>debian/rules</tt>,
+ Additional targets may exist in <file>debian/rules</file>,
either as published or undocumented interfaces or for the
package's internal use.
</p>
</p>
</sect>
- <sect id="dpkgchangelog"><heading><tt>debian/changelog</tt>
+ <sect id="dpkgchangelog"><heading><file>debian/changelog</file>
</heading>
<p>
That format is a series of entries like this:
<example compact="compact">
<var>package</var> (<var>version</var>) <var>distribution(s)</var>; urgency=<var>urgency</var>
-
+ <comment>
+ <p>[optional blank line(s), stripped]</p>
+ </comment>
* <var>change details</var>
<var>more change details</var>
+ <comment>
+ <p>[blank line(s), included in output of dpkg-parsechangelog]</p>
+ </comment>
* <var>even more change details</var>
-
- -- <var>maintainer name</var> <<var>email address</var>> <var>date</var>
+ <comment>
+ <p>[optional blank line(s), stripped]</p>
+ </comment>
+ -- <var>maintainer name</var> <<var>email
+ address</var>><var>[two spaces]</var> <var>date</var>
</example>
</p>
<var>distribution(s)</var> lists the distributions where
this version should be installed when it is uploaded - it
is copied to the <tt>Distribution</tt> field in the
- <tt>.changes</tt> file. See <ref id="f-Distribution">.
+ <file>.changes</file> file. See <ref id="f-Distribution">.
</p>
<p>
<var>urgency</var> is the value for the <tt>Urgency</tt>
- field in the <tt>.changes</tt> file for the upload. It is
+ field in the <file>.changes</file> file for the upload. It is
not possible to specify an urgency containing commas; commas
are used to separate
<tt><var>keyword</var>=<var>value</var></tt> settings in the
currently only one useful <var>keyword</var>,
<tt>urgency</tt>).<footnote>
<p>
- Usual urgency values are <tt>low</tt>, <tt>medium</tt>,
- <tt>high</tt> and <tt>critical</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.
+ 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.
</p>
</footnote>
</p>
</p>
<p>
- The first `title' line with the package name should start
- at the left hand margin; the `trailer' line with the
+ The first "title" line with the package name should start
+ at the left hand margin; the "trailer" line with the
maintainer and date details should be preceded by exactly
one space. The maintainer details and the date must be
separated by exactly two spaces.
</sect1>
</sect>
- <sect id="srcsubstvars"><heading><tt>debian/substvars</tt>
+<!-- FIXME: section pkg-srcsubstvars is the same as srcsubstvars -->
+
+ <sect id="srcsubstvars"><heading><file>debian/substvars</file>
and variable substitutions </heading>
<p>
generate control files they perform variable substitutions
on their output just before writing it. Variable
substitutions have the form <tt>${<var>variable</var>}</tt>.
- The optional file <tt>debian/substvars</tt> contains
+ The optional file <file>debian/substvars</file> contains
variable substitutions to be used; variables can also be set
- directly from <tt>debian/rules</tt> using the <tt>-V</tt>
+ directly from <file>debian/rules</file> using the <tt>-V</tt>
option to the source packaging commands, and certain
predefined variables are also available.
</p>
<p>
- The <tt>debian/substvars</tt> file is usually generated and
- modified dynamically by <tt>debian/rules</tt> targets; in
- this case it must be removed by the <prgn>clean</prgn>
- target.
+ The <file>debian/substvars</file> file is usually generated and
+ modified dynamically by <file>debian/rules</file> targets, in
+ which case it must be removed by the <tt>clean</tt> target.
</p>
<p>
See <manref name="dpkg-source" section="1"> for full
details about source variable substitutions, including the
- format of <tt>debian/substvars</tt>.</p>
+ format of <file>debian/substvars</file>.</p>
</sect>
- <sect id="debianfiles"><heading><tt>debian/files</tt>
+ <sect id="debianfiles"><heading><file>debian/files</file>
</heading>
<p>
This file is not a permanent part of the source tree; it
is used while building packages to record which files are
being generated. <prgn>dpkg-genchanges</prgn> uses it
- when it generates a <tt>.changes</tt> file.
+ when it generates a <file>.changes</file> file.
</p>
<p>
It should not exist in a shipped source package, and so it
(and any backup files or temporary files such as
- <tt>files.new</tt><footnote>
+ <file>files.new</file><footnote>
<p>
- <tt>files.new</tt> is used as a temporary file by
+ <file>files.new</file> is used as a temporary file by
<prgn>dpkg-gencontrol</prgn> and
<prgn>dpkg-distaddfile</prgn> - they write a new
version of <tt>files</tt> here before renaming it,
occurs
</p>
</footnote>) should be removed by the
- <prgn>clean</prgn> target. It may also be wise to
+ <tt>clean</tt> target. It may also be wise to
ensure a fresh start by emptying or removing it at the
- start of the <prgn>binary</prgn> target.
+ start of the <tt>binary</tt> target.
</p>
<p>
When <prgn>dpkg-gencontrol</prgn> is run for a binary
- package, it adds an entry to <tt>debian/files</tt> for the
- <tt>.deb</tt> file that will be created when <tt>dpkg-deb
+ package, it adds an entry to <file>debian/files</file> for the
+ <file>.deb</file> file that will be created when <tt>dpkg-deb
--build</tt> is run for that binary package. So for most
packages all that needs to be done with this file is to
- delete it in the <prgn>clean</prgn> target.
+ delete it in the <tt>clean</tt> target.
</p>
<p>
made with <prgn>dpkg-gencontrol</prgn> then they should be
placed in the parent of the package's top-level directory
and <prgn>dpkg-distaddfile</prgn> should be called to add
- the file to the list in <tt>debian/files</tt>.</p>
+ the file to the list in <file>debian/files</file>.</p>
</sect>
<sect id="restrictions"><heading>Restrictions on objects in source packages
</footnote>
</p>
</sect>
+
<sect id="descriptions"><heading>Descriptions of packages - the
- <tt>Description</tt> field </heading>
+ <tt>Description</tt> field</heading>
+
+ <p>
+ The "Description" control file field consists of two parts,
+ the synopsis or the short description, and the long description.
+ The field's format is as follows:
+ </p>
+
+ <p><example>
+ Description: <single line synopsis>
+ <extended description over several lines>
+</example></p>
<p>
The description is intended to describe the program to a user
conflicts have been declared.
</p>
- <sect1><heading>Notes about writing descriptions
- </heading>
+ <p>
+ Put important information first, both in the synopsis and
+ extended description. Sometimes only the first part of the
+ synopsis or of the description will be displayed. You can
+ assume that there will usually be a way to see the whole
+ extended description.
+ </p>
+
+ <sect1 id="synopsis"><heading>The single line synopsis</heading>
<p>
The single line synopsis should be kept brief - certainly
informative as you can.
</p>
+ </sect1>
+
+ <sect1 id="extendeddesc"><heading>The extended description</heading>
+
<p>
Do not try to continue the single line synopsis into the
extended description. This will not work correctly when
The description field needs to make sense to anyone, even
people who have no idea about any of the things the
package deals with.<footnote>
- <p>
The blurb that comes with a program in its
announcements and/or <prgn>README</prgn> files is
rarely suitable for use in a description. It is
usually aimed at people who are already in the
community where the package is used.
- </p>
</footnote>
</p>
<p>
- Put important information first, both in the synopsis and
- extended description. Sometimes only the first part of the
- synopsis or of the description will be displayed. You can
- assume that there will usually be a way to see the whole
- extended description.
+ The lines in the extended description can have these formats:
</p>
- <p>
- You may include information about dependencies and so forth
- in the extended description, if you wish.
- </p>
+ <p><list>
+
+ <item>
+ Those starting with a single space are part of a paragraph.
+ Successive lines of this form will be word-wrapped when
+ displayed. The leading space will usually be stripped off.
+ </item>
+
+ <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"
+ (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
+ deleted from each line will be the same (so that you can have
+ indenting work correctly, for example).
+ </item>
+
+ <item>
+ Those containing a single space followed by a single full stop
+ character. These are rendered as blank lines. This is the
+ <em>only</em> way to get a blank line<footnote>
+ Completely empty lines will not be rendered as blank lines.
+ Instead, they will cause the parser to think you're starting
+ a whole new record in the control file, and will therefore
+ likely abort with an error.
+ </footnote>.
+ </item>
+
+ <item>
+ Those containing a space, a full stop and some more characters.
+ These are for future expansion. Do not use them.
+ </item>
+
+ </list></p>
<p>
Do not use tab characters. Their effect is not predictable.
</p>
</sect1>
+
</sect>
+
</chapt>
aborted half way through for some reason, the second call
should merely do the things that were left undone the first
time, if any, and exit with a success status if everything
- is OK.<footnote>
+ is OK.<footnote>
<p>
This is so that if an error occurs, the user interrupts
<prgn>dpkg</prgn> or some other unforeseen circumstance
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 <tt>/dev/tty</tt>, since
+ 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
case, if a major error occurs (unless listed below) the
actions are, in general, run backwards - this means that the
maintainer scripts are run with different arguments in
- reverse order. These are the `error unwind' calls listed
+ reverse order. These are the "error unwind" calls listed
below.
<enumlist>
</p>
</item>
<item>
- <p>If a `conflicting' package is being removed at the same time:
+ <p>If a "conflicting" package is being removed at the same time:
<enumlist>
<item>
<p>
<p>
Otherwise, if the package had some configuration
files from a previous version installed (i.e., it
- is in the `configuration files only' state):
+ is in the "configuration files only" state):
<example compact="compact">
<var>new-preinst</var> install <var>old-version</var>
</example></p>
Packages which overwrite each other's files produce
behavior which, though deterministic, is hard for the
system administrator to understand. It can easily
- lead to `missing' programs if, for example, a package
+ lead to "missing" programs if, for example, a package
is installed which overwrites a file from another
package, and is then removed again.<footnote>
<p>
Any files in the package we're unpacking that are also
listed in the file lists of other packages are removed
from those lists. (This will lobotomize the file list
- of the `conflicting' package if there is one.)
+ of the "conflicting" package if there is one.)
</p>
</item>
<item>
<item>
<p>
The new package's status is now sane, and recorded as
- `unpacked'.
+ "unpacked".
</p>
<p>
<chapt id="relationships"><heading>Declaring relationships between
packages</heading>
- <p>
- Packages can declare in their control file that they have
- certain relationships to other packages - for example, that
- they may not be installed at the same time as certain other
- packages, and/or that they depend on the presence of others,
- or that they should overwrite files in certain other packages
- if present.
- </p>
-
- <p>
- This is done using the <tt>Depends</tt>, <tt>Pre-Depends</tt>,
- <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
- <tt>Conflicts</tt>, <tt>Provides</tt> and <tt>Replaces</tt>
- control file fields.
- </p>
-
- <p>
- Source packages may declare relationships to binary packages,
- saying that they require certain binary packages to be
- installed or absent at the time of building the package.
- </p>
-
- <p>
- This is done using the <tt>Build-Depends</tt>,
- <tt>Build-Depends-Indep</tt>, <tt>Build-Conflicts</tt> and
- <tt>Build-Conflicts-Indep</tt> control file fields.
- </p>
-
<sect id="depsyntax"><heading>Syntax of relationship fields
</heading>
<tt>Pre-Depends</tt>
</heading>
+ <p>
+ Packages can declare in their control file that they have
+ certain relationships to other packages - for example, that
+ they may not be installed at the same time as certain other
+ packages, and/or that they depend on the presence of others.
+ </p>
+
+ <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.
+ </p>
+
<p>
- These five fields are used to declare a dependency
+ These six 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
<p>
A <tt>Conflicts</tt> entry should almost never have an
- `earlier than' version clause. This would prevent
+ "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.
</heading>
<p>
- As well as the names of actual (`concrete') packages, the
+ 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>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
<tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>
- may mention `virtual packages'.
+ may mention "virtual packages".
</p>
<p>
<tt>Provides</tt> control file field of another package.
The effect is as if the package(s) which provide a
particular virtual package name had been listed by name
- everywhere the virtual package name appears.
+ everywhere the virtual package name appears. (See also <ref
+ id="virtual_pkg">)
</p>
<p>
- If there are both a real and a virtual package of the same
- name then the dependency may be satisfied (or the conflict
- caused) by either the real package or any of the virtual
- packages which provide it. This is so that, for example,
- supposing we have
+ If there are both concrete and virtual packages of the same
+ name, then the dependency may be satisfied (or the conflict
+ caused) by either the concrete package with the name in
+ question or any other concrete package which provides the
+ virtual package with the name in question. This is so that,
+ for example, supposing we have
<example compact="compact">
Package: foo
Depends: bar
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.
+ 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
packages - <tt>Replaces</tt></heading>
<p>
- The <tt>Replaces</tt> control file field has two distinct
- purposes, which come into play in different situations.
+ Packages can declare in their control file that they should
+ overwrite files in certain other packages, or completely
+ replace other packages. The <tt>Replaces</tt> control file
+ field has these two distinct purposes.
</p>
<sect1><heading>Overwriting files in other packages</heading>
<tt>Replaces</tt> the one containing the file being
overwritten, then <prgn>dpkg</prgn> will replace the file
from the old package with that from the new. The file
- will no longer be listed as `owned' by the old package.
+ will no longer be listed as "owned" by the old package.
</p>
<p>
If a package is completely replaced in this way, so that
<prgn>dpkg</prgn> does not know of any files it still
- contains, it is considered to have `disappeared'. It will
+ contains, it is considered to have "disappeared". It will
be marked as not wanted on the system (selected for
removal) and not installed. Any <tt>conffile</tt>s
details noted for the package will be ignored, as they
<tt>Build-Conflicts</tt>, <tt>Build-Conflicts-Indep</tt>
</heading>
+ <p>
+ Source packages that require certain binary packages to be
+ installed or absent at the time of building the package
+ can declare relationships to those binary packages.
+ </p>
+
+ <p>
+ This is done using the <tt>Build-Depends</tt>,
+ <tt>Build-Depends-Indep</tt>, <tt>Build-Conflicts</tt> and
+ <tt>Build-Conflicts-Indep</tt> control file fields.
+ </p>
+
<p>
- A source package may declare a dependency or a conflict on a
- binary package, indicating which packages are required to be
- present on the system in order to build the binary packages
- from the source package. This is done with the control file
- fields <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
- <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>.
+ Build-dependencies on "build-essential" binary packages can be
+ omitted. Please see <ref id="pkg-relations"> for more information.
+ </p>
+
+ <p>
The dependencies and conflicts they define must be satisfied
(as defined earlier for binary packages) in order to invoke
- the targets in <tt>debian/rules</tt>, as follows:
+ the targets in <tt>debian/rules</tt>, as follows:<footnote>
+ <p>
+ If you make "build-arch" or "binary-arch", you need
+ Build-Depends. If you make "build-indep" or
+ "binary-indep", you need Build-Depends and
+ Build-Depends-Indep. If you make "build" or "binary",
+ 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.
+ </p>
+ <p>
+ The purpose of the original split, I recall, was so that
+ the autobuilders wouldn't need to install extra packages
+ needed only for the binary-indep targets. But without a
+ build-arch/build-indep split, this didn't work, since
+ most of the work is done in the build target, not in the
+ binary target.
+ </p>
+ </footnote>
<taglist>
<tag><tt>Build-Depends</tt>, <tt>Build-Conflicts</tt></tag>
The <tt>Build-Depends</tt> and
<tt>Build-Conflicts</tt> fields must be satisfied when
any of the following targets is invoked:
- <tt>build</tt>, <tt>binary</tt>, <tt>binary-arch</tt>
- and <tt>binary-indep</tt>.
+ <tt>build</tt>, <tt>clean</tt>, <tt>binary</tt>,
+ <tt>binary-arch</tt>, <tt>build-arch</tt>,
+ <tt>build-indep</tt> and <tt>binary-indep</tt>.
</p>
</item>
- <tag><tt>Build-Depends-Indep</tt>, <tt>Build-Conflicts-Indep</tt></tag>
+ <tag><tt>Build-Depends-Indep</tt>,
+ <tt>Build-Conflicts-Indep</tt></tag>
<item>
<p>
The <tt>Build-Depends-Indep</tt> and
<tt>Build-Conflicts-Indep</tt> fields must be
satisfied when any of the following targets is
- invoked: <tt>binary</tt> and <tt>binary-indep</tt>.
+ invoked: <tt>build</tt>, <tt>clean</tt>,
+ <tt>build-indep</tt>, <tt>binary</tt> and
+ <tt>binary-indep</tt>.
</p>
</item>
</taglist>
</heading>
<p>
- This chapter has been superseded by <ref id="config files">.
+ This chapter has been superseded by <ref id="config-files">.
</p>
</p>
<p>
- Firstly, the package should install the shared libraries under
- their normal names. For example, the <tt>libgdbmg1</tt>
- package should install <tt>libgdbm.so.1.7.3</tt> as
- <tt>/usr/lib/libgdbm.so.1.7.3</tt>. The files should not be
+ Packages involving shared libraries should be split up into
+ several binary packages. This section mostly deals with how
+ this separation is to be accomplished; rules for files within
+ the shared library packages are in <ref id="libraries"> instead.
+ </p>
+
+ <sect id="sharedlibs-runtime">
+ <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>
+ <p>
+ 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
+ program. For example, if the soname of the library is
+ <file>libfoo.so.6</file>, the library package would be
+ called <file>libfoo6</file>.
+ </p>
+ </footnote>.
+ Alternatively, if it would be confusing to directly append
+ <var>soversion</var> to <var>libraryname</var> (e.g. because
+ <var>libraryname</var> itself ends in a number), you may use
+ <package><var>libraryname</var>-<var>soversion</var></package> and
+ <package><var>libraryname</var>-<var>soversion</var>-dev</package>
+ instead.
+ </p>
+
+ <p>
+ If you have several shared libraries built from the same
+ source tree you may lump them all together into a single
+ shared library package, provided that you change all of
+ their sonames at once (so that you don't get filename
+ clashes if you try to install different versions of the
+ combined shared libraries package).
+ </p>
+
+ <p>
+ The package should install the shared libraries under
+ their normal names. For example, the <package>libgdbmg1</package>
+ package should install <file>libgdbm.so.1.7.3</file> as
+ <file>/usr/lib/libgdbm.so.1.7.3</file>. The files should not be
renamed or re-linked by any <prgn>prerm</prgn> or
<prgn>postrm</prgn> scripts; <prgn>dpkg</prgn> will take care
of renaming things safely without affecting running programs,
</p>
<p>
- Secondly, the package should include the symbolic link that
+ Shared libraries should not be installed executable, since
+ the dynamic linker does not require this and trying to
+ execute a shared library usually results in a core dump.
+ </p>
+
+ <p>
+ The run-time library package should include the symbolic link that
<prgn>ldconfig</prgn> would create for the shared libraries.
- For example, the <prgn>libgdbmg1</prgn> package should include
- a symbolic link from <tt>/usr/lib/libgdbm.so.1</tt> to
- <tt>libgdbm.so.1.7.3</tt>. This is needed so that the dynamic
+ For example, the <package>libgdbmg1</package> package should include
+ a symbolic link from <file>/usr/lib/libgdbm.so.1</file> to
+ <file>libgdbm.so.1.7.3</file>. This is needed so that the dynamic
linker (for example <prgn>ld.so</prgn> or
<prgn>ld-linux.so.*</prgn>) can find the library between the
time that <prgn>dpkg</prgn> installs it and the time that
<p>
The package management system requires the library to be
placed before the symbolic link pointing to it in the
- <tt>.deb</tt> file. This is so that when
+ <file>.deb</file> file. This is so that when
<prgn>dpkg</prgn> comes to install the symlink
(overwriting the previous symlink pointing at an older
version of the library), the new shared library is already
library in the temporary packaging directory before
creating the symlink. Unfortunately, this was not always
effective, since the building of the tar file in the
- <tt>.deb</tt> depended on the behavior of the underlying
+ <file>.deb</file> depended on the behavior of the underlying
file system. Some file systems (such as reiserfs) reorder
the files so that the order of creation is forgotten.
- S
tarting with release <tt>1.7.0</tt>, <prgn>dpkg</prgn>
- will reorder the files itself as necessary when building a
+ S
ince version 1.7.0, <prgn>dpkg</prgn>
+ reorders the files itself as necessary when building a
package. Thus it is no longer important to concern
oneself with the order of file creation.
</p>
</footnote>
</p>
- <p>
- Thirdly, the associated development package should contain a
- symlink for the shared library without a version number. For
- example, the <tt>libgdbmg1-dev</tt> package should include a
- symlink from <tt>/usr/lib/libgdbm.so</tt> to
- <tt>libgdbm.so.1.7.3</tt>. This symlink is needed by the
- linker (<prgn>ld</prgn>) when compiling packages, as it will
- only look for <tt>libgdbm.so</tt> when compiling dynamically.
- </p>
+ <sect1 id="ldconfig">
+ <heading><tt>ldconfig</tt></heading>
<p>
Any package installing shared libraries in one of the default
library directories of the dynamic linker (which are currently
- <tt>/usr/lib</tt> and <tt>/lib</tt>) or a directory that is
- listed in <tt>/etc/ld.so.conf</tt><footnote>
+ <file>/usr/lib</file> and <file>/lib</file>) or a directory that is
+ listed in <file>/etc/ld.so.conf</file><footnote>
<p>
These are currently
<list compact="compact">
</list>
</p>
</footnote>
- must call <prgn>ldconfig</prgn> in its <prgn>postinst</prgn>
- script if the first argument is <tt>configure</tt> and should
- call it in the <prgn>postrm</prgn> script if the first
- argument is <tt>remove</tt>.
+ must use <prgn>ldconfig</prgn> to update the shared library
+ system.
+ </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>
+ <p>During install or upgrade, the preinst is called before
+ the new files are installed, so calling "ldconfig" is
+ pointless. The preinst of an existing package can also be
+ called if an upgrade fails. However, this happens during
+ the critical time when a shared libs may exist on-disk
+ under a temporary name. Thus, it is dangerous and
+ forbidden by current policy to call "ldconfig" at this
+ time.
+ </p>
+ <p>When a package is installed or upgraded, "postinst
+ configure" runs after the new files are safely on-disk.
+ Since it is perfectly safe to invoke ldconfig
+ unconditionally in a postinst, it is OK for a package to
+ simply put ldconfig in its postinst without checking the
+ argument. The postinst can also be called to recover from
+ a failed upgrade. This happens before any new files are
+ unpacked, so there is no reason to call "ldconfig" at this
+ point.
+ </p>
+ <p>For a package that is being removed, prerm is
+ called with all the files intact, so calling ldconfig is
+ useless. The other calls to "prerm" happen in the case of
+ upgrade at a time when all the files of the old package
+ are on-disk, so again calling "ldconfig" is pointless.
+ </p>
+ <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.
+ </p>
+ </footnote>
</p>
+ </sect1>
+
+ </sect>
+
+ <sect id="sharedlibs-runtime-progs">
+ <heading>Run-time support programs</heading>
<p>
- However, <prgn>postrm</prgn> and <prgn>preinst</prgn> scripts
- <em>must not</em> call <prgn>ldconfig</prgn> in the case where
- the package is being upgraded (see <ref id="unpackphase"> for
- details), as <prgn>ldconfig</prgn> will see the temporary
- names that <prgn>dpkg</prgn> uses for the files while it is
- installing them and will make the shared library links point
- to them, just before <prgn>dpkg</prgn> continues the
- installation and renames the temporary files!
+ If your package has some run-time support programs which use
+ the shared library you must not put them in the shared
+ library package. If you do that then you won't be able to
+ install several versions of the shared library without
+ getting filename clashes.
</p>
- <sect>
- <heading>Handling shared library dependencies - the
- <tt>shlibs</tt> system</heading>
+ <p>
+ Instead, either create another package for the runtime binaries
+ (this package might typically be named
+ <package><var>libraryname</var>-runtime</package>; note the absence
+ of the <var>soversion</var> in the package name), or if the
+ development package is small, include them in there.
+ </p>
+ </sect>
+
+ <sect id="sharedlibs-static">
+ <heading>Static libraries</heading>
+
+ <p>
+ The static library (<file><var>libraryname.a</var></file>)
+ is usually provided in addition to the shared version.
+ It is placed into the development package (see below).
+ </p>
+
+ <p>
+ In some cases, it is acceptable for a library to be
+ available in static form only; these cases include:
+ <list>
+ <item>libraries for languages whose shared library support
+ is immature or unstable</item>
+ <item>libraries whose interfaces are in flux or under
+ development (commonly the case when the library's
+ major version number is zero, or where the ABI breaks
+ across patchlevels)</item>
+ <item>libraries which are explicitly intended to be
+ available only in static form by their upstream
+ author(s)</item>
+ </list>
+ </p>
+
+ <sect id="sharedlibs-dev">
+ <heading>Development files</heading>
+
+ <p>
+ The development files associated to a shared library need to be
+ placed in a package called
+ <package><var>libraryname</var><var>soversion</var>-dev</package>,
+ or if you prefer only to support one development version at a
+ time, <package><var>libraryname</var>-dev</package>.
+ </p>
+
+ <p>
+ In case several development versions of a library exist, you may
+ need to use <prgn>dpkg</prgn>'s Conflicts mechanism (see
+ <ref id="conflicts">) to ensure that the user only installs one
+ development version at a time (as different development versions are
+ likely to have the same header files in them, which would cause a
+ filename clash if both were installed).
+ </p>
+
+ <p>
+ The development package should contain a symlink for the associated
+ shared library without a version number. For example, the
+ <package>libgdbmg1-dev</package> package should include a symlink
+ from <file>/usr/lib/libgdbm.so</file> to
+ <file>libgdbm.so.1.7.3</file>. This symlink is needed by the linker
+ (<prgn>ld</prgn>) when compiling packages, as it will only look for
+ <file>libgdbm.so</file> when compiling dynamically.
+ </p>
+ </sect>
+
+ <sect id="sharedlibs-intradeps">
+ <heading>Dependencies between the packages of the same library</heading>
+
+ <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
+ useful for this purpose.
+ </p>
+ </sect>
+
+ <sect id="sharedlibs-shlibdeps">
+ <heading>Dependencies between the library and other packages -
+ the <tt>shlibs</tt> system</heading>
<p>
If a package contains a binary or library which links to a
<em>uses</em> a shared library uses this information to
determine the dependencies it requires. The files which
contain the mapping from shared libraries to the necessary
- dependency information are called <tt>shlibs</tt> files.
+ dependency information are called <file>shlibs</file> files.
</p>
<p>
Thus, when a package is built which contains any shared
- libraries, it must provide a <tt>shlibs</tt> file for other
+ libraries, it must provide a <file>shlibs</file> file for other
packages to use, and when a package is built which contains
any shared libraries or compiled binaries, it must run
<prgn>dpkg-shlibdeps</prgn> on these to determine the
<p>
In the past, the shared libraries linked to were
determined by calling <prgn>ldd</prgn>, but now
- <prgn>objdump</prgn> to do this. The only change this
- makes to package building is that
+ <prgn>objdump</prgn> is used to do this. The only
+ change this makes to package building is that
<prgn>dpkg-shlibdeps</prgn> must also be run on shared
libraries, whereas in the past this was unnecessary.
The rest of this footnote explains the advantage that
libraries that are needed by <tt>libbar</tt> are linked
<em>indirectly</em> to <tt>foo</tt>, and the dynamic
linker will load them automatically when it loads
- <tt>libbar</tt>. A package should needs to depend on
+ <tt>libbar</tt>. A package should depend on
the libraries it directly uses, and the dependencies for
those libraries should automatically pull in the other
libraries.
<tt>shlibs</tt> file format and how to create them if your
package contains a shared library.
</p>
- </sect>
- <sect><heading>The <tt>shlibs</tt> files present on the system
- </heading>
+ <sect1>
+ <heading>The <tt>shlibs</tt> files present on the system</heading>
<p>
There are several places where <tt>shlibs</tt> files are
<p>
<list>
<item>
- <p><tt>debian/shlibs.local</tt></p>
+ <p><file>debian/shlibs.local</file></p>
<p>
This lists overrides for this package. Its use is
described below (see <ref id="shlibslocal">).
</item>
<item>
- <p><tt>/etc/dpkg/shlibs.override</tt></p>
+ <p><file>/etc/dpkg/shlibs.override</file></p>
<p>
This lists global overrides. This list is normally
empty. It is maintained by the local system
</item>
<item>
- <p><tt>DEBIAN/shlibs</tt> files in the `build directory'</p>
+ <p><file>DEBIAN/shlibs</file> files in the "build directory"</p>
<p>
When packages are being built, any
- <tt>debian/shlibs</tt> files are copied into the
+ <file>debian/shlibs</file> files are copied into the
control file area of the temporary build directory and
- given the name <tt>shlibs</tt>. These files give
+ given the name <file>shlibs</file>. These files give
details of any shared libraries included in the
package.<footnote>
<p>
packages, <tt>libfoo2</tt> and
<tt>foo-runtime</tt>. When building the binary
packages, the two packages are created in the
- directories <tt>debian/libfoo2</tt> and
- <tt>debian/foo-runtime</tt> respectively.
- (<tt>debian/tmp</tt> could be used instead of one
+ directories <file>debian/libfoo2</file> and
+ <file>debian/foo-runtime</file> respectively.
+ (<file>debian/tmp</file> could be used instead of one
of these.) Since <tt>libfoo2</tt> provides the
<tt>libfoo</tt> shared library, it will require a
<tt>shlibs</tt> file, which will be installed in
- <tt>debian/libfoo2/DEBIAN/shlibs</tt>, eventually
+ <file>debian/libfoo2/DEBIAN/shlibs</file>, eventually
to become
- <tt>/var/lib/dpkg/info/libfoo2.shlibs</tt>. Then
+ <file>/var/lib/dpkg/info/libfoo2.shlibs</file>. Then
when <prgn>dpkg-shlibdeps</prgn> is run on the
executable
- <tt>debian/foo-runtime/usr/bin/foo-prog</tt>, it
+ <file>debian/foo-runtime/usr/bin/foo-prog</file>, it
will examine the
- <tt>debian/libfoo2/DEBIAN/shlibs</tt> file to
+ <file>debian/libfoo2/DEBIAN/shlibs</file> file to
determine whether <tt>foo-prog</tt>'s library
dependencies are satisfied by any of the libraries
provided by <tt>libfoo2</tt>. For this reason,
</item>
<item>
- <p><tt>/var/lib/dpkg/info/*.shlibs</tt></p>
+ <p><file>/var/lib/dpkg/info/*.shlibs</file></p>
<p>
- These are the <tt>shlibs</tt> files corresponding to
+ These are the <file>shlibs</file> files corresponding to
all of the packages installed on the system, and are
maintained by the relevant package maintainers.
</p>
</item>
<item>
- <p><tt>/etc/dpkg/shlibs.default</tt></p>
+ <p><file>/etc/dpkg/shlibs.default</file></p>
<p>
This file lists any shared libraries whose packages
- have failed to provide correct <tt>shlibs</tt> files.
- It was used when the <tt>shlibs</tt> setup was first
+ have failed to provide correct <file>shlibs</file> files.
+ It was used when the <file>shlibs</file> setup was first
introduced, but it is now normally empty. It is
maintained by the <tt>dpkg</tt> maintainer.
</p>
</item>
</list>
</p>
- </sect>
+ </sect1>
- <sect>
+ <sect1>
<heading>How to use <prgn>dpkg-shlibdeps</prgn> and the
- <tt>shlibs</tt> files</heading>
+ <file>shlibs</file> files</heading>
<p>
Put a call to <prgn>dpkg-shlibdeps</prgn> into your
- <tt>debian/rules</tt> file. If your package contains only
+ <file>debian/rules</file> file. If your package contains only
compiled binaries and libraries (but no scripts), you can
use a command such as:
<example compact="compact">
<p>
This command puts the dependency information into the
- <tt>debian/substvars</tt> file, which is then used by
+ <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>
field in the control file for this to work.
<p>
If <prgn>dpkg-shlibdeps</prgn> doesn't complain, you're
done. If it does complain you might need to create your own
- <tt>debian/shlibs.local</tt> file, as explained below (see
+ <file>debian/shlibs.local</file> file, as explained below (see
<ref id="shlibslocal">).
</p>
<prgn>dpkg-shlibdeps</prgn> on each one which contains
compiled libraries or binaries. In such a case, you will
need to use the <tt>-T</tt> option to the <tt>dpkg</tt>
- utilities to specify a different <tt>substvars</tt> file.
+ utilities to specify a different <file>substvars</file> file.
For more details on this and other options, see <manref
name="dpkg-shlibdeps" section="1">.
</p>
- </sect>
+ </sect1>
- <sect id="shlibs"><heading>The <tt>shlibs</tt> File Format
- </heading>
+ <sect1 id="shlibs">
+ <heading>The <file>shlibs</file> File Format</heading>
<p>
- Each <tt>shlibs</tt> file has the same format. Lines
- beginning with <tt>#</tt> are considered to be commments and
+ Each <file>shlibs</file> file has the same format. Lines
+ 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>
<p>
We will explain this by reference to the example of the
<tt>zlib1g</tt> package, which (at the time of writing)
- installs the shared library <tt>/usr/lib/libz.so.1.1.3</tt>.
+ installs the shared library <file>/usr/lib/libz.so.1.1.3</file>.
</p>
<p>
the dynamic linker about using older shared libraries with
newer binaries.
</p>
- </sect>
+ </sect1>
- <sect>
- <heading>Providing a <tt>shlibs</tt> file</heading>
+ <sect1>
+ <heading>Providing a <file>shlibs</file> file</heading>
<p>
If your package provides a shared library, you should create
- a <tt>shlibs</tt> file following the format described above.
- It is usual to call this file <tt>debian/shlibs</tt> (but if
+ 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
- <tt>debian/shlibs.<var>package</var></tt> instead). Then
- let <tt>debian/rules</tt> install it in the control area:
+ <file>debian/shlibs.<var>package</var></file> instead). Then
+ let <file>debian/rules</file> install it in the control area:
<example compact="compact">
install -m644 debian/shlibs debian/tmp/DEBIAN
</example>
install -m644 debian/shlibs.<var>package</var> debian/<var>package</var>/DEBIAN/shlibs
</example>
An alternative way of doing this is to create the
- <tt>shlibs</tt> file in the control area directly from
- <tt>debian/rules</tt> without using a <tt>debian/shlibs</tt>
+ <file>shlibs</file> file in the control area directly from
+ <file>debian/rules</file> without using a <file>debian/shlibs</file>
file at all,<footnote>
<p>
This is what <prgn>dh_makeshlibs</prgn> in the
<tt>debhelper</tt> suite does.
</p>
</footnote>
- since the <tt>debian/shlibs</tt> file itself is ignored by
+ since the <file>debian/shlibs</file> file itself is ignored by
<prgn>dpkg-shlibdeps</prgn>.
</p>
<p>
As <prgn>dpkg-shlibdeps</prgn> reads the
- <tt>DEBIAN/shlibs</tt> files in all of the binary packages
+ <file>DEBIAN/shlibs</file> files in all of the binary packages
being built from this source package, all of the
- <tt>DEBIAN/shlibs</tt> files should be installed before
+ <file>DEBIAN/shlibs</file> files should be installed before
<prgn>dpkg-shlibdeps</prgn> is called on any of the binary
packages.
</p>
- </sect>
+ </sect1>
- <sect id="shlibslocal">
- <heading>Writing the <tt>debian/shlibs.local</tt> file</heading>
+ <sect1 id="shlibslocal">
+ <heading>Writing the <file>debian/shlibs.local</file> file</heading>
<p>
This file is intended only as a <em>temporary</em> fix if
your binaries or libraries depend on a library whose package
- does not yet provide a correct <tt>shlibs</tt> file.
+ does not yet provide a correct <file>shlibs</file> file.
</p>
<p>
</example>
So the <prgn>foo</prgn> binary depends on the
<prgn>libbar</prgn> shared library, but no package seems to
- provide a <tt>*.shlibs</tt> file handling
- <tt>libbar.so.1</tt> in <tt>/var/lib/dpkg/info/</tt>. Let's
+ provide a <file>*.shlibs</file> file handling
+ <file>libbar.so.1</file> in <file>/var/lib/dpkg/info/</file>. Let's
determine the package responsible:
<example compact="compact">
$ dpkg -S /usr/lib/libbar.so.1
This tells us that the <tt>bar1</tt> package, version 1.0-1,
is the one we are using. Now we can file a bug against the
<tt>bar1</tt> package and create our own
- <tt>debian/shlibs.local</tt> to locally fix the problem.
+ <file>debian/shlibs.local</file> to locally fix the problem.
Including the following line into your
- <tt>debian/shlibs.local</tt> file:
+ <file>debian/shlibs.local</file> file:
<example compact="compact">
libbar 1 bar1 (>= 1.0-1)
</example>
<p>
As soon as the maintainer of <tt>bar1</tt> provides a
- correct <tt>shlibs</tt> file, you should remove this line
- from your <tt>debian/shlibs.local</tt> file. (You should
+ correct <file>shlibs</file> file, you should remove this line
+ from your <file>debian/shlibs.local</file> file. (You should
probably also then have a versioned <tt>Build-Depends</tt>
on <tt>bar1</tt> to help ensure that others do not have the
same problem building your package.)
</p>
+ </sect1>
+
</sect>
+
</chapt>
<chapt id="opersys"><heading>The Operating System</heading>
<p>
The location of all installed files and directories must
comply with the Filesystem Hierarchy Standard (FHS),
- version 2.1. This 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 on <url
- id="http://www.pathname.com/fhs/" name="FHS (upstream)">.
+ 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/"
+ name="FHS (Debian copy)"> alongside this manual (or, if
+ you have the <package>debian-policy</package> installed,
+ you can try <url
+ id="file:///usr/share/doc/debian-policy/fhs/" name="FHS
+ (local copy)">). The
+ latest version, which may be a more recent version, may
+ be found on
+ <url id="http://www.pathname.com/fhs/" name="FHS (upstream)">.
Specific questions about following the standard may be
asked on the <tt>debian-devel</tt> mailing list, or
- referred to Daniel Quinlan, the FHS coordinator, at
- <email>quinlan@pathname.com</email>.
+ referred to the FHS mailing list (see the
+ <url id="http://www.pathname.com/fhs/" name="FHS web site"> for
+ more information).
</p>
</sect1>
<p>
As mandated by the FHS, packages must not place any
- files in <tt>/usr/local</tt>, either by putting them in
+ files in <file>/usr/local</file>, either by putting them in
the file system archive to be unpacked by <prgn>dpkg</prgn>
or by manipulating them in their maintainer scripts.
</p>
<p>
However, the package may create empty directories below
- <tt>/usr/local</tt> so that the system administrator knows
+ <file>/usr/local</file> so that the system administrator knows
where to place site-specific files. These directories
should be removed on package removal if they are
empty.
<p>
Note, that this applies only to directories <em>below</em>
- <tt>/usr/local</tt>, not <em>in</em> <tt>/usr/local</tt>.
+ <file>/usr/local</file>, not <em>in</em> <file>/usr/local</file>.
Packages must not create sub-directories in the directory
- <tt>/usr/local</tt> itself, except those listed in FHS,
+ <file>/usr/local</file> itself, except those listed in FHS,
section 4.5. However, you may create directories below
them as you wish. You must not remove any of the
directories listed in 4.5, even if you created them.
</p>
<p>
- Since <tt>/usr/local</tt> can be mounted read-only from a
+ Since <file>/usr/local</file> can be mounted read-only from a
remote server, these directories must be created and
removed by the <prgn>postinst</prgn> and <prgn>prerm</prgn>
maintainer scripts and not be included in the
- <tt>.deb</tt> archive. These scripts must not fail if
- either of these operations fail.<footnote>
- <p>
- In the future, it may be possible to tell
- <prgn>dpkg</prgn> not to unpack files matching certain
- patterns, so that the directories can be included in
- the <tt>.deb</tt> packages and system administrators
- who do not wish these directories in
- <tt>/usr/local</tt> do not need to have them.)
- </p>
- </footnote>
+ <file>.deb</file> archive. These scripts must not fail if
+ either of these operations fail.
</p>
<p>
</example>
in the <prgn>prerm</prgn> script. (Note that this form is
used to ensure that if the script is interrupted, the
- directory <tt>/usr/local/share/emacs</tt> will still be
+ directory <file>/usr/local/share/emacs</file> will still be
removed.)
</p>
<p>
- If you do create a directory in <tt>/usr/local</tt> for
+ If you do create a directory in <file>/usr/local</file> for
local additions to a package, you should ensure that
- settings in <tt>/usr/local</tt> take precedence over the
- equivalents in <tt>/usr</tt>.
+ settings in <file>/usr/local</file> take precedence over the
+ equivalents in <file>/usr</file>.
</p>
<p>
- However, because <tt>/usr/local</tt> and its contents are
+ However, because <file>/usr/local</file> and its contents are
for exclusive use of the local administrator, a package
must not rely on the presence or absence of files or
- directories in <tt>/usr/local</tt> for normal operation.
+ directories in <file>/usr/local</file> for normal operation.
</p>
<p>
- The <tt>/usr/local</tt> directory itself and all the
+ The <file>/usr/local</file> directory itself and all the
subdirectories created by the package should (by default) have
permissions 2775 (group-writable and set-group-id) and be
owned by <tt>root.staff</tt>.
<sect1>
<heading>The system-wide mail directory</heading>
<p>
- The system-wide mail directory is <tt>/var/mail</tt>. This
+ The system-wide mail directory is <file>/var/mail</file>. This
directory is part of the base system and should not owned
by any particular mail agents. The use of the old
- location <tt>/var/spool/mail</tt> is deprecated, even
+ location <file>/var/spool/mail</file> is deprecated, even
though the spool may still be physically located there.
To maintain partial upgrade compatibility for systems
- which have <tt>/var/spool/mail</tt> as their physical mail
- spool, packages using <tt>/var/mail</tt> must depend on
+ which have <file>/var/spool/mail</file> as their physical mail
+ spool, packages using <file>/var/mail</file> must depend on
either <package>libc6</package> (>= 2.1.3-13), or on
<package>base-files</package> (>= 2.2.0), or on later
versions of either one of these packages.
<p>
Packages other than <tt>base-passwd</tt> must not modify
- <tt>/etc/passwd</tt>, <tt>/etc/shadow</tt>,
- <tt>/etc/group</tt> or <tt>/etc/gshadow</tt>.
+ <file>/etc/passwd</file>, <file>/etc/shadow</file>,
+ <file>/etc/group</file> or <file>/etc/gshadow</file>.
</p>
</sect1>
<p>
Globally allocated by the Debian project, the same
on every Debian system. These ids will appear in
- the <tt>passwd</tt> and <tt>group</tt> files of all
+ the <file>passwd</file> and <file>group</file> files of all
Debian systems, new ids in this range being added
automatically as the <tt>base-passwd</tt> package is
updated.
<prgn>adduser</prgn> will check for the existence of
the user or group, and if necessary choose an unused
id based on the ranges specified in
- <tt>adduser.conf</tt>.
+ <file>adduser.conf</file>.
</p>
</item>
Dynamically allocated user accounts. By default
<prgn>adduser</prgn> will choose UIDs and GIDs for
user accounts in this range, though
- <tt>adduser.conf</tt> may be used to modify this
+ <file>adduser.conf</file> may be used to modify this
behavior.
</p>
</item>
These ids are for packages which are obscure or
which require many statically-allocated ids. These
packages should check for and create the accounts in
- <tt>/etc/passwd</tt> or <tt>/etc/group</tt> (using
+ <file>/etc/passwd</file> or <file>/etc/group</file> (using
<prgn>adduser</prgn> if it has this facility) if
necessary. Packages which are likely to require
- further allocations should have a `hole' left after
+ further allocations should have a "hole" left after
them in the allocation, to give them room to
grow.
</p>
</sect>
<sect id="sysvinit">
- <heading>System run levels and <tt>init.d</tt> scripts</heading>
+ <heading>System run levels and <file>init.d</file> scripts</heading>
<sect1 id="/etc/init.d">
<heading>Introduction</heading>
<p>
- The <tt>/etc/init.d</tt> directory contains the scripts
+ The <file>/etc/init.d</file> directory contains the scripts
executed by <prgn>init</prgn> at boot time and when the
- init state (or `runlevel') is changed (see <manref
+ init state (or "runlevel") is changed (see <manref
name="init" section="8">).
</p>
<p>
These scripts are referenced by symbolic links in the
- <tt>/etc/rc<var>n</var>.d</tt> directories. When changing
+ <file>/etc/rc<var>n</var>.d</file> directories. When changing
runlevels, <prgn>init</prgn> looks in the directory
- <tt>/etc/rc<var>n</var>.d</tt> for the scripts it should
+ <file>/etc/rc<var>n</var>.d</file> for the scripts it should
execute, where <tt><var>n</var></tt> is the runlevel that
is being changed to, or <tt>S</tt> for the boot-up
scripts.
<p>
The names of the links all have the form
- <tt>S<var>mm</var><var>script</var></tt> or
- <tt>K<var>mm</var><var>script</var></tt> where
+ <file>S<var>mm</var><var>script</var></file> or
+ <file>K<var>mm</var><var>script</var></file> where
<var>mm</var> is a two-digit number and <var>script</var>
is the name of the script (this should be the same as the
- name of the actual script in <tt>/etc/init.d</tt>).
+ name of the actual script in <file>/etc/init.d</file>).
</p>
<p>
executed, each with the single argument <tt>stop</tt>,
followed by the scripts prefixed with an <tt>S</tt>, each
with the single argument <tt>start</tt>. (The links are
- those in the <tt>/etc/rc<var>n</var>.d</tt> directory
+ those in the <file>/etc/rc<var>n</var>.d</file> directory
corresponding to the new runlevel.) The <tt>K</tt> links
are responsible for killing services and the <tt>S</tt>
link for starting services upon entering the runlevel.
<p>
For example, if we are changing from runlevel 2 to
runlevel 3, init will first execute all of the <tt>K</tt>
- prefixed scripts it finds in <tt>/etc/rc3.d</tt>, and then
+ prefixed scripts it finds in <file>/etc/rc3.d</file>, and then
all of the <tt>S</tt> prefixed scripts in that directory.
The links starting with <tt>K</tt> will cause the
referred-to file to be executed with an argument of
<p>
Packages that include daemons for system services should
- place scripts in <tt>/etc/init.d</tt> to start or stop
+ place scripts in <file>/etc/init.d</file> to start or stop
services at boot time or during a change of runlevel.
These scripts should be named
- <tt>/etc/init.d/<var>package</var></tt>, and they should
+ <file>/etc/init.d/<var>package</var></file>, and they should
accept one argument, saying what to do:
<taglist>
<item><p>stop the service,</p></item>
<tag><tt>restart</tt></tag>
- <item><p>stop and restart the service,</p></item>
+ <item><p>stop and restart the service if it's already
+ running, otherwise start the service</p></item>
<tag><tt>reload</tt></tag>
<item><p>cause the configuration of the service to be
The <tt>start</tt>, <tt>stop</tt>, <tt>restart</tt>, and
<tt>force-reload</tt> options should be supported by all
- scripts in <tt>/etc/init.d</tt>, the <tt>reload</tt>
+ scripts in <file>/etc/init.d</file>, the <tt>reload</tt>
option is optional.</p>
<p>
- The <tt>init.d</tt> scripts should ensure that they will
+ The <file>init.d</file> scripts should 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
<p>
If a service reloads its configuration automatically (as
in the case of <prgn>cron</prgn>, for example), the
- <tt>reload</tt> option of the <tt>init.d</tt> script
+ <tt>reload</tt> option of the <file>init.d</file> script
should behave as if the configuration has been reloaded
successfully.</p>
<p>
- The <tt>/etc/init.d</tt> scripts should be treated as
- configuration files, either by marking them as
- <tt>conffile</tt>s or managing them correctly in the
- maintainer scripts (see <ref id="config files">). This is
- important since we want to give the local system
- administrator the chance to adapt 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 package upgrade.
+ The <file>/etc/init.d</file> scripts must be treated as
+ configuration files, either (if they are present in the
+ package, that is, in the .deb file) by marking them as
+ <tt>conffile</tt>s, or, (if they do not exist in the .deb)
+ by managing them correctly in the maintainer scripts (see
+ <ref id="config-files">). This is important since we want
+ to give the local system administrator the chance to adapt
+ 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
+ package upgrade.
</p>
<p>
the package has been removed. Only when <prgn>dpkg</prgn>
is executed with the <tt>--purge</tt> option will
configuration files be removed. In particular, as the
- <tt>/etc/init.d/<var>package</var></tt> script itself is
+ <file>/etc/init.d/<var>package</var></file> script itself is
usually a <tt>conffile</tt>, it will remain on the system
if the package is removed but not purged. Therefore, you
should include a <tt>test</tt> statement at the top of the
</p>
<p>
- Often there are some variables in the <tt>init.d</tt>
- scripts whose values control the bahaviour of the scripts,
+ Often there are some variables in the <file>init.d</file>
+ scripts whose values control the behaviour 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
administrator merge in their changes each time the package
- is upgraded and the <tt>conffile changes</tt>. To ease
+ is upgraded and the <tt>conffile</tt> changes. To ease
the burden on the system administrator, such configurable
values should not be placed directly in the script.
Instead, they should be placed in a file in
- <tt>/etc/default</tt>, which typically will have thesame
- base name as the <tt>init.d</tt> script. This extra file
+ <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
- <prgn>sh</prgn> format. It should not be a
- <tt>conffile</tt>, but a configuration file maintained by
- the package maintainer scripts. See <ref id="config files">
+ <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">
for more details.
</p>
<p>
To ensure that vital configurable values are always
- available, the <tt>init.d</tt> script should set default
+ available, the <file>init.d</file> script should set default
values for each of the shell variables it uses, either
- before sourcing the <tt>/etc/default/</tt> file or
+ before sourcing the <file>/etc/default/</file> file or
afterwards using something like the <tt>:
- ${VAR:=default}</tt> syntax. Also, the <tt>init.d</tt>
+ ${VAR:=default}</tt> syntax. Also, the <file>init.d</file>
script must behave sensibly and not fail if the
- <tt>/etc/default</tt> file is deleted.
+ <file>/etc/default</file> file is deleted.
</p>
</sect1>
<sect1>
- <heading>Managing the links</heading>
+ <heading>Interfacing with the initscript system</heading>
<p>
- The program <prgn>update-rc.d</prgn> is provided for
- package maintainers to arrange for the proper creation and
- removal of <tt>/etc/rc<var>n</var>.d</tt> symbolic links,
- or their functional equivalent if another method is being
- used. This may be used by maintainers in their packages'
- <prgn>postinst</prgn> and <prgn>postrm</prgn> scripts.</p>
-
- <p>
- You must not include any <tt>/etc/rc<var>n</var>.d</tt>
- symbolic links in the actual archive or manually create or
- remove the symbolic links in maintainer scripts; you must
- use the <prgn>update-rc.d</prgn> program instead. (The
- former will fail if an alternative method of maintaining
- runlevel information is being used.) You must not include
- the <tt>/etc/rc<var>n</var>.d</tt> directories themselves
- in the archive either. (Only the <tt>sysvinit</tt>
- package may do so.)
+ Maintainers should use the abstraction layer provided by
+ the <prgn>update-rc.d</prgn> and <prgn>invoke-rc.d</prgn>
+ programs to deal with initscripts in their packages'
+ scripts such as <prgn>postinst</prgn>, <prgn>prerm</prgn>
+ and <prgn>postrm</prgn>.
</p>
-
<p>
- By default <prgn>update-rc.d</prgn> will start services in
- each of the multi-user state runlevels (2, 3, 4, and 5)
- and stop them in the halt runlevel (0), the single-user
- runlevel (1) and the reboot runlevel (6). The system
- administrator will have the opportunity to customize
- runlevels by simply adding, moving, or removing the
- symbolic links in <tt>/etc/rc<var>n</var>.d</tt> if
- symbolic links are being used, or by modifying
- <tt>/etc/runlevel.conf</tt> if the <tt>file-rc</tt> method
- is being used.
+ Directly managing the /etc/rc?.d links and directly
+ invoking the <file>/etc/init.d/</file> initscripts should
+ be done only by packages providing the initscript
+ subsystem (such as <prgn>sysvinit</prgn> and
+ <prgn>file-rc</prgn>).
+
</p>
- <p>
- To get the default behavior for your package, put in your
- <prgn>postinst</prgn> script
- <example compact="compact">
-update-rc.d <var>package</var> defaults >/dev/null
- </example>
- and in your <prgn>postrm</prgn>
- <example compact="compact">
-if [ "$1" = purge ]; then
- update-rc.d <var>package</var> remove >/dev/null
-fi
- </example></p>
+ <sect2>
+ <heading>Managing the links</heading>
- <p>
- This will use a default sequence number of 20. If it does
- not matter when or in which order the <tt>init.d</tt>
- script is run, use this default. If it does, then you
- should talk to the maintainer of the <prgn>sysvinit</prgn>
- package or post to <tt>debian-devel</tt>, and they will
- help you choose a number.
- </p>
+ <p>
+ The program <prgn>update-rc.d</prgn> is provided for
+ package maintainers to arrange for the proper creation and
+ removal of <file>/etc/rc<var>n</var>.d</file> symbolic links,
+ or their functional equivalent if another method is being
+ used. This may be used by maintainers in their packages'
+ <prgn>postinst</prgn> and <prgn>postrm</prgn> scripts.</p>
- <p>
- For more information about using <tt>update-rc.d</tt>,
- please consult its manpage <manref name="update-rc.d"
- section="8">.
- </p>
+ <p>
+ You must not include any <file>/etc/rc<var>n</var>.d</file>
+ symbolic links in the actual archive or manually create or
+ remove the symbolic links in maintainer scripts; you must
+ use the <prgn>update-rc.d</prgn> program instead. (The
+ former will fail if an alternative method of maintaining
+ runlevel information is being used.) You must not include
+ the <file>/etc/rc<var>n</var>.d</file> directories themselves
+ in the archive either. (Only the <tt>sysvinit</tt>
+ package may do so.)
+ </p>
+
+ <p>
+ By default <prgn>update-rc.d</prgn> will start services in
+ each of the multi-user state runlevels (2, 3, 4, and 5)
+ and stop them in the halt runlevel (0), the single-user
+ runlevel (1) and the reboot runlevel (6). The system
+ administrator will have the opportunity to customize
+ runlevels by simply adding, moving, or removing the
+ symbolic links in <file>/etc/rc<var>n</var>.d</file> if
+ symbolic links are being used, or by modifying
+ <file>/etc/runlevel.conf</file> if the <tt>file-rc</tt> method
+ is being used.
+ </p>
+
+ <p>
+ To get the default behavior for your package, put in your
+ <prgn>postinst</prgn> script
+ <example compact="compact">
+ update-rc.d <var>package</var> defaults
+ </example>
+ and in your <prgn>postrm</prgn>
+ <example compact="compact">
+ if [ "$1" = purge ]; then
+ update-rc.d <var>package</var> remove
+ fi
+ </example>. Note that if your package changes runlevels
+ or priority, you may have to remove and recreate the links,
+ since otherwise the old links may persist. Refer to the
+ documentation of <prgn>update-rc.d</prgn></p>
+
+ <p>
+ This will use a default sequence number of 20. If it does
+ not matter when or in which order the <file>init.d</file>
+ script is run, use this default. If it does, then you
+ should talk to the maintainer of the <prgn>sysvinit</prgn>
+ package or post to <tt>debian-devel</tt>, and they will
+ help you choose a number.
+ </p>
+
+ <p>
+ For more information about using <tt>update-rc.d</tt>,
+ please consult its manpage <manref name="update-rc.d"
+ section="8">.
+ </p>
+ </sect2>
+
+ <sect2>
+ <heading>Running initscripts</heading>
+ <p>
+ The program <prgn>invoke-rc.d</prgn> is provided to make
+ it easier for package maintainers to properly invoke an
+ initscript, obeying runlevel and other locally-defined
+ constraints that might limit a package's right to start,
+ stop and otherwise manage services. This program may be
+ used by maintainers in their packages' scripts.
+ </p>
+ <p>
+ The use of <prgn>invoke-rc.d</prgn> to invoke the
+ <file>/etc/init.d/*</file> initscripts is strongly
+ recommended<footnote>
+ <p>
+ 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.</p>
+ </footnote>, instead of calling them directly.
+ </p>
+
+ <p>
+ By default, <prgn>invoke-rc.d</prgn> will pass any
+ action requests (start, stop, reload, restart...) to the
+ <file>/etc/init.d</file> script, filtering out requests
+ to start or restart a service out of its intended
+ runlevels.
+ </p>
+ <p>
+ Most packages will simply need to change:
+ <example compact="compact">/etc/init.d/<package>
+ <action></example> in their <prgn>postinst</prgn>
+ and <prgn>prerm</prgn> scripts to:
+ <example compact="compact">
+ if [ -x /usr/sbin/invoke-rc.d ] ; then
+ invoke-rc.d <var>package</var> <action>
+ else
+ /etc/init.d/<var>package</var> <action>
+ fi
+ </example></p>
+ <p>
+ A package should register its initscript services using
+ <prgn>update-rc.d</prgn> before it tries to invoke them
+ using <prgn>invoke-rc.d</prgn>. Invocation of
+ unregistered services may fail.
+ </p>
+ <p>
+ For more information about using
+ <prgn>invoke-rc.d</prgn>, please consult its manpage
+ <manref name="invoke-rc.d" section="8">.
+ </p>
+ </sect2>
</sect1>
<heading>Boot-time initialization</heading>
<p>
- There used to be another directory, <tt>/etc/rc.boot</tt>,
+ There used to be another directory, <file>/etc/rc.boot</file>,
which contained scripts which were run once per machine
boot. This has been deprecated in favour of links from
- <tt>/etc/rcS.d</tt> to files in <tt>/etc/init.d</tt> as
+ <file>/etc/rcS.d</file> to files in <file>/etc/init.d</file> as
described in <ref id="/etc/init.d">. Packages must not
- place files in <tt>/etc/rc.boot</tt>.</p>
+ place files in <file>/etc/rc.boot</file>.</p>
<sect1>
<heading>Example</heading>
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 <tt>/etc/init.d</tt>, naming the script
+ 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
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
- <tt>/etc/default/bind</tt> (see below).
+ <file>/etc/default/bind</file> (see below).
</p>
<p>
echo "."
;;
*)
- echo "Usage: /etc/init.d/bind {start|stop|restart|reload|force-reload}" >&2
+ echo "Usage: /etc/init.d/bind " \
+ " {start|stop|restart|reload|force-reload}" >&2
exit 1
;;
esac
<p>
Complementing the above init script is a configuration
- file <tt>/etc/default/bind</tt>, which contains
+ 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
<p>
Another example on which you can base your
- <tt>/etc/init.d</tt> scripts is found in
- <tt>/etc/init.d/skeleton</tt>.
+ <file>/etc/init.d</file> scripts is found in
+ <file>/etc/init.d/skeleton</file>.
</p>
<p>
</sect>
<sect>
- <heading>Console messages from <tt>init.d</tt> scripts</heading>
+ <heading>Console messages from <file>init.d</file> scripts</heading>
<p>
This section describes the formats to be used for messages
- written to standard output by the <tt>/etc/init.d</tt>
+ written to standard output by the <file>/etc/init.d</file>
scripts. The intent is to improve the consistency of
Debian's startup and shutdown look and feel. For this
reason, please look very carefully at the details. We want
</p>
<p>
- For example, the output of <tt>/etc/init.d/lpd</tt>
+ For example, the output of <file>/etc/init.d/lpd</file>
would look like:
<example compact="compact">
Starting printer spooler: lpd.
If you have to set up different system parameters
during the system boot, you should use this format:
<example compact="compact">
-Setting <var>parameter</var> to `<var>value</var>'.
+Setting <var>parameter</var> to "<var>value</var>".
</example>
</p>
You can use a statement such as the following to get
the quotes right:
<example compact="compact">
-echo "Setting DNS domainname to \`$domainname'."
+echo "Setting DNS domainname to \"$domainname\"."
</example>
</p>
<p>
- Note that the left quotation mark (<tt>`</tt>) is
- different from the right one (<tt>'</tt>).
+ Note that the same symbol (<tt>"</tt>) is used for the left
+ and right quotation marks. A grave accent (<tt>`</tt>) is
+ not a quote character; neither is an apostrophe
+ (<tt>'</tt>).
</p>
</item>
<p>
Packages must not modify the configuration file
- <tt>/etc/crontab</tt>, and they must not modify the files in
- <tt>/var/spool/cron/crontabs</tt>.</p>
+ <file>/etc/crontab</file>, and they must not modify the files in
+ <file>/var/spool/cron/crontabs</file>.</p>
<p>
If a package wants to install a job that has to be executed
As these directory names imply, the files within them are
executed on a daily, weekly, or monthly basis,
respectively. The exact times are listed in
- <tt>/etc/crontab</tt>.</p>
+ <file>/etc/crontab</file>.</p>
<p>
All files installed in any of these directories must be
<p>
If a certain job has to be executed more frequently than
daily, the package should install a file
- <tt>/etc/cron.d/<var>package</var></tt>. This file uses the
- same syntax as <tt>/etc/crontab</tt> and is processed by
+ <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
treated as a configuration file. (Note that entries in the
- <tt>/etc/cron.d</tt> directory are not handled by
+ <file>/etc/cron.d</file> directory are not handled by
<prgn>anacron</prgn>. Thus, you should only use this
directory for jobs which may be skipped if the system is not
running.)</p>
<sect>
<heading>Menus</heading>
- <p>
- Menu entries should follow the current menu policy found in
- the <tt>menu-policy</tt> files in the <tt>debian-policy</tt>
- package. It may also be found on the Debian FTP site
- <ftpsite>ftp.debian.org</ftpsite> as the file
- <ftppath>/debian/doc/package-developer/menu-policy.txt.gz</ftppath>,
- or in the equivalent location on your local mirror.
- </p>
-
<p>
The Debian <tt>menu</tt> package provides a standard
interface between packages providing applications and
operation should register a menu entry for those
applications, so that users of the <tt>menu</tt> package
will automatically get menu entries in their window
- managers, as well in shells like <tt>pdmenu</tt>.</p>
+ managers, as well in shells like <tt>pdmenu</tt>.
+ </p>
+
+ <p>
+ Menu entries should follow the current menu policy.
+ </p>
+
+ <p>
+ The menu policy can be found in the <tt>menu-policy</tt>
+ files in the <tt>debian-policy</tt> package.
+ They are 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>.
+ </p>
<p>
Please also refer to the <em>Debian Menu System</em>
<sect>
<heading>Multimedia handlers</heading>
- <p>
- Packages which provide the ability to view/show/play,
- compose, edit or print MIME types should register themselves
- as such following the current MIME support policy found in
- the <tt>mime-policy</tt> files in the <tt>debian-policy</tt>
- package. It may also be found on the Debian FTP site
- <ftpsite>ftp.debian.org</ftpsite> as the file
- <ftppath>/debian/doc/package-developer/mime-policy.txt.gz</ftppath>,
- or in the equivalent location on your local mirror.
- </p>
-
<p>
MIME (Multipurpose Internet Mail Extensions, RFCs 2045-2049)
is a mechanism for encoding files and data streams and
view, edit or display MIME types they don't support
directly.
</p>
+
+ <p>
+ Packages which provide the ability to view/show/play,
+ compose, edit or print MIME types should register themselves
+ as such following the current MIME support policy.
+ </p>
+
+ <p>
+ The MIME support policy can be found in the <tt>mime-policy</tt>
+ files in the <tt>debian-policy</tt> package.
+ They are 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>.
+ </p>
+
</sect>
<sect>
<p>
<list>
- <item><p><tt><--</tt> generates <tt>KB_Backspace</tt>
+ <item><p><tt><--</tt> generates <tt>KB_BackSpace</tt>
in X.</p></item>
<item><p><tt>Delete</tt> generates <tt>KB_Delete</tt> in
X translations are set up to make
<tt>KB_Backspace</tt> generate ASCII DEL, and to make
<tt>KB_Delete</tt> generate <tt>ESC [ 3 ~</tt> (this
- is the vt220 escape code for the `delete character'
+ is the vt220 escape code for the "delete character"
key). This must be done by loading the X resources
using <prgn>xrdb</prgn> on all local X displays, not
using the application defaults, so that the
<p>
Other applications use the <tt>stty erase</tt>
character and <tt>kdch1</tt> for the two delete keys,
- with ASCII DEL being `delete previous character' and
- <tt>kdch1</tt> being `delete character under
- cursor'.</p></item>
+ with ASCII DEL being "delete previous character" and
+ <tt>kdch1</tt> being "delete character under
+ cursor".</p></item>
</list>
</p>
A program must not depend on environment variables to get
reasonable defaults. (That's because these environment
variables would have to be set in a system-wide
- configuration file like <tt>/etc/profile</tt>, which is not
+ configuration file like <file>/etc/profile</file>, which is not
supported by all shells.)</p>
<p>
variables are not present. If this cannot be done easily
(e.g., if the source code of a non-free program is not
available), the program must be replaced by a small
- `wrapper' shell script which sets the environment variables
+ "wrapper" shell script which sets the environment variables
if they are not already defined, and calls the original program.</p>
<p>
</p>
<p>
- Furthermore, as <tt>/etc/profile</tt> is a configuration
+ Furthermore, as <file>/etc/profile</file> is a configuration
file of the <prgn>base-files</prgn> package, other packages must not
put any environment variables or other commands into that
file.</p>
Two different packages must not install programs with
different functionality but with the same filenames. (The
case of two programs having the same functionality but
- different implementations is handled via `alternatives' or
- the `Conflicts' mechanism. See <ref id="maintscripts"> and
+ different implementations is handled via "alternatives" or
+ the "Conflicts" mechanism. See <ref id="maintscripts"> and
<ref id="conflicts"> respectively.) If this case happens,
one of the programs must be renamed. The maintainers should
report this to the <tt>debian-devel</tt> mailing list and
</p>
<p>
- Generally the following compilation parameters should be used:
+ By default, when a package is being built, any binaries
+ created should include debugging information, as well as
+ being compiled with optimization. You should also turn on
+ as many reasonable compilation warnings as possible; this
+ makes life easier for porters, who can then look at build
+ logs for possible problems. For the C programming language,
+ this means the following compilation parameters should be
+ used:
<example compact="compact">
CC = gcc
-CFLAGS = -O2 -Wall # sane warning options vary between programs
+CFLAGS = -O2 -g -Wall # sane warning options vary between programs
LDFLAGS = # none
install -s # (or use strip on the files in debian/tmp)
- </example></p>
+ </example>
+ </p>
<p>
Note that by default all installed binaries should be stripped,
either by using the <tt>-s</tt> flag to
<prgn>install</prgn>, or by calling <prgn>strip</prgn> on
the binaries after they have been copied into
- <tt>debian/tmp</tt> but before the tree is made into a
+ <file>debian/tmp</file> but before the tree is made into a
package.</p>
<p>
- The <tt>-N</tt> flag should not be used. On <tt>a.out</tt>
- systems it may have been useful for some very small
- binaries, but for ELF it has no good effect.</p>
-
- <p>
- Debugging symbols are useful for error diagnosis,
- investigation of core dumps (which may be submitted by users
- in bug reports), or testing and developing the software.
- Therefore it is recommended to support building the package
- with debugging information through the following interface:
- If the environment variable <tt>DEB_BUILD_OPTIONS</tt>
- contains the string <tt>debug</tt>, compile the software
- with debugging information (usually this involves adding the
- <tt>-g</tt> flag to <tt>CFLAGS</tt>). This allows the
- generation of a build tree with debugging information. If
- the environment variable <tt>DEB_BUILD_OPTIONS</tt> contains
- the string <tt>nostrip</tt>, do not strip the files at
- installation time. This allows one to generate a package
- with debugging information included.<footnote>
- <p>
- Rationale: Using <tt>-g</tt> by default causes wasted
- CPU cycles since the information is stripped away
- anyway; this can have a significant impact on the
- efficiency of the autobuilders. Having a standard way
- to build a debugging variant also makes it easier to
- build debugging bins and libraries since it provides a
- documented way of getting this type of build; one does
- not have to manually edit <tt>debian/rules</tt> or
- <tt>Makefile</tt>s.
- </p>
- </footnote>
+ 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>
+ <p>
+ The presence of this string means that the package
+ should be complied 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.
+ </p>
+ </item>
+ <tag>nostrip</tag>
+ <item>
+ <p>
+ 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.
+ </p>
+ </item>
+ </taglist>
+ </p>
+ <p>
The following makefile snippet is an example of how one may
- test for either condition; you will probably have to massage
- this example in order to make it work for your package.
- <example compact="compact">
-CFLAGS = -O2 -Wall
+ 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 debug,$(DEB_BUILD_OPTIONS)))
-CFLAGS += -g
+ifneq (,$(findstring noopt,$(DEB_BUILD_OPTIONS)))
+CFLAGS += -O0
+else
+CFLAGS += -O2
endif
ifeq (,$(findstring nostrip,$(DEB_BUILD_OPTIONS)))
INSTALL_PROGRAM += -s
if there is good reason to do so. Feel free to override
the upstream author's ideas about which compilation
options are best: they are often inappropriate for our
- environment.</p></sect>
+ environment.
+ </p>
+ </sect>
- <sect>
+ <sect id="libraries">
<heading>Libraries</heading>
<p>
- All libraries must have a shared version in the
- <tt>lib*</tt> package and a static version in the
- <tt>lib*-dev</tt> package. The shared version must be
- compiled with <tt>-fPIC</tt>, and the static version must
- not be. In other words, each <tt>*.c</tt> file will need to
- be compiled twice.</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.
+ </p>
+
<p>
You must specify the gcc option <tt>-D_REENTRANT</tt>
when building a library (either static or shared) to make
- the library compatible with LinuxThreads.</p>
+ the library compatible with LinuxThreads.
+ </p>
<p>
- Note that all installed shared libraries should be
- stripped with
+ All installed shared libraries should be stripped with
<example compact="compact">
strip --strip-unneeded <var>your-lib</var>
</example>
building a separate package to support debugging.
</p>
+ <p>
+ Shared object files (often <file>.so</file> files) that are not
+ public libraries, that is, they are not meant to be linked
+ to by third party executables (binaries of other packages),
+ should be installed in subdirectories of the
+ <file>/usr/lib</file> directory. Such files are exempt from the
+ rules that govern ordinary shared libraries, except that
+ they must not be installed executable and should be
+ stripped.<footnote>
+ <p>
+ A common example are the so-called "plug-ins",
+ internal shared objects that are dynamically loaded by
+ programs using <manref name="dlopen" section="3">.
+ </p>
+ </footnote>
+ </p>
+
+ <p>
+ Packages containing shared libraries that may be linked to
+ by other packages' binaries, but which for some
+ <em>compelling</em> reason can not be installed in
+ <file>/usr/lib</file> directory, may install the shared library
+ files in subdirectories of the <file>/usr/lib</file> directory,
+ in which case they should arrange to add that directory in
+ <file>/etc/ld.so.conf</file> in the package's post-installation
+ script, and remove it in the package's post-removal script.
+ </p>
+
<p>
An ever increasing number of packages are using
<prgn>libtool</prgn> to do their linking. The latest GNU
libtools (>= 1.3a) can take advantage of the metadata in the
- installed <prgn>libtool</prgn> archive files (<tt>*.la</tt>
+ installed <prgn>libtool</prgn> archive files (<file>*.la</file>
files). The main advantage of <prgn>libtool</prgn>'s
- <
tt>.la</tt> files is that it allows <prgn>libtool</prgn> to
+ <
file>.la</file> files is that it allows <prgn>libtool</prgn> to
store and subsequently access metadata with respect to the
libraries it builds. <prgn>libtool</prgn> will search for
those files, which contain a lot of useful information about
for each library every time it is linked. With the
advent of <prgn>libtool</prgn> version 1.4 (and to a
lesser extent <prgn>libtool</prgn> version 1.3), the
- <tt>.la</tt> files also store information about
+ <file>.la</file> files also store information about
inter-library dependencies which cannot necessarily be
- derived after the <tt>.la</tt> file is deleted.
+ derived after the <file>.la</file> file is deleted.
</p>
</footnote>
</p>
<p>
Packages that use <prgn>libtool</prgn> to create shared
- libraries should include the <tt>.la</tt> files in the
+ libraries should include the <file>.la</file> files in the
<tt>-dev</tt> package, unless the package relies on
<tt>libtool</tt>'s <tt>libltdl</tt> library, in which case
the <tt>.la</tt> files must go in the run-time library
</p>
</sect>
+
<sect>
<heading>Shared libraries</heading>
-
- <p>
- Packages involving shared libraries should be split up
- into several binary packages.</p>
-
- <p>
- For a straightforward library which has a development
- environment and a runtime kit including just shared
- libraries you need to create two packages:
- <tt><var>libraryname</var><var>soversion</var></tt>, where
- <tt><var>soversion</var></tt> is the version number in the
- soname of the shared library<footnote>
- <p>
- 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
- program. For example, if the soname of the library is
- <tt>libfoo.so.6</tt>, the library package would be
- called <tt>libfoo6</tt>.
- </p>
- </footnote>
- and <tt><var>libraryname</var><var>soversion</var>-dev</tt>.
- </p>
-
- <p>
- If you prefer only to support one development version at a
- time you may name the development package
- <tt><var>libraryname</var>-dev</tt>; otherwise you may need
- to use <prgn>dpkg</prgn>'s Conflicts mechanism (see <ref
- id="conflicts">) to ensure that the user only installs one
- development version at a time (as different development
- versions are likely to have the same header files in them,
- which would cause a filename clash if both were installed).
- Typically the development version should also 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
- useful for this purpose.
- </p>
-
- <p>
- Packages which use the shared library should have a
- dependency on the name of the shared library package,
- <tt><var>libraryname</var><var>soversion</var></tt>. When
- the soname changes you can have both versions of the library
- installed while migrating from the old library to the new.
- </p>
-
- <p>
- If your package has some run-time support programs which use
- the shared library you must not put them in the shared
- library package. If you do that then you won't be able to
- install several versions of the shared library without
- getting filename clashes. Instead, either create a third
- package for the runtime binaries (this package might
- typically be named <tt><var>libraryname</var>-runtime</tt>;
- note the absence of the <var>soversion</var> in the package
- name), or if the development package is small you may
- include them in there.
- </p>
-
- <p>
- If you have several shared libraries built from the same
- source tree you may lump them all together into a single
- shared library package, provided that you change all of
- their sonames at once (so that you don't get filename
- clashes if you try to install different versions of the
- combined shared libraries package).
- </p>
-
<p>
- Shared libraries should not be installed executable, since
- the dynamic linker does not require this and trying to
- execute a shared library usually results in a core dump.
+ This section has moved to <ref id="sharedlibs">.
</p>
</sect>
+
<sect id="scripts">
<heading>Scripts</heading>
command.</p>
<p>
- The standard shell interpreter <tt>/bin/sh</tt> can be a
+ 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>
<p>
Debian policy specifies POSIX behavior for
- <tt>/bin/sh</tt>, but <tt>echo -n</tt> has widespread
+ <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
the LSB anyway.
</p>
</footnote>
- Thus, shell scripts specifying <tt>/bin/sh</tt> as
+ 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
+ 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 <tt>/bin/sh</tt> as its
- interpreter. If your script works with <prgn>ash</prgn>,
- it's probably POSIX compliant, but if you are in doubt, use
- <tt>/bin/bash</tt>.
+ 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
+ <file>/bin/bash</file>.
</p>
<p>
<p>
Any scripts which create files in world-writeable
- directories (e.g., in <tt>/tmp</tt>) must use a
+ directories (e.g., in <file>/tmp</file>) must use a
mechanism which will fail if a file with the same name
already exists.</p>
<p>
- The Debian base distribution provides the
- <prgn>tempfile</prgn> and <prgn>mktemp</prgn> utilities
- for use by scripts for this purpose.</p></sect>
+ The Debian base system provides the <prgn>tempfile</prgn>
+ and <prgn>mktemp</prgn> utilities for use by scripts for
+ this purpose.</p></sect>
<sect>
should be relative, and symbolic links pointing from one
top-level directory into another should be absolute. (A
top-level directory is a sub-directory of the root
- directory <tt>/</tt>.)</p>
+ directory <file>/</file>.)</p>
<p>
In addition, symbolic links should be specified as short as
- possible, i.e., link targets like <tt>foo/../bar</tt> are
+ possible, i.e., link targets like <file>foo/../bar</file> are
deprecated.</p>
<p>
<p>
For example, in your <prgn>Makefile</prgn> or
- <tt>debian/rules</tt>, you can do things like:
+ <file>debian/rules</file>, you can do things like:
<example compact="compact">
ln -fs gcc $(prefix)/bin/cc
ln -fs gcc debian/tmp/usr/bin/cc
<p>
A symbolic link pointing to a compressed file should always
have the same file extension as the referenced file. (For
- example, if a file <tt>foo.gz</tt> is referenced by a
+ example, if a file <file>foo.gz</file> is referenced by a
symbolic link, the filename of the link has to end with
- `<tt>.gz</tt>' too, as in <tt>bar.gz</tt>.)
+ "<file>.gz</file>" too, as in <file>bar.gz</file>.)
</p>
</sect>
If a package needs any special device files that are not
included in the base system, it must call
<prgn>MAKEDEV</prgn> in the <prgn>postinst</prgn> script,
- after asking the user for permission to do so.</p>
+ after notifying the user<footnote>
+ <p>
+ This notification could be done via a (low-priority)
+ debconf message, or an echo (printf) statement.
+ </p>
+ </footnote>
+ .</p>
<p>
Packages must not remove any device files in the
<p>
Debian uses the serial devices
- <tt>/dev/ttyS*</tt>. Programs using the old
- <tt>/dev/cu*</tt> devices should be changed to use
- <tt>/dev/ttyS*</tt>.</p>
+ <file>/dev/ttyS*</file>. Programs using the old
+ <file>/dev/cu*</file> devices should be changed to use
+ <file>/dev/ttyS*</file>.</p>
</sect>
- <sect id="config files">
+ <sect id="config-files">
<heading>Configuration files</heading>
<sect1>
<heading>Definitions</heading>
<p>
Note that a script that embeds configuration information
- (such as most of the files in <tt>/etc/default</tt> and
- <tt>/etc/cron.{daily,weekly,monthly}</tt>) is de-facto a
+ (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.
</p>
</sect1>
<heading>Location</heading>
<p>
Any configuration files created or used by your package
- must reside in <tt>/etc</tt>. If there are several you
- should consider creating a subdirectory of <tt>/etc</tt>
+ must reside in <file>/etc</file>. If there are several,
+ consider creating a subdirectory of <file>/etc</file>
named after your package.</p>
<p>
If your package creates or uses configuration files
- outside of <tt>/etc</tt>, and it is not feasible to modify
- the package to use the <tt>/etc</tt>, you should still put
- the files in <tt>/etc</tt> and create symbolic links to
- those files from the location that the package
- requires.</p>
+ outside of <file>/etc</file>, and it is not feasible to modify
+ the package to use <file>/etc</file> directly, put the files
+ in <file>/etc</file> and create symbolic links to those files
+ from the location that the package requires.</p>
</sect1>
<sect1>
<p>
A common practice is to create a script called
- <tt><var>package</var>-configure</tt> and have the
+ <file><var>package</var>-configure</file> and have the
package's <prgn>postinst</prgn> call it if and only if the
configuration file does not already exist. In certain
cases it is useful for there to be an example or template
file which the maintainer scripts use. Such files should
- be in <tt>/usr/share/<var>package</var></tt> or
- <tt>/usr/lib/<var>package</var></tt> (depending on whether
+ be in <file>/usr/share/<var>package</var></file> or
+ <file>/usr/lib/<var>package</var></file> (depending on whether
they are architecture-independent or not). There should
be symbolic links to them from
- <tt>/usr/share/doc/<var>package</var>/examples</tt> if
+ <file>/usr/share/doc/<var>package</var>/examples</file> if
they are examples, and should be perfectly ordinary
<prgn>dpkg</prgn>-handled files (<em>not</em>
- <tt>conffiles</tt>).
+ configuration files).
</p>
<p>
<tt>conffile</tt> must be tagged as <em>conflicting</em>
with each other. (This is an instance of the general rule
about not sharing files. Note that neither alternatives
- nor diversions are likely to be appropriate in this case.)
+ nor diversions are likely to be appropriate in this case;
+ in particular, <prgn>dpkg</prgn> does not handle diverted
+ <tt>conffile</tt>s well.)
</p>
<p>
<heading>User configuration files ("dotfiles")</heading>
<p>
- The files in <tt>/etc/skel</tt> will automatically be
+ The files in <file>/etc/skel</file> will automatically be
copied into new user accounts by <prgn>adduser</prgn>.
No other program should reference the files in
- <tt>/etc/skel</tt>.
+ <file>/etc/skel</file>.
</p>
<p>
Therefore, if a program needs a dotfile to exist in
- advance in <tt>$HOME</tt> to work sensibly, that dotfile
- should be installed in <tt>/etc/skel</tt> and treated as a
+ advance in <file>$HOME</file> to work sensibly, that dotfile
+ should be installed in <file>/etc/skel</file> and treated as a
configuration file.
</p>
<p>
However, programs that require dotfiles in order to
- operate sensibly (dotfiles that they do not create
- themselves automatically, that is) are a bad thing.
+ operate sensibly are a bad thing, unless they do create
+ the dotfiles themselves automatically.
+ </p>
+
+ <p>
Furthermore, programs should be configured by the Debian
- default installation as behave as closely to the upstream
+ default installation to behave as closely to the upstream
default behaviour as possible.
</p>
Therefore, if a program in a Debian package needs to be
configured in some way in order to operate sensibly, that
should be done using a site-wide configuration file placed
- in <tt>/etc</tt>. Only if the program doesn't support a
+ in <file>/etc</file>. Only if the program doesn't support a
site-wide default configuration and the package maintainer
doesn't have time to add it may a default per-user file be
- placed in <tt>/etc/skel</tt>.
+ placed in <file>/etc/skel</file>.
</p>
<p>
- <tt>/etc/skel</tt> should be as empty as we can make it.
+ <file>/etc/skel</file> should be as empty as we can make it.
This is particularly true because there is no easy (or
necessarily desirable) mechanism for ensuring that the
appropriate dotfiles are copied into the accounts of
<heading>Log files</heading>
<p>
Log files should usually be named
- <tt>/var/log/<var>package</var>.log</tt>. If you have many
+ <file>/var/log/<var>package</var>.log</file>. If you have many
log files, or need a separate directory for permission
- reasons (<tt>/var/log</tt> is writable only by
- <tt>root</tt>), you should usually create a directory named
- <tt>/var/log/<var>package</var></tt> and place your log
+ reasons (<file>/var/log</file> is writable only by
+ <file>root</file>), you should usually create a directory named
+ <file>/var/log/<var>package</var></file> and place your log
files there.
</p>
Log files must be rotated occasionally so that they don't
grow indefinitely; the best way to do this is to drop a log
rotation configuration file into the directory
- <tt>/etc/logrotate.d</tt> and use the facilities provided by
+ <file>/etc/logrotate.d</file> and use the facilities provided by
logrotate.<footnote>
<p>
The traditional approach to log files has been to set up
The use of <prgn>logrotate</prgn>, a program developed
by Red Hat, is better, as it centralizes log management.
It has both a configuration file
- (<tt>/etc/logrotate.conf</tt>) and a directory where
+ (<file>/etc/logrotate.conf</file>) and a directory where
packages can drop their individual log rotation
- configurations (<tt>/etc/logrotate.d</tt>).
+ configurations (<file>/etc/logrotate.d</file>).
</p>
</footnote>
Here is a good example for a logrotate config
file (for more information see <manref name="logrotate"
section="8">):
<example compact="compact">
-/var/log/foo/* {
+/var/log/foo/*.log {
rotate 12
weekly
compress
endscript
}
</example>
- This rotates all files under <tt>/var/log/foo</tt>, saves 12
+ This rotates all files under <file>/var/log/foo</file>, saves 12
compressed generations, and forces the daemon to reload its
configuration information after the log rotation.
</p>
allocated one. Once you have been allocated one you must
either make the package depend on a version of the
<tt>base-passwd</tt> package with the id present in
- <tt>/etc/passwd</tt> or <tt>/etc/group</tt>, or arrange for
+ <file>/etc/passwd</file> or <file>/etc/group</file>, or arrange for
your package to create the user or group itself with the
correct id (using <tt>adduser</tt>) in its
<prgn>preinst</prgn> or <prgn>postinst</prgn>. (Doing it in
that a dynamically allocated id can be used. In this case
you should choose an appropriate user or group name,
discussing this on <prgn>debian-devel</prgn> and checking
- with the base system maintainer that it is unique and that
+ with the <package/base-passwd/ maintainer that it is unique and that
they do not wish you to use a statically allocated id
instead. When this has been checked you must arrange for
your package to create the user or group if necessary using
<p>
If a program needs to specify an <em>architecture specification
- string</em> in some place, the following format should be used:
- <example compact="compact">
-<var>arch</var>-<var>os</var>
- </example><footnote>
+ string</em> in some place, the following format should be
+ used: <var>arch</var>-<var>os</var><footnote>
<p>
The following architectures and operating systems are
currently recognised by <prgn>dpkg-archictecture</prgn>.
<tt>openbsd</tt>. Use of <tt>gnu</tt> in this string is
reserved for the GNU/Hurd operating system.
</p>
- </footnote>
+ </footnote>.
</p>
<p>
<heading>Daemons</heading>
<p>
- The configuration files <tt>/etc/services</tt>,
- <tt>/etc/protocols</tt>, and <tt>/etc/rpc</tt> are managed
+ The configuration files <file>/etc/services</file>,
+ <file>/etc/protocols</file>, and <file>/etc/rpc</file> are managed
by the <prgn>netbase</prgn> package and must not be modified
by other packages.
</p>
</p>
<p>
- The configuration file <tt>/etc/inetd.conf</tt> must not be
+ The configuration file <file>/etc/inetd.conf</file> must not be
modified by the package's scripts except via the
<prgn>update-inetd</prgn> script or the
- <tt>DebianNet.pm</tt> Perl module. See their documentation
+ <file>DebianNet.pm</file> Perl module. See their documentation
for details on how to add entries.
</p>
<p>
If a package wants to install an example entry into
- <tt>/etc/inetd.conf</tt>, the entry must be preceded with
+ <file>/etc/inetd.conf</file>, the entry must be preceded with
exactly one hash character (<tt>#</tt>). Such lines are
- treated as `commented out by user' by the
+ treated as "commented out by user" by the
<prgn>update-inetd</prgn> script and are not changed or
activated during package updates.
</p>
</p>
<p>
- The files <tt>/var/run/utmp</tt>, <tt>/var/log/wtmp</tt> and
- <tt>/var/log/lastlog</tt> must be installed writeable by
+ The files <file>/var/run/utmp</file>, <file>/var/log/wtmp</file> and
+ <file>/var/log/lastlog</file> must be installed writeable by
group <tt>utmp</tt>. Programs which need to modify those
files must be installed setgid <tt>utmp</tt>.
</p>
Thus, every program that launches an editor or pager must
use the EDITOR or PAGER environment variable to determine
the editor or pager the user wishes to use. If these
- variables are not set, the programs <tt>/usr/bin/editor</tt>
- and <tt>/usr/bin/pager</tt> should be used, respectively.
+ variables are not set, the programs <file>/usr/bin/editor</file>
+ and <file>/usr/bin/pager</file> should be used, respectively.
</p>
<p>
These two files are managed through the <prgn>dpkg</prgn>
- `alternatives' mechanism. Thus every package providing an
+ "alternatives" mechanism. Thus every package providing an
editor or pager must call the
<prgn>update-alternatives</prgn> script to register these
programs.
<p>
If it is very hard to adapt a program to make use of the
EDITOR or PAGER variables, that program may be configured to
- use <tt>/usr/bin/sensible-editor</tt> and
- <tt>/usr/bin/sensible-pager</tt> as the editor or pager
+ use <file>/usr/bin/sensible-editor</file> and
+ <file>/usr/bin/sensible-pager</file> as the editor or pager
program respectively. These are two scripts provided in the
Debian base system that check the EDITOR and PAGER variables
and launch the appropriate program, and fall back to
- <tt>/usr/bin/editor</tt> and <tt>/usr/bin/pager</tt> if the
+ <file>/usr/bin/editor</file> and <file>/usr/bin/pager</file> if the
variable is not set.
</p>
A program may also use the VISUAL environment variable to
determine the user's choice of editor. If it exists, it
should take precedence over EDITOR. This is in fact what
- <tt>/usr/bin/sensible-editor</tt> does.
+ <file>/usr/bin/sensible-editor</file> does.
</p>
<p>
<p>
HTML documents for a package are stored in
- <tt>/usr/share/doc/<var>package</var></tt> but should
- be accessed via symlinks as
- <tt>/usr/doc/<var>package</var></tt><footnote>
- <p>
- for backward compatibility; see <ref
- id="usrdoc">
- </p>
- </footnote>
+ <file>/usr/share/doc/<var>package</var></file>
and can be referred to as
<example compact="compact">
http://localhost/doc/<var>package</var>/<var>filename</var>
</example>
</p>
+ <p>
+ The web server should restrict access to the document
+ tree so that only clients on the same host can read
+ the documents. If the web server does not support such
+ access controls, then it should not provide access at
+ all, or ask about providing access during installation.
+ </p>
</item>
<item><p>Web Document Root</p>
</p>
<p>
- The mail spool is <tt>/var/mail</tt> and the interface to
- send a mail message is <tt>/usr/sbin/sendmail</tt> (as per
+ The mail spool is <file>/var/mail</file> and the interface to
+ send a mail message is <file>/usr/sbin/sendmail</file> (as per
the FHS). On older systems, the mail spool may be
- physically located in <tt>/var/spool/mail</tt>, but all
+ physically located in <file>/var/spool/mail</file>, but all
access to the mail spool should be via the
- <tt>/var/mail</tt> symlink. The mail spool is part of the
+ <file>/var/mail</file> symlink. The mail spool is part of the
base system and not part of the MTA package.
</p>
using this privilege).</p>
<p>
- <tt>/etc/aliases</tt> is the source file for the system mail
+ <file>/etc/aliases</file> is the source file for the system mail
aliases (e.g., postmaster, usenet, etc.), it is the one
which the sysadmin and <prgn>postinst</prgn> scripts may
- edit. After <tt>/etc/aliases</tt> is edited the program or
+ edit. After <file>/etc/aliases</file> is edited the program or
human editing it must call <prgn>newaliases</prgn>. All MTA
packages must come with a <prgn>newaliases</prgn> program,
even if it does nothing, but older MTA packages did not do
<p>
The <prgn>rmail</prgn> program used by UUCP
- for incoming mail should be <tt>/usr/sbin/rmail</tt>.
+ for incoming mail should be <file>/usr/sbin/rmail</file>.
Likewise, <prgn>rsmtp</prgn>, for receiving
- batch-SMTP-over-UUCP, should be <tt>/usr/sbin/rsmtp</tt> if it
+ batch-SMTP-over-UUCP, should be <file>/usr/sbin/rsmtp</file> if it
is supported.</p>
<p>
If your package needs to know what hostname to use on (for
example) outgoing news and mail messages which are generated
- locally, you should use the file <tt>/etc/mailname</tt>. It
+ locally, you should use the file <file>/etc/mailname</file>. It
will contain the portion after the username and <tt>@</tt>
(at) sign for email addresses of users on the machine
(followed by a newline).
may wish to prompt the user even if it finds that this file
exists. If the file does not exist, the package should
prompt the user for the value (preferably using
- <prgn>debconf</prgn>) and store it in <tt>/etc/mailname</tt>
+ <prgn>debconf</prgn>) and store it in <file>/etc/mailname</file>
as well as using it in the package's configuration. The
prompt should make it clear that the name will not just be
used by that package. For example, in this situation the
<tt>inn</tt> package could say something like:
<example compact="compact">
-Please enter the `mail name' of your system. This is the
+Please enter the "mail name" of your system. This is the
hostname portion of the address to be shown on outgoing
news and mail messages. The default is
<var>syshostname</var>, your system's host name. Mail
-name [`<var>syshostname</var>']:
+name ["<var>syshostname</var>"]:
</example>
where <var>syshostname</var> is the output of <tt>hostname
--fqdn</tt>.
<p>
All the configuration files related to the NNTP (news)
servers and clients should be located under
- <tt>/etc/news</tt>.</p>
+ <file>/etc/news</file>.</p>
<p>
There are some configuration issues that apply to a number
are:
<taglist>
- <tag><tt>/etc/news/organization</tt></tag>
+ <tag><file>/etc/news/organization</file></tag>
<item><p>A string which should appear as the
organization header for all messages posted
by NNTP clients on the machine</p></item>
- <tag><tt>/etc/news/server</tt></tag>
+ <tag><file>/etc/news/server</file></tag>
<item><p>Contains the FQDN of the upstream NNTP
server, or localhost if the local machine is
an NNTP server.</p></item>
in their control data that they provide the virtual
package <tt>x-terminal-emulator</tt>. They should also
register themselves as an alternative for
- <tt>/usr/bin/x-terminal-emulator</tt>, with a priority of
+ <file>/usr/bin/x-terminal-emulator</file>, with a priority of
20.
</p>
"view" in a multiple-document interface (MDI).
</p>
</footnote>
- and runs the specified <var>command</var>.
+ and runs the specified <var>command</var>,
+ interpreting the entirity of the rest of the command
+ line as a command to pass straight to exec, in the
+ manner that <tt>xterm</tt> does.
</p></item>
<item><p>
their control data that they provide the virtual package
<tt>x-window-manager</tt>. They should also register
themselves as an alternative for
- <tt>/usr/bin/x-window-manager</tt>, with a priority
+ <file>/usr/bin/x-window-manager</file>, with a priority
calculated as follows:
<list compact="compact">
<item><p>Start with a priority of 20.</p></item>
points.
</p>
</item>
+ <item>
+ <p>
+ If the window manager complies with <url
+ id="http://www.freedesktop.org/standards/wm-spec.html"
+ name="The Window Manager Specification Project">,
+ written by the <url id="http://www.freedesktop.org"
+ name="Free Desktop Group">, add 40 points.
+ </p>
+ </item>
<item>
<p>
<item>
<p>
Fonts of any type supported by the X Window System
- must be be in a separate binary package from any
+ must be in a separate binary package from any
executables, libraries, or documentation (except
that specific to the fonts shipped, such as their
license information). If one or more of the fonts
<p>
BDF fonts must be converted to PCF fonts with the
<prgn>bdftopcf</prgn> utility (available in the
- <tt>xutils</tt> package, <tt>gzip</tt>ped, and
+ <tt>xutils</tt> package, <prgn>gzip</prgn>ped, and
placed in a directory that corresponds to their
resolution:
<list compact="compact">
<item><p>
100 dpi fonts must be placed in
- <tt>/usr/X11R6/lib/X11/fonts/100dpi/</tt>.
+ <file>/usr/X11R6/lib/X11/fonts/100dpi/</file>.
</p></item>
<item><p>
75 dpi fonts must be placed in
- <tt>/usr/X11R6/lib/X11/fonts/75dpi/</tt>.
+ <file>/usr/X11R6/lib/X11/fonts/75dpi/</file>.
</p></item>
<item><p>
Character-cell fonts, cursor fonts, and other
low-resolution fonts must be placed in
- <tt>/usr/X11R6/lib/X11/fonts/misc/</tt>.
+ <file>/usr/X11R6/lib/X11/fonts/misc/</file>.
</p></item>
</list>
</p>
<item><p>
Speedo fonts must be placed in
- <tt>/usr/X11R6/lib/X11/fonts/Speedo/</tt>.
+ <file>/usr/X11R6/lib/X11/fonts/Speedo/</file>.
</p></item>
<item><p>
Type 1 fonts must be placed in
- <tt>/usr/X11R6/lib/X11/fonts/Type1/</tt>. If font
+ <file>/usr/X11R6/lib/X11/fonts/Type1/</file>. If font
metric files are available, they must be placed here
as well.
</p></item>
<item>
<p>
- Subdirectories of <tt>/usr/X11R6/lib/X11/fonts/</tt>
+ Subdirectories of <file>/usr/X11R6/lib/X11/fonts/</file>
other than those listed above must be neither
- created nor used. (The <tt>PEX</tt>, <tt>CID</tt>,
- and <tt>cyrillic</tt> directories are excepted for
+ created nor used. (The <file>PEX</file>, <file>CID</file>,
+ and <file>cyrillic</file> directories are excepted for
historical reasons, but installation of files into
these directories remains discouraged.)
</p>
<p>
Font packages may, instead of placing files directly
in the X font directories listed above, provide
- symbolic links in the font directory which point to
+ symbolic links in that font directory pointing to
the files' actual location in the filesystem. Such
a location must comply with the FHS.
</p>
<item>
<p>
- Fonts destined for the <tt>misc</tt> subdirectory
+ Fonts destined for the <file>misc</file> subdirectory
should not be included in the same package as 75dpi
or 100dpi fonts; instead, they should be provided in
a separate package with <tt>-misc</tt> appended to
<item>
<p>
Font packages must not provide the files
- <tt>fonts.dir</tt>, <tt>fonts.alias</tt>, or
- <tt>fonts.scale</tt> in a font directory:
+ <file>fonts.dir</file>, <file>fonts.alias</file>, or
+ <file>fonts.scale</file> in a font directory:
<list>
<item><p>
- <tt>fonts.dir</tt> files must not be provided at all.
+ <file>fonts.dir</file> files must not be provided at all.
</p></item>
<item>
<p>
- <tt>fonts.alias</tt> and <tt>fonts.scale</tt>
+ <file>fonts.alias</file> and <file>fonts.scale</file>
files, if needed, should be provided in the
directory
- <tt>/etc/X11/fonts/<var>fontdir</var>/<var>package</var>.<var>extension</var></tt>,
+ <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
- <tt>/usr/X11R6/lib/X11/fonts/</tt> where the
+ <file>/usr/X11R6/lib/X11/fonts/</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>
<p>
Font packages that provide one or more
- <tt>fonts.scale</tt> files as described above must
+ <file>fonts.scale</file> files as described above must
invoke <prgn>update-fonts-scale</prgn> on each
directory into which they installed fonts
<em>before</em> invoking
<item>
<p>
Font packages that provide one or more
- <tt>fonts.alias</tt> files as described above must
+ <file>fonts.alias</file> files as described above must
invoke <prgn>update-fonts-alias</prgn> on each
directory into which they installed fonts. This
invocation must occur in both the
<p>
Application defaults files must be installed in the
- directory <tt>/etc/X11/app-defaults/</tt> (use of a
- localized subdirectory of <tt>/etc/X11/</tt> as described
+ directory <file>/etc/X11/app-defaults/</file> (use of a
+ localized subdirectory of <file>/etc/X11/</file> as described
in the <em>X Toolkit Intrinsics - C Language
Interface</em> manual is also permitted). They must be
registered as <tt>conffile</tt>s or handled as
configuration files. Packages must not provide the
- directory <tt>/usr/X11R6/lib/X11/app-defaults/</tt>.
+ directory <file>/usr/X11R6/lib/X11/app-defaults/</file>.
</p>
<p>
Customization of programs' X resources may also be
supported with the provision of a file with the same name
as that of the package placed in the
- <tt>/etc/X11/Xresources/</tt> directory, which must
+ <file>/etc/X11/Xresources/</file> directory, which must
registered as a <tt>conffile</tt> or handled as a
configuration file.<footnote>
<p>
</p>
</footnote>
<em>Important:</em> packages that install files into the
- <tt>/etc/X11/Xresources/</tt> directory must conflict with
+ <file>/etc/X11/Xresources/</file> directory must conflict with
<tt>xbase (<< 3.3.2.3a-2)</tt>; if this is not done
it is possible for the installing package to destroy a
- previously-existing <tt>/etc/X11/Xresources</tt> file
+ previously-existing <file>/etc/X11/Xresources</file> file
which had been customized by the system administrator.
</p>
</sect1>
<p>
Packages using the X Window System should not be
- configured to install files under the <tt>/usr/X11R6/</tt>
+ configured to install files under the <file>/usr/X11R6/</file>
directory unless they use <prgn>imake</prgn>. The
- <tt>/usr/X11R6/</tt> directory hierarchy should be
+ <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 <tt>/usr/X11R6/</tt>
+ packages may transition out of the <file>/usr/X11R6/</file>
directory at the maintainer's discretion.<footnote>
<p>
<prgn>Imake</prgn>-using programs are exempt because,
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 <tt>/usr/X11R7/</tt>,
- <tt>/usr/X12/</tt>, or just plain <tt>/usr/</tt>, all
+ 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>
Programs that use GNU <prgn>autoconf</prgn> and
<prgn>automake</prgn> are usually easily configured at
- compile time to use <tt>/usr/</tt> instead of
- <tt>/usr/X11R6/</tt>, and this should be done whenever
+ compile time to use <file>/usr/</file> instead of
+ <file>/usr/X11R6/</file>, and this should be done whenever
possible. Configuration files for window managers and
display managers should be placed in a subdirectory of
- <tt>/etc/X11/</tt> corresponding to the package name due
+ <file>/etc/X11/</file> corresponding to the package name due
to these programs' tight integration with the mechanisms
of the X Window System. Application-level programs should
- use the <tt>/etc/</tt> directory unless otherwise mandated
+ use the <file>/etc/</file> directory unless otherwise mandated
by policy. The installation of files into subdirectories
- of <tt>/usr/X11R6/include/X11/</tt> and
- <tt>/usr/X11R6/lib/X11/</tt> is permitted but discouraged;
+ of <file>/usr/X11R6/include/X11/</file> and
+ <file>/usr/X11R6/lib/X11/</file> is permitted but discouraged;
package maintainers should determine if subdirectories of
- <tt>/usr/lib/</tt> and <tt>/usr/share/</tt> can be used
+ <file>/usr/lib/</file> and <file>/usr/share/</file> can be used
instead. (The use of symbolic links from the
- <tt>X11R6</tt> directories to other FHS-compliant
+ <file>X11R6</file> directories to other FHS-compliant
locations is encouraged if the program is not easily
configured to look elsewhere for its files.) Packages
must not provide or install files into the directories
- <tt>/usr/bin/X11/</tt>, <tt>/usr/include/X11/</tt> or
- <tt>/usr/lib/X11/</tt>. Files within a package should,
+ <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
- <tt>/usr/X11R6/bin/</tt>, <tt>/usr/X11R6/include/X11/</tt>
- and <tt>/usr/X11R6/lib/X11/</tt>, if the resources being
+ <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.
</p>
<sect>
<heading>Perl programs and modules</heading>
+
<p>
- Perl programs and modules should follow the current Perl
- policy as defined in the file found on
- <ftpsite>ftp.debian.org</ftpsite> in
- <ftppath>/debian/doc/package-developer/perl-policy.txt.gz</ftppath>
- or your local mirror. In addition, it is included in the
- <tt>debian-policy</tt> package.
+ Perl programs and modules should follow the current Perl policy.
+ </p>
+
+ <p>
+ The Perl policy can be found in the <tt>perl-policy</tt>
+ files in the <tt>debian-policy</tt> package.
+ They are 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>.
</p>
</sect>
<heading>Emacs lisp programs</heading>
<p>
- Please refer to the `Debian Emacs Policy' (documented in
- <tt>debian-emacs-policy.gz</tt> of the
- <prgn>emacsen-common</prgn> package) for details of how to
+ Please refer to the "Debian Emacs Policy" for details of how to
package emacs lisp programs.
</p>
+
+ <p>
+ The Emacs policy is available in
+ <file>debian-emacs-policy.gz</file> of the
+ <package>emacsen-common</package> package.
+ It is also available from the Debian web mirrors at
+ <tt><url name="/doc/packaging-manuals/debian-emacs-policy"
+ id="http://www.debian.org/doc/packaging-manuals/debian-emacs-policy"></tt>.
+ </p>
</sect>
<sect>
<heading>Games</heading>
<p>
- The permissions on <tt>/var/games</tt> are mode 755, owner
+ The permissions on <file>/var/games</file> are mode 755, owner
<tt>root</tt> and group <tt>root</tt>.
</p>
-
+
<p>
Each game decides on its own security policy.</p>
data files or other static information made unreadable so
that they can only be accessed through set-id programs
provided. You should not do this in a Debian package: anyone can
- download the <tt>.deb</tt> file and read the data from it,
+ download the <file>.deb</file> file and read the data from it,
so there is no point making the files unreadable. Not
making the files unreadable also means that you don't have
to make so many programs set-id, which reduces the risk of a
<p>
As described in the FHS, binaries of games should be
- installed in the directory <tt>/usr/games</tt>. This also
+ installed in the directory <file>/usr/games</file>. This also
applies to games that use the X Window System. Manual pages
for games (X and non-X games) should be installed in
- <tt>/usr/share/man/man6</tt>.</p>
+ <file>/usr/share/man/man6</file>.</p>
</sect>
</chapt>
<p>
You should install manual pages in <prgn>nroff</prgn> source
- form, in appropriate places under <tt>/usr/share/man</tt>. You
- should only use sections 1 to 9 (see the FHS for more
- details). You must not install a preformatted `cat
- page'.</p>
+ 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".
+ </p>
<p>
Each program, utility, and function should have an
- associated manpage included in the same package. It is
+ associated manual page included in the same package. It is
suggested that all configuration files also have a manual
- page included as well.
+ page included as well. Manual pages for protocols and other
+ auxiliary things are optional.
</p>
<p>
- If no manual page is available for a particular program,
- utility, function or configuration file and this is reported as a bug on
- debian-bugs, a symbolic link from the requested manual page
- to the <manref name="undocumented" section="7"> manual page
- may be provided. This symbolic link can be created from
- <tt>debian/rules</tt> like this:
- <example compact="compact">
-ln -s ../man7/undocumented.7.gz \
-debian/tmp/usr/share/man/man[1-9]/the_requested_manpage.[1-9].gz
- </example>
- This manpage claims that the lack of a manpage has been
- reported as a bug, so you may only do this if it really has
- (you can report it yourself, if you like). Do not close the
- bug report until a proper manpage is available.</p>
+ If no manual page is available, this is considered as a bug
+ 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>
+ <p>
+ 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">,
+ <manref name="man" section="7">, the examples
+ created by <prgn>debmake</prgn> or <prgn>dh_make</prgn>,
+ the helper programs <prgn>help2man</prgn>, or the
+ directory <file>/usr/share/doc/man-db/examples</file>.
+ </p>
+ </footnote>
+ </p>
<p>
You may forward a complaint about a missing manpage to the
not in general consider the lack of a manpage 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>
+ anyway.
+ </p>
<p>
- Manual pages should be installed compressed using <tt>gzip
- -9</tt>.</p>
+ Manual pages should be installed compressed using <tt>gzip -9</tt>.
+ </p>
<p>
If one manpage needs to be accessible via several names it
- is better to use a symbolic link than the <tt>.so</tt>
+ 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 <tt>.so</tt> to
+ 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 <tt>.so</tt> directives. The filename
- in a <tt>.so</tt> in a manpage should be relative to the
+ 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
- <tt>/usr/share/man</tt>). If you do not create any links
+ <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,
then you should not rely on <prgn>man</prgn> finding your
<heading>Info documents</heading>
<p>
- Info documents should be installed in <tt>/usr/share/info</tt>.
- They should be compressed with <tt>gzip -9</tt>.</p>
+ Info documents should be installed in <file>/usr/share/info</file>.
+ They should be compressed with <tt>gzip -9</tt>.
+ </p>
<p>
- Your package should call <prgn>install-info</prgn> to update the Info
- <tt>dir</tt>
- file, in its <prgn>postinst</prgn> script:
+ Your package should call <prgn>install-info</prgn> to update
+ the Info <file>dir</file> file in its <prgn>postinst</prgn>
+ script when called with a <tt>configure</tt> argument, for
+ example:
<example compact="compact">
install-info --quiet --section Development Development \
-/usr/share/info/foobar.info
+ /usr/share/info/foobar.info
</example></p>
<p>
It is a good idea to specify a section for the location of
your program; this is done with the <tt>--section</tt>
switch. To determine which section to use, you should look
- at <tt>/usr/share/info/dir</tt> on your system and choose the most
+ at <file>/usr/share/info/dir</file> on your system and choose the most
relevant (or create a new section if none of the current
sections are relevant). Note that the <tt>--section</tt>
flag takes two arguments; the first is a regular expression
the second is used when creating a new one.</p>
<p>
- You should remove the entries in the <prgn>prerm</prgn> script:
+ You should remove the entries in the <prgn>prerm</prgn>
+ script when called with a <tt>remove</tt> argument:
<example compact="compact">
install-info --quiet --remove /usr/share/info/foobar.info
</example></p>
<p>
If <prgn>install-info</prgn> cannot find a description entry
in the Info file you must supply one. See <manref
- name="install-info" section="8"> for details.</p>
+ name="install-info" section="8"> for details.</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 a directory
- <tt>/usr/share/doc/<var>package</var></tt>, where
+ 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.</p>
+ compressed with <tt>gzip -9</tt> unless it is small.
+ </p>
<p>
If a package comes with large amounts of documentation which
<p>
It is often a good idea to put text information files
- (<tt>README</tt>s, changelogs, and so forth) that come with
- the source package in <tt>/usr/share/doc/<var>package</var></tt>
+ (<file>README</file>s, changelogs, and so forth) that come with
+ the source package in <file>/usr/share/doc/<var>package</var></file>
in the binary package. However, you don't need to install
the instructions for building and installing the package, of
course!</p>
<p>
- Files in <tt>/usr/share/doc</tt> should not be referenced by
- any program, and the system administrator should be able to
- delete them without causing any programs to break. Any files
- that are referenced by programs but are also useful as
- standalone documentation should be installed under
- <tt>/usr/share/<var>package</var>/</tt> and symlinked in
- <tt>/usr/share/doc/<var>package</var>/</tt>.
+ Packages must not require the existance of any files in
+ <file>/usr/share/doc/</file> in order to function
+ <footnote>
+ <p>
+ The system administrator should be able to
+ delete files in <file>/usr/share/doc/</file> without causing
+ any programs to break.
+ </p>
+ </footnote>.
+ Any files that are referenced by programs but are also
+ useful as standalone 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>
- </sect>
-
- <sect id="usrdoc">
- <heading>Accessing the documentation</heading>
+ <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.
+ </p>
<p>
Former Debian releases placed all additional documentation
- in <tt>/usr/doc/<var>package</var></tt>. To realize a
- smooth migration to
- <tt>/usr/share/doc/<var>package</var></tt>, each package
- must maintain a symlink <tt>/usr/doc/<var>package</var></tt>
- that points to the new location of its documentation in
- <tt>/usr/share/doc/<var>package</var></tt><footnote>These
- symlinks will be removed in the future, but they have to be
- there for compatibility reasons until all packages have
- moved and the policy is changed accordingly.</footnote>.
- The symlink must be created when the package is installed;
- it cannot be contained in the package itself due to problems
- with <prgn>dpkg</prgn>. One reasonable way to accomplish
- this is to put the following in the package's
- <prgn>postinst</prgn>:
- <example compact="compact">
-if [ "$1" = "configure" ]; then
- if [ -d /usr/doc -a ! -e /usr/doc/#PACKAGE# \
- -a -d /usr/share/doc/#PACKAGE# ]; then
- ln -sf ../share/doc/#PACKAGE# /usr/doc/#PACKAGE#
- fi
-fi
- </example>
- And the following in the package's <prgn>prerm</prgn>:
- <example compact="compact">
-if [ \( "$1" = "upgrade" -o "$1" = "remove" \) \
- -a -L /usr/doc/#PACKAGE# ]; then
- rm -f /usr/doc/#PACKAGE#
-fi
- </example>
+ in <file>/usr/doc/<var>package</var></file>. This has been
+ changed to <file>/usr/share/doc/<var>package</var></file>,
+ and packages must not put documentation in the directory
+ <file>/usr/doc/<var>package</var></file>. <footnote>
+ <p>At this phase of the transition, we no longer require a
+ symbolic link in <file>/usr/doc/</file>. At a later point,
+ policy shall change to make the symbolic links a bug.</p>
+ </footnote>
</p>
</sect>
<p>
If your package comes with extensive documentation in a
- mark up format that can be converted to various other formats
+ markup format that can be converted to various other formats
you should if possible ship HTML versions in a binary
package, in the directory
- <tt>/usr/share/doc/<var>appropriate package</var></tt> or its
- subdirectories.<footnote>
- <p>The rationale: The important thing here is that HTML
+ <file>/usr/share/doc/<var>appropriate-package</var></file> or
+ its subdirectories.<footnote>
+ <p>
+ The rationale: The important thing here is that HTML
docs should be available in <em>some</em> package, not
- necessarily in the main binary package, though. </p>
+ necessarily in the main binary package.
+ </p>
</footnote>
</p>
<p>
- Other formats such as PostScript may be provided at your
- option.</p>
+ Other formats such as PostScript may be provided at the
+ package maintainer's discretion.
+ </p>
</sect>
<sect id="copyrightfile">
<p>
Every package must be accompanied by a verbatim copy of its
copyright and distribution license in the file
- /usr/share/doc/<var>package</var>/copyright. This file must
- neither be compressed nor be a symbolic link.</p>
+ <file>/usr/share/doc/<var>package</var>/copyright</file>. This
+ file must neither be compressed nor be a symbolic link.
+ </p>
<p>
In addition, the copyright file must say where the upstream
- sources (if any) were obtained, and should explain briefly what
- modifications were made in the Debian version of the package
- compared to the upstream one. It should name the original
+ 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>
<p>
A copy of the file which will be installed in
- <tt>/usr/share/doc/<var>package</var>/copyright</tt> should be
- in <tt>debian/copyright</tt>.</p>
-
+ <file>/usr/share/doc/<var>package</var>/copyright</file> should
+ be in <file>debian/copyright</file> in the source package.
+ </p>
<p>
- /usr/share/doc/<var>package</var> may be a symbolic link to a
- directory in /usr/share/doc only if two packages both come from
- the same source and the first package has a "Depends"
- relationship on the second. These rules are important
- because copyrights must be extractable by mechanical
- means.</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. These rules are
+ important because copyrights must be extractable by
+ mechanical means.
+ </p>
<p>
Packages distributed under the UCB BSD license, the Artistic
license, the GNU GPL, and the GNU LGPL should refer to the
- files /usr/share/common-licenses/BSD,
- /usr/share/common-licenses/Artistic,
- /usr/share/common-licenses/GPL, and
- /usr/share/common-licenses/LGPL.<footnote>
- <p>
- Why "licenses" and not "copyright"? Because
- <tt>/usr/doc/copyright</tt> used to contain all the
- copyright files, plus the four common licenses GPL,
- LGPL, Artistic and BSD. Now individual copyright files
- for packages are no longer in a common directory. Once
- <tt>/usr/doc/copyright</tt> is almost empty it makes
- sense to rename "copyright" to "licenses"
- </p>
- <p>
- Why "common-licenses" and not "licenses"? Because if I
- put just "licenses" I'm sure I will receive a bug report
- saying "license foo is not included in the licenses
- directory. They are not all the licenses, just a few
- common ones. I could use /usr/share/doc/common-licenses
- but I think this is too long, and, after all, the GPL
- does not "document" anything, it is merely a license.
- </p>
- </footnote>
+ 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.
</p>
<p>
- You should not use the copyright file as a general <tt>README</tt>
+ You should not use the copyright file as a general <file>README</file>
file. If your package has such a file it should be
- installed in <tt>/usr/share/doc/<var>package</var>/README</tt> or
- <tt>README.Debian</tt> or some other appropriate place.</p>
+ installed in <file>/usr/share/doc/<var>package</var>/README</file> or
+ <file>README.Debian</file> or some other appropriate place.</p>
</sect>
<sect>
<p>
Any examples (configurations, source files, whatever),
should be installed in a directory
- <tt>/usr/share/doc/<var>package</var>/examples</tt>. These
+ <file>/usr/share/doc/<var>package</var>/examples</file>. These
files should not be referenced by any program: they're there
- for the benefit of the system administrator and users, as
- documentation only. Architecture-specific example files
+ for the benefit of the system administrator and users as
+ documentation only. Architecture-specific example files
should be installed in a directory
- <tt>/usr/lib/<var>package</var>/examples</tt>, and files in
- <tt>/usr/share/doc/<var>package</var>/examples</tt> symlink
- to files in it. Or the latter directory may be a symlink to
- the former.</p>
+ <file>/usr/lib/<var>package</var>/examples</file> with symbolic
+ links to them from
+ <file>/usr/share/doc/<var>package</var>/examples</file>, or the
+ latter directory itself may be a symbolic link to the
+ former.
+ </p>
+
+ <p>
+ If the purpose of a package is to provide examples, then the
+ example files may be installed into
+ <file>/usr/share/doc/<var>package</var></file>.
+ </p>
</sect>
- <sect id="instchangelog">
+ <sect id="changelogs">
<heading>Changelog files</heading>
- <p>
- Packages that are not Debian-native must contain a copy of
- <tt>debian/changelog</tt> file from the Debian source tree
- in <tt>/usr/share/doc/<var>package</var></tt> as
- <tt>changelog.Debian.gz</tt>. If an upstream changelog is
- available, it should be accessible as
- <tt>/usr/share/doc/<var>package</var>/changelog.gz</tt> in
- plain text. If the upstream changelog is distributed in
+ <p>
+ The Debian changelog file (<file>debian/changelog</file>) should
+ explain briefly what modifications were made in the Debian version
+ of the package compared to the upstream one. Other changes and
+ updates to the package should also be documented in this file.
+ </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>
+ The format of the <file>debian/changelog</file> file is described
+ in <ref id="dpkgchangelog">. In non-experimental packages you must
+ use a format for <file>debian/changelog</file> which is supported
+ by the most recent released version of <prgn>dpkg</prgn>.<footnote>
+ <p>
+ If you wish to use an alternative format, you may do so as
+ long as you include a parser for it in your source package.
+ The parser must have an API compatible with that expected by
+ <prgn>dpkg-genchanges</prgn> and <prgn>dpkg-gencontrol</prgn>.
+ If there is general interest in the new format, you should
+ contact the <package>dpkg</package> maintainer to have the
+ parser script for it included in the <prgn>dpkg</prgn>
+ package. (You will need to agree that the parser and its
+ manpage may be distributed under the GNU GPL, just as the rest
+ of <prgn>dpkg</prgn> is.)
+ </p>
+ </footnote>
+ </p>
+
+ <p>
+ Packages that are not Debian-native must contain a
+ compressed copy of the <file>debian/changelog</file> file from
+ the Debian source tree in
+ <file>/usr/share/doc/<var>package</var></file> with the name
+ <file>changelog.Debian.gz</file>.
+ </p>
+
+ <p>
+ If an upstream changelog is available, it should be accessible as
+ <file>/usr/share/doc/<var>package</var>/changelog.gz</file> in
+ plain text. If the upstream changelog is distributed in
HTML, it should be made available in that form as
- <tt>/usr/share/doc/<var>package</var>/changelog.html.gz</tt>
- and the <tt>changelog.gz</tt> should be generated using, eg,
- <tt>lynx -dump -nolist</tt>. If the upstream changelog files
- do not already conform to this naming convention, then this
- may be achieved either by renaming the files, or adding a
- symbolic link, at the maintainer's discretion.<footnote>
+ <file>/usr/share/doc/<var>package</var>/changelog.html.gz</file>
+ and a plain text <file>changelog.gz</file> should be generated
+ from it using, for example, <tt>lynx -dump -nolist</tt>. If
+ the upstream changelog files do not already conform to this
+ naming convention, then this may be achieved either by
+ renaming the files, or by adding a symbolic link, at the
+ maintainer's discretion.<footnote>
<p>
- Rationale: People should not have to look into two
- places for upstream changelogs merely because they are
- in HTML format.
+ Rationale: People should not have to look in places for
+ upstream changelogs merely because they are given
+ different names or are distributed in HTML format.
</p>
</footnote>
</p>
-
<p>
- All these files should be installed compressed using <tt>gzip -9</tt>,
- as they will become large with time even if they start out
- small.
+ All of these files should be installed compressed using
+ <tt>gzip -9</tt>, as they will become large with time even
+ if they start out small.
</p>
<p>
the Debian changelog and the upstream one because there is
no separate upstream maintainer then that changelog should
usually be installed as
- <tt>/usr/share/doc/<var>package</var>/changelog.gz</tt>; if
+ <file>/usr/share/doc/<var>package</var>/changelog.gz</file>; if
there is a separate upstream maintainer, but no upstream
changelog, then the Debian changelog should still be called
- <tt>changelog.Debian.gz</tt>.</p>
+ <file>changelog.Debian.gz</file>.</p>
+
</sect>
</chapt>
+
+ <appendix id="pkg-scope">
+ <heading>Introduction and scope of these appendices</heading>
+
+ <p>
+ These appendices are taken essentially verbatim from the
+ now-deprecated Packaging Manual, version 3.2.1.0. They are
+ the chapters which are likely to be of use to package
+ maintainers and which have not already been included in the
+ policy document itself. Most of these sections are very likely
+ not relevant to policy; they should be treated as
+ documentation for the packaging system. Please note that these
+ appendices are included for convenience, and for historical
+ reasons: they used to be part of policy package, and they have
+ not yet been incorporated into dpkg documentation. However,
+ they still have value, and hence they are presented here.
+ </p>
+ <p>
+ They have not yet been checked to ensure that they are
+ compatible with the contents of policy, and if there are any
+ contradictions, the version in the main policy document takes
+ precedence. The remaining chapters of the old Packaging
+ Manual have also not been read in detail to ensure that there
+ are not parts which have been left out. Both of these will be
+ done in due course.
+ </p>
+
+ <p>
+ <prgn>dpkg</prgn> is a suite of programs for creating binary
+ package files and installing and removing them on Unix
+ systems.<footnote>
+ <p>
+ <prgn>dpkg</prgn> is targetted primarily at Debian
+ GNU/Linux, but may work on or be ported to other
+ systems.
+ </p>
+ </footnote>
+ </p>
+
+ <p>
+ The binary packages are designed for the management of
+ installed executable programs (usually compiled binaries) and
+ their associated data, though source code examples and
+ documentation are provided as part of some packages.</p>
+
+ <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
+ <prgn>dpkg</prgn>, <prgn>dselect</prgn> et al. and the way
+ they interact with packages.</p>
+
+ <p>
+ It also documents the interaction between
+ <prgn>dselect</prgn>'s core and the access method scripts it
+ uses to actually install the selected packages, and describes
+ how to create a new access method.</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.
+ </p>
+
+ <p>
+ The utility programs which are provided with <prgn>dpkg</prgn>
+ 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.
+ </p>
+
+ <p>
+ It is assumed that the reader is reasonably familiar with the
+ <prgn>dpkg</prgn> System Administrators' manual.
+ Unfortunately this manual does not yet exist.
+ </p>
+
+ <p>
+ The Debian version of the FSF's GNU hello program is provided
+ as an example for people wishing to create Debian
+ packages. The Debian <prgn>debmake</prgn> package is
+ recommended as a very helpful tool in creating and maintaining
+ Debian packages. However, while the tools and examples are
+ helpful, they do not replace the need to read and follow the
+ Policy and Programmer's Manual.</p>
+ </appendix>
+
+ <appendix id="pkg-binarypkg"><heading>Binary packages (from old
+ Packaging Manual)
+ </heading>
+
+ <p>
+ The binary package has two main sections. The first part
+ consists of various control information files and scripts used
+ by <prgn>dpkg</prgn> when installing and removing. See <ref
+ id="pkg-controlarea">.
+ </p>
+
+ <p>
+ The second part is an archive containing the files and
+ directories to be installed.
+ </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.
+ </p>
+
+
+ <sect id="pkg-bincreating"><heading>Creating package files -
+ <prgn>dpkg-deb</prgn>
+ </heading>
+
+ <p>
+ All manipulation of binary package files is done by
+ <prgn>dpkg-deb</prgn>; it's the only program that has
+ knowledge of the format. (<prgn>dpkg-deb</prgn> may be
+ invoked by calling <prgn>dpkg</prgn>, as <prgn>dpkg</prgn>
+ will spot that the options requested are appropriate to
+ <prgn>dpkg-deb</prgn> and invoke that instead with the same
+ arguments.)
+ </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.
+ In Debian-format source packages this directory is usually
+ <file>debian/tmp</file>, relative to the top of the package's
+ source tree.
+ </p>
+
+ <p>
+ They should have the locations (relative to the root of the
+ directory tree you're constructing) ownerships and
+ permissions which you want them to have on the system when
+ they are installed.
+ </p>
+
+ <p>
+ With current versions of <prgn>dpkg</prgn> the uid/username
+ and gid/groupname mappings for the users and groups being
+ used should be the same on the system where the package is
+ built and the one where it is installed.
+ </p>
+
+ <p>
+ You need to add one special directory to the root of the
+ miniature filesystem 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>
+
+ <p>
+ The <prgn>DEBIAN</prgn> directory will not appear in the
+ filesystem archive of the package, and so won't be installed
+ by <prgn>dpkg</prgn> when the package is installed.
+ </p>
+
+ <p>
+ When you've prepared the package, you should invoke:
+ <example>
+ dpkg --build <var>directory</var>
+ </example>
+ </p>
+
+ <p>
+ This will build the package in
+ <file><var>directory</var>.deb</file>. (<prgn>dpkg</prgn> knows
+ that <tt>--build</tt> is a <prgn>dpkg-deb</prgn> option, so
+ it invokes <prgn>dpkg-deb</prgn> with the same arguments to
+ build the package.)
+ </p>
+
+ <p>
+ See the manpage <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>
+ dpkg-deb --info <var>filename</var>.deb
+ dpkg-deb --contents <var>filename</var>.deb
+ dpkg --contents <var>filename</var>.deb
+ </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
+ </example>
+ </p>
+ </sect>
+
+ <sect id="pkg-controlarea">
+ <heading>
+ Package control information files
+ </heading>
+
+ <p>
+ The control information portion of a binary package is a
+ collection of files with names known to <prgn>dpkg</prgn>.
+ It will treat the contents of these files specially - some
+ of them contain information used by <prgn>dpkg</prgn> when
+ installing or removing the package; others are scripts which
+ the package maintainer wants <prgn>dpkg</prgn> to run.
+ </p>
+
+ <p>
+ It is possible to put other files in the package control
+ area, but this is not generally a good idea (though they
+ will largely be ignored).
+ </p>
+
+ <p>
+ Here is a brief list of the control info files supported by
+ <prgn>dpkg</prgn> and a summary of what they're used for.
+ </p>
+
+ <p>
+ <taglist>
+ <tag><tt>control</tt>
+ <item>
+
+ <p>
+ This is the key description file used by
+ <prgn>dpkg</prgn>. It specifies the package's name
+ and version, gives its description for the user,
+ states its relationships with other packages, and so
+ forth. See <ref id="pkg-controlfile">.
+ </p>
+
+ <p>
+ It is usually generated automatically from information
+ in the source package by the
+ <prgn>dpkg-gencontrol</prgn> program, and with
+ assistance from <prgn>dpkg-shlibdeps</prgn>. See <ref
+ id="pkg-sourcetools">.</p>
+ </item>
+
+ <tag><tt>postinst</tt>, <tt>preinst</tt>, <tt>postrm</tt>,
+ <tt>prerm</tt>
+ </tag>
+ <item>
+
+ <p>
+ These are exectuable 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
+ or require more complicated processing than that
+ provided by <prgn>dpkg</prgn>. Details of when and
+ how they are called are in <ref
+ id="maintainerscripts">.
+ </p>
+
+ <p>
+ It is very important to make these scripts
+ idempotent.
+ <footnote>
+ <p>
+ That means that if it runs successfully or fails
+ and then you call it again it doesn't bomb out,
+ but just ensures that everything is the way it
+ ought to be.
+ </p>
+ </footnote> This is so that if an error occurs, the
+ user interrupts <prgn>dpkg</prgn> or some other
+ unforeseen circumstance happens you don't leave the
+ user with a badly-broken package.
+ </p>
+
+ <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
+ buffered.
+ </p>
+
+ <p>
+ Each script should return a zero exit status for
+ success, or a nonzero one for failure.</p>
+ </item>
+
+ <tag><tt>conffiles</tt>
+ </tag>
+ <item>
+
+ <p>
+ This file contains a list of configuration files which
+ are to be handled automatically by <prgn>dpkg</prgn>
+ (see <ref id="pkg-conffiles">). Note that not necessarily
+ every configuration file should be listed here.</p>
+ </item>
+
+ <tag><tt>shlibs</tt>
+ </tag>
+ <item>
+
+ <p>
+ This file contains a list of the shared libraries
+ supplied by the package, with dependency details for
+ each. This is used by <prgn>dpkg-shlibdeps</prgn>
+ when it determines what dependencies are required in a
+ package control file. The <tt>shlibs</tt> file format
+ is described on <ref id="shlibs">.
+ </p>
+ </item>
+ </taglist>
+ </p>
+
+ <sect id="pkg-controlfile">
+ <heading>
+ The main control information file: <tt>control</tt>
+ </heading>
+ <p>
+ The most important control information file used by
+ <prgn>dpkg</prgn> when it installs a package is
+ <tt>control</tt>. It contains all the package"s "vital
+ statistics".
+ </p>
+
+ <p>
+ The binary package control files of packages built from
+ Debian sources are made by a special tool,
+ <prgn>dpkg-gencontrol</prgn>, which reads
+ <file>debian/control</file> and <file>debian/changelog</file> to
+ find the information it needs. See <ref id="pkg-sourcepkg"> for
+ more details.
+ </p>
+
+ <p>
+ The fields in binary package control files are:
+ <list compact="compact">
+ <item>
+ <p><qref id="pkg-f-Package"><tt>Package</tt></qref> (mandatory)</p>
+ </item>
+ <item>
+ <p><qref id="versions"><tt>Version</tt></qref> (mandatory)</p>
+ </item>
+ <item><p><qref id="pkg-f-Architecture"><tt>Architecture</tt></qref>
+ (mandatory)
+ <footnote>
+ <p>
+ This field should appear in all packages, though
+ <prgn>dpkg</prgn> doesn't require it yet so that
+ old packages can still be installed.
+ </p>
+ </footnote>
+ </p>
+ </item>
+ <item>
+ <p><qref id="relationships"><tt>Depends</tt>,
+ <tt>Provides</tt> et al.</qref></p>
+ </item>
+ <item>
+ <p><qref id="pkg-f-Essential"><tt>Essential</tt></qref></p>
+ </item>
+ <item>
+ <p><qref id="pkg-f-Maintainer"><tt>Maintainer</tt></qref></p>
+ </item>
+ <item>
+ <p><qref id="pkg-f-classification"><tt>Section</tt>,
+ <tt>Priority</tt></qref></p>
+ </item>
+ <item>
+ <p><qref id="pkg-f-Source"><tt>Source</tt></qref></p>
+ </item>
+ <item>
+ <p><qref id="descriptions"><tt>Description</tt></qref></p>
+ </item>
+ <item>
+ <p>
+ <qref id="pkg-f-Installed-Size"><tt>Installed-Size</tt></qref>
+ </p>
+ </item>
+ </list>
+
+ <p>
+ A description of the syntax of control files and the purpose
+ of these fields is available in <ref id="pkg-controlfields">.
+ </p>
+ </sect>
+
+ <sect>
+ <heading>Time Stamps</heading>
+ <p>
+ Maintainers are encouraged to preserve the modification
+ times of the upstream source files in a package, as far as
+ is reasonably possible.
+ <footnote>
+ <p>
+ The rationale is that there is some information conveyed
+ by knowing the age of the file, for example, you could
+ recognize that some documentation is very old by looking
+ at the modification time, so it would be nice if the
+ modification time of the upstream source would be
+ preserved.
+ </p>
+ </footnote>
+ </p>
+ </sect>
+ </appendix>
+
+ <appendix id="pkg-sourcepkg">
+ <heading>Source packages (from old Packaging Manual) </heading>
+
+ <p>
+ The Debian binary packages in the distribution are generated
+ from Debian sources, which are in a special format to assist
+ the easy and automatic building of binaries.
+ </p>
+
+ <sect id="pkg-sourcetools">
+ <heading>Tools for processing source packages</heading>
+
+ <p>
+ Various tools are provided for manipulating source packages;
+ they pack and unpack sources and help build of binary
+ packages and help manage the distribution of new versions.
+ </p>
+
+ <p>
+ They are introduced and typical uses described here; see
+ <manref name="dpkg-source" section="1"> for full
+ documentation about their arguments and operation.
+ </p>
+
+ <p>
+ For examples of how to construct a Debian source package,
+ and how to use those utilities that are used by Debian
+ source packages, please see the <prgn>hello</prgn> example
+ package.
+ </p>
+
+ <sect1>
+ <heading>
+ <prgn>dpkg-source</prgn> - packs and unpacks Debian source
+ packages
+ </heading>
+
+ <p>
+ This program is frequently used by hand, and is also
+ called from package-independent automated building scripts
+ such as <prgn>dpkg-buildpackage</prgn>.
+ </p>
+
+ <p>
+ To unpack a package it is typically invoked with
+ <example>
+ dpkg-source -x <var>.../path/to/filename</var>.dsc
+ </example>
+ </p>
+
+ <p>
+ with the <file><var>filename</var>.tar.gz</file> and
+ <file><var>filename</var>.diff.gz</file> (if applicable) in
+ the same directory. It unpacks into
+ <file><var>package</var>-<var>version</var></file>, and if
+ applicable
+ <file><var>package</var>-<var>version</var>.orig</file>, in
+ the current directory.
+ </p>
+
+ <p>
+ To create a packed source archive it is typically invoked:
+ <example>
+ dpkg-source -b <var>package</var>-<var>version</var>
+ </example>
+ </p>
+
+ <p>
+ This will create the <file>.dsc</file>, <file>.tar.gz</file> and
+ <file>.diff.gz</file> (if appropriate) in the current
+ directory. <prgn>dpkg-source</prgn> does not clean the
+ source tree first - this must be done separately if it is
+ required.
+ </p>
+
+ <p>
+ See also <ref id="pkg-sourcearchives">.</p>
+ </sect1>
+
+
+ <sect1>
+ <heading>
+ <prgn>dpkg-buildpackage</prgn> - overall package-building
+ control script
+ </heading>
+
+ <p>
+ <prgn>dpkg-buildpackage</prgn> is a script which invokes
+ <prgn>dpkg-source</prgn>, the <file>debian/rules</file>
+ targets <tt>clean</tt>, <tt>build</tt> and
+ <tt>binary</tt>, <prgn>dpkg-genchanges</prgn> and
+ <prgn>pgp</prgn> to build a signed source and binary
+ package upload.
+ </p>
+
+ <p>
+ It is usually invoked by hand from the top level of the
+ built or unbuilt source directory. It may be invoked with
+ no arguments; useful arguments include:
+ <taglist compact="compact">
+ <tag><tt>-uc</tt>, <tt>-us</tt></tag>
+ <item>
+ <p>
+ Do not PGP-sign the <tt>.changes</tt> file or the
+ source package <tt>.dsc</tt> file, respectively.</p>
+ </item>
+ <tag><tt>-p<var>pgp-command</var></tt></tag>
+ <item>
+ <p>
+ Invoke <var>pgp-command</var> instead of finding
+ <tt>pgp</tt> on the <prgn>PATH</prgn>.
+ <var>pgp-command</var> must behave just like
+ <prgn>pgp</prgn>.</p>
+ </item>
+ <tag><tt>-r<var>root-command</var></tt></tag>
+ <item>
+ <p>
+ When root privilege is required, invoke the command
+ <var>root-command</var>. <var>root-command</var>
+ should invoke its first argument as a command, from
+ the <prgn>PATH</prgn> if necessary, and pass its
+ second and subsequent arguments to the command it
+ calls. If no <var>root-command</var> is supplied
+ then <var>dpkg-buildpackage</var> will take no
+ special action to gain root privilege, so that for
+ most packages it will have to be invoked as root to
+ start with.</p>
+ </item>
+ <tag><tt>-b</tt>, <tt>-B</tt></tag>
+ <item>
+ <p>
+ Two types of binary-only build and upload - see
+ <manref name="dpkg-source" section="1">.
+ </p>
+ </item>
+ </taglist>
+ </p>
+ </sect1>
+
+ <sect1>
+ <heading>
+ <prgn>dpkg-gencontrol</prgn> - generates binary package
+ control files
+ </heading>
+
+ <p>
+ This program is usually called from <file>debian/rules</file>
+ (see <ref id="pkg-sourcetree">) in the top level of the source
+ tree.
+ </p>
+
+ <p>
+ This is usually done just before the files and directories in the
+ temporary directory tree where the package is being built have their
+ permissions and ownerships set and the package is constructed using
+ <prgn>dpkg-deb/</prgn>
+ <footnote>
+ <p>
+ This is so that the control file which is produced has
+ the right permissions
+ </p>
+ </footnote>.
+ </p>
+
+ <p>
+ <prgn>dpkg-gencontrol</prgn> must be called after all the
+ files which are to go into the package have been placed in
+ the temporary build directory, so that its calculation of
+ the installed size of a package is correct.
+ </p>
+
+ <p>
+ It is also necessary for <prgn>dpkg-gencontrol</prgn> to
+ be run after <prgn>dpkg-shlibdeps</prgn> so that the
+ variable substitutions created by
+ <prgn>dpkg-shlibdeps</prgn> in <file>debian/substvars</file>
+ are available.
+ </p>
+
+ <p>
+ For a package which generates only one binary package, and
+ which builds it in <file>debian/tmp</file> relative to the top
+ of the source package, it is usually sufficient to call
+ <prgn>dpkg-gencontrol</prgn>.
+ </p>
+
+ <p>
+ Sources which build several binaries will typically need
+ something like:
+ <example>
+ dpkg-gencontrol -Pdebian/tmp-<var>pkg</var> -p<var>package</var>
+ </example> The <tt>-P</tt> tells
+ <prgn>dpkg-gencontrol</prgn> that the package is being
+ built in a non-default directory, and the <tt>-p</tt>
+ tells it which package's control file should be generated.
+ </p>
+
+ <p>
+ <prgn>dpkg-gencontrol</prgn> also adds information to the
+ list of files in <file>debian/files</file>, for the benefit of
+ (for example) a future invocation of
+ <prgn>dpkg-genchanges</prgn>.</p>
+ </sect1>
+
+ <sect1>
+ <heading>
+ <prgn>dpkg-shlibdeps</prgn> - calculates shared library
+ dependencies
+ </heading>
+
+ <p>
+ This program is usually called from <file>debian/rules</file>
+ just before <prgn>dpkg-gencontrol</prgn> (see <ref
+ id="pkg-sourcetree">), in the top level of the source tree.
+ </p>
+
+ <p>
+ Its arguments are executables.
+ <footnote>
+ <p>
+ In a forthcoming dpkg version,
+ <prgn>dpkg-shlibdeps</prgn> would be required to be
+ called on shared libraries as well.
+ </p>
+ <p>
+ They may be specified either in the locations in the
+ source tree where they are created or in the locations
+ in the temporary build tree where they are installed
+ prior to binary package creation.
+ </p>
+ </footnote> for which shared library dependencies should
+ be included in the binary package's control file.
+ </p>
+
+ <p>
+ If some of the found shared libraries should only
+ warrant a <tt>Recommends</tt> or <tt>Suggests</tt>, or if
+ some warrant a <tt>Pre-Depends</tt>, this can be achieved
+ by using the <tt>-d<var>dependency-field</var></tt> option
+ before those executable(s). (Each <tt>-d</tt> option
+ takes effect until the next <tt>-d</tt>.)
+ </p>
+
+ <p>
+ <prgn>dpkg-shlibdeps</prgn> does not directly cause the
+ output control file to be modified. Instead by default it
+ adds to the <file>debian/substvars</file> file variable
+ settings like <tt>shlibs:Depends</tt>. These variable
+ settings must be referenced in dependency fields in the
+ appropriate per-binary-package sections of the source
+ control file.
+ </p>
+
+ <p>
+ For example, the <prgn>procps</prgn> package generates two
+ kinds of binaries, simple C binaries like <prgn>ps</prgn>
+ which require a predependency and full-screen ncurses
+ binaries like <prgn>top</prgn> which require only a
+ recommendation. It can say in its <file>debian/rules</file>:
+ <example>
+ dpkg-shlibdeps -dPre-Depends ps -dRecommends top
+ </example>
+ and then in its main control file <file>debian/control</file>:
+ <example>
+ <var>...</var>
+ Package: procps
+ Pre-Depends: ${shlibs:Pre-Depends}
+ Recommends: ${shlibs:Recommends}
+ <var>...</var>
+ </example>
+ </p>
+
+ <p>
+ Sources which produce several binary packages with
+ different shared library dependency requirements can use
+ the <tt>-p<var>varnameprefix</var></tt> option to override
+ the default <tt>shlibs:</tt> prefix (one invocation of
+ <prgn>dpkg-shlibdeps</prgn> per setting of this option).
+ They can thus produce several sets of dependency
+ variables, each of the form
+ <tt><var>varnameprefix</var>:<var>dependencyfield</var></tt>,
+ which can be referred to in the appropriate parts of the
+ binary package control files.
+ </p>
+ </sect1>
+
+
+ <sect1>
+ <heading>
+ <prgn>dpkg-distaddfile</prgn> - adds a file to
+ <file>debian/files</file>
+ </heading>
+
+ <p>
+ Some packages' uploads need to include files other than
+ the source and binary package files.
+ </p>
+
+ <p>
+ <prgn>dpkg-distaddfile</prgn> adds a file to the
+ <file>debian/files</file> file so that it will be included in
+ the <file>.changes</file> file when
+ <prgn>dpkg-genchanges</prgn> is run.
+ </p>
+
+ <p>
+ It is usually invoked from the <tt>binary</tt> target of
+ <file>debian/rules</file>:
+ <example>
+ dpkg-distaddfile <var>filename</var> <var>section</var> <var>priority</var>
+ </example>
+ The <var>filename</var> is relative to the directory where
+ <prgn>dpkg-genchanges</prgn> will expect to find it - this
+ is usually the directory above the top level of the source
+ tree. The <file>debian/rules</file> target should put the
+ file there just before or just after calling
+ <prgn>dpkg-distaddfile</prgn>.
+ </p>
+
+ <p>
+ The <var>section</var> and <var>priority</var> are passed
+ unchanged into the resulting <file>.changes</file> file. See
+ <ref id="pkg-f-classification">.
+ </p>
+ </sect1>
+
+
+ <sect1><heading><prgn>dpkg-genchanges</prgn> - generates a <file>.changes</file> upload
+ control file
+ </heading>
+
+ <p>
+ This program is usually called by package-independent
+ automatic building scripts such as
+ <prgn>dpkg-buildpackage</prgn>, but it may also be called
+ by hand.
+ </p>
+
+ <p>
+ It is usually called in the top level of a built source
+ tree, and when invoked with no arguments will print out a
+ straightforward <file>.changes</file> file based on the
+ information in the source package's changelog and control
+ file and the binary and source packages which should have
+ been built.
+ </p>
+ </sect1>
+
+
+ <sect1><heading><prgn>dpkg-parsechangelog</prgn> - produces parsed representation of
+ a changelog
+ </heading>
+
+ <p>
+ This program is used internally by
+ <prgn>dpkg-source</prgn> et al. It may also occasionally
+ be useful in <file>debian/rules</file> and elsewhere. It
+ parses a changelog, <file>debian/changelog</file> by default,
+ and prints a control-file format representation of the
+ information in it to standard output.
+ </p>
+ </sect1>
+
+ <sect1 id="pkg-dpkgarch"><heading><prgn>dpkg-architecture</prgn> -
+ information about the build and host system
+ </heading>
+
+ <p>
+ This program can be used manually, but is also invoked by
+ <tt>dpkg-buildpackage</tt> or <file>debian/rules</file> to set
+ to set environment or make variables which specify the build and
+ host architecture for the package building process.
+ </p>
+ </sect1>
+ </sect>
+
+ <sect id="pkg-sourcetree"><heading>The Debianised source tree
+ </heading>
+
+ <p>
+ The source archive scheme described later is intended to
+ allow a Debianised source tree with some associated control
+ information to be reproduced and transported easily. The
+ Debianised source tree is a version of the original program
+ with certain files added for the benefit of the
+ Debianisation process, and with any other changes required
+ made to the rest of the source code and installation
+ scripts.
+ </p>
+
+ <p>
+ The extra files created for Debian are in the subdirectory
+ <file>debian</file> of the top level of the Debianised source
+ tree. They are described below.
+ </p>
+
+ <sect1 id="pkg-debianrules"><heading><file>debian/rules</file> - the main building
+ script
+ </heading>
+
+ <p>
+ This file is an executable makefile, and contains the
+ package-specific recipies for compiling the package and
+ building binary package(s) out of the source.
+ </p>
+
+ <p>
+ It must start with the line <tt>#!/usr/bin/make -f</tt>,
+ so that it can be invoked by saying its name rather than
+ invoking <prgn>make</prgn> explicitly.
+ </p>
+
+ <p>
+ Since an interactive <file>debian/rules</file> script makes it
+ impossible to autocompile that package and also makes it
+ hard for other people to reproduce the same binary
+ package, all <strong>required targets</strong> have to be
+ non-interactive. At a minimul, required targets are the
+ ones called by <prgn>dpkg-buildpackage</prgn>, namely,
+ <em>clean</em>, <em>binary</em>, <em>binary-arch</em>, and
+ <em>build</em>. It also follows that any target that these
+ targets depend on must also be non-interactive.
+ </p>
+
+ <p>
+ The targets which are required to be present are:
+ <taglist>
+ <tag><tt>build</tt></tag>
+ <item>
+ <p>
+ This should perform all non-interactive
+ configuration and compilation of the package. If a
+ package has an interactive pre-build configuration
+ routine, the Debianised source package should be
+ built after this has taken place, so that it can be
+ built without rerunning the configuration.
+ </p>
+
+ <p>
+ A package may also provide both of the targets
+ <tt>build-arch</tt> and <tt>build-indep</tt>. The
+ <tt>build-arch</tt> target, if provided, should
+ perform all non-interactive configuration and
+ compilation required for producing all
+ architecture-dependant binary packages (those packages
+ for which the body of the <tt>Architecture</tt> field
+ in <tt>debian/control</tt> is not <tt>all</tt>).
+ Similarly, the <tt>build-indep</tt> target, if
+ provided, should perform all non-interactive
+ configuration and compilation required for producing
+ all architecture-independent binary packages (those
+ packages for which the body of the
+ <tt>Architecture</tt> field in <tt>debian/control</tt>
+ is <tt>all</tt>). The <tt>build</tt> target should
+ depend on those of the targets <tt>build-arch</tt> and
+ <tt>build-indep</tt> that are provided in the rules
+ file.
+ </p>
+
+ <p>
+ If one or both of the targets <tt>build-arch</tt> and
+ <tt>build-indep</tt> are not provided, then invoking
+ <file>debian/rules</file> with one of the not-provided
+ targets as arguments should produce a exit status code
+ of 2. Usually this is provided automatically by make
+ if the target is missing.
+ </p>
+
+ <p>
+ For some packages, notably ones where the same
+ source tree is compiled in different ways to produce
+ two binary packages, the <tt>build</tt> target does
+ not make much sense. For these packages it is good
+ enough to provide two (or more) targets
+ (<tt>build-a</tt> and <tt>build-b</tt> or whatever)
+ for each of the ways of building the package, and a
+ <tt>build</tt> target that does nothing. The
+ <tt>binary</tt> target will have to build the
+ package in each of the possible ways and make the
+ binary package out of each.
+ </p>
+
+ <p>
+ The targets <tt>build</tt>, <tt>build-arch</tt>
+ and <tt>build-indep</tt> target must not do
+ anything that might require root privilege.
+ </p>
+
+ <p>
+ The <tt>build</tt> target may need to run
+ <tt>clean</tt> first - see below.
+ </p>
+
+ <p>
+ When a package has a configuration routine that takes
+ a long time, or when the makefiles are poorly
+ designed, or when <tt>build</tt> needs to run
+ <tt>clean</tt> first, it is a good idea to <tt>touch
+ build</tt> when the build process is complete. This
+ will ensure that if <tt>debian/rules build</tt> is run
+ again it will not rebuild the whole program.
+ </p>
+ </item>
+
+ <tag><tt>binary</tt>, <tt>binary-arch</tt>,
+ <tt>binary-indep</tt>
+ </tag>
+ <item>
+ <p>
+ The <tt>binary</tt> target should be all that is
+ necessary for the user to build the binary
+ package. All these targets are required to be
+ non-interactive. It is split into two parts:
+ <tt>binary-arch</tt> builds the packages' output
+ files which are specific to a particular
+ architecture, and <tt>binary-indep</tt> builds
+ those which are not.
+ </p>
+
+ <p>
+ <tt>binary</tt> should usually be a target with
+ no commands which simply depends on
+ <prgn>binary-arch</prgn> and
+ <prgn>binary-indep</prgn>.
+ </p>
+
+ <p>
+ Both <prgn>binary-*</prgn> targets should depend on
+ the <tt>build</tt> target, above, so that the
+ package is built if it has not been already. It
+ should then create the relevant binary package(s),
+ using <prgn>dpkg-gencontrol</prgn> to make their
+ control files and <prgn>dpkg-deb</prgn> to build
+ them and place them in the parent of the top level
+ directory.
+ </p>
+
+ <p>
+ If one of the <prgn>binary-*</prgn> targets has
+ nothing to do (this will be always be the case if
+ the source generates only a single binary package,
+ whether architecture-dependent or not) it
+ <em>must</em> still exist, but should always
+ succeed.
+ </p>
+
+ <p>
+ <ref id="pkg-binarypkg"> describes how to construct
+ binary packages.
+ </p>
+
+ <p>
+ The <tt>binary</tt> targets must be invoked as
+ root.
+ </p>
+ </item>
+
+ <tag><tt>clean</tt></tag>
+ <item>
+
+ <p>
+ This should undo any effects that the
+ <tt>build</tt> and <tt>binary</tt> targets
+ may have had, except that it should leave alone any
+ output files created in the parent directory by a
+ run of <tt>binary</tt>. This target is required
+ to be non-interactive.
+ </p>
+
+ <p>
+ If a <tt>build</tt> file is touched at the end
+ of the <tt>build</tt> target, as suggested
+ above, it must be removed as the first thing that
+ <tt>clean</tt> does, so that running
+ <tt>build</tt> again after an interrupted
+ <tt>clean</tt> doesn't think that everything is
+ already done.
+ </p>
+
+ <p>
+ The <tt>clean</tt> target must be invoked as
+ root if <tt>binary</tt> has been invoked since
+ the last <tt>clean</tt>, or if
+ <tt>build</tt> has been invoked as root (since
+ <tt>build</tt> may create directories, for
+ example).
+ </p>
+ </item>
+
+ <tag><tt>get-orig-source</tt> (optional)</tag>
+ <item>
+
+ <p>
+ This target fetches the most recent version of the
+ original source package from a canonical archive
+ site (via FTP or WWW, for example), does any
+ necessary rearrangement to turn it into the original
+ source tarfile format described below, and leaves it
+ in the current directory.
+ </p>
+
+ <p>
+ This target may be invoked in any directory, and
+ should take care to clean up any temporary files it
+ may have left.
+ </p>
+
+ <p>
+ This target is optional, but providing it if
+ possible is a good idea.
+ </p>
+ </item>
+ </taglist>
+
+ <p>
+ The <tt>build</tt>, <tt>binary</tt> and
+ <tt>clean</tt> targets must be invoked with a current
+ directory of the package's top-level directory.
+ </p>
+
+
+ <p>
+ Additional targets may exist in <file>debian/rules</file>,
+ either as published or undocumented interfaces or for the
+ package's internal use.
+ </p>
+
+ <p>
+ The architecture we build on and build for is determined by make
+ variables via dpkg-architecture (see <ref id="pkg-dpkgarch">). You can
+ get the Debian architecture and the GNU style architecture
+ specification string for the build machine as well as the host
+ machine. Here is a list of supported make variables:
+ <list compact="compact">
+ <item>
+ <p><tt>DEB_*_ARCH</tt> (the Debian architecture)</p>
+ </item>
+ <item>
+ <p><tt>DEB_*_GNU_TYPE</tt> (the GNU style architecture
+ specification string)</p>
+ </item>
+ <item>
+ <p><tt>DEB_*_GNU_CPU</tt> (the CPU part of DEB_*_GNU_TYPE)</p>
+ </item>
+ <item>
+ <p><tt>DEB_*_GNU_SYSTEM</tt> (the System part of
+ DEB_*_GNU_TYPE)</p>
+ </list>
+ </p>
+
+ <p>
+ where <tt>*</tt> is either <tt>BUILD</tt> for specification of
+ the build machine or <tt>HOST</tt> for specification of the machine
+ we build for.
+ </p>
+
+ <p>
+ Backward compatibility can be provided in the rules file
+ by setting the needed variables to suitable default
+ values, please refer to the documentation of
+ dpkg-architecture for details.
+ </p>
+
+ <p>
+ It is important to understand that the <tt>DEB_*_ARCH</tt>
+ string does only determine which Debian architecture we
+ build on resp. for. It should not be used to get the CPU
+ or System information, the GNU style variables should be
+ used for that.
+ </p>
+ </sect1>
+
+
+ <sect1><heading><file>debian/control</file>
+ </heading>
+
+ <p>
+ This file contains version-independent details about the
+ source package and about the binary packages it creates.
+ </p>
+
+ <p>
+ It is a series of sets of control fields, each
+ syntactically similar to a binary package control file.
+ The sets are separated by one or more blank lines. The
+ first set is information about the source package in
+ general; each subsequent set describes one binary package
+ that the source tree builds.
+ </p>
+
+ <p>
+ The syntax and semantics of the fields are described below
+ in <ref id="pkg-controlfields">.
+ </p>
+
+ <p>
+ The general (binary-package-independent) fields are:
+ <list compact="compact">
+ <item>
+ <p><qref id="pkg-f-Source"><tt>Source</tt></qref> (mandatory)</p>
+ </item>
+ <item>
+ <p><qref id="pkg-f-Maintainer"><tt>Maintainer</tt></qref></p>
+ </item>
+ <item>
+ <p>
+ <qref id="pkg-f-classification"><tt>Section</tt> and
+ <tt>Priority</tt></qref>
+ (classification, mandatory)
+ </p>
+ </item>
+ <item>
+ <p>
+ <qref id="relationships"><tt>Build-Depends</tt> et
+ al.</qref> (source package interrelationships)
+ </p>
+ </item>
+ <item>
+ <p>
+ <qref id="pkg-f-Standards-Version"><tt>Standards-Version</tt></qref>
+ </p>
+ </item>
+ </list>
+
+ <p>
+ The per-binary-package fields are:
+ <list compact="compact">
+ <item>
+ <p><qref id="pkg-f-Package"><tt>Package</tt></qref> (mandatory)</p>
+ </item>
+ <item>
+ <p>
+ <qref id="pkg-f-Architecture"><tt>Architecture</tt></qref>
+ (mandatory)</p>
+ </item>
+ <item>
+ <p><qref id="descriptions"><tt>Description</tt></qref></p>
+ </item>
+ <item>
+ <p>
+ <qref id="pkg-f-classification"><tt>Section</tt> and
+ <tt>Priority</tt></qref> (classification)</p>
+ </item>
+ <item>
+ <p><qref id="pkg-f-Essential"><tt>Essential</tt></qref></p>
+ </item>
+ <item>
+ <p>
+ <qref id="relationships"><tt>Depends</tt> et
+ al.</qref> (binary package interrelationships)
+ </p>
+ </item>
+ </list>
+
+ <p>
+ These fields are used by <prgn>dpkg-gencontrol</prgn> to
+ 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.
+ </p>
+
+ <p>
+ The fields here may contain variable references - their
+ values will be substituted by
+ <prgn>dpkg-gencontrol</prgn>, <prgn>dpkg-genchanges</prgn>
+ or <prgn>dpkg-source</prgn> when they generate output
+ control files. See <ref id="pkg-srcsubstvars"> for details.
+ </p>
+
+ <p> <sect2><heading>User-defined fields
+ </heading>
+
+ <p>
+ Additional user-defined fields may be added to the
+ source package control file. Such fields will be
+ ignored, and not copied to (for example) binary or
+ source package control files or upload control files.
+ </p>
+
+ <p>
+ If you wish to add additional unsupported fields to
+ these output files you should use the mechanism
+ described here.
+ </p>
+
+ <p>
+ Fields in the main source control information file with
+ names starting <tt>X</tt>, followed by one or more of
+ the letters <tt>BCS</tt> and a hyphen <tt>-</tt>, will
+ be copied to the output files. Only the part of the
+ field name after the hyphen will be used in the output
+ file. Where the letter <tt>B</tt> is used the field
+ will appear in binary package control files, where the
+ letter <tt>S</tt> is used in source package control
+ files and where <tt>C</tt> is used in upload control
+ (<tt>.changes</tt>) files.
+ </p>
+
+ <p>
+ For example, if the main source information control file
+ contains the field
+ <example>
+ XBS-Comment: I stand between the candle and the star.
+ </example>
+ then the binary and source package control files will contain the
+ field
+ <example>
+ Comment: I stand between the candle and the star.
+ </example>
+ </p>
+ </sect2>
+
+ </sect1>
+
+ <sect1 id="pkg-dpkgchangelog"><heading><file>debian/changelog</file>
+ </heading>
+
+ <p>
+ This file records the changes to the Debian-specific parts of the
+ package
+ <footnote>
+ <p>
+ Though there is nothing stopping an author who is also
+ the Debian maintainer from using it for all their
+ changes, it will have to be renamed if the Debian and
+ upstream maintainers become different
+ people.
+ </p>
+ </footnote>.
+ </p>
+
+ <p>
+ It has a special format which allows the package building
+ tools to discover which version of the package is being
+ built and find out other release-specific information.
+ </p>
+
+ <p>
+ That format is a series of entries like this:
+ <example>
+ <var>package</var> (<var>version</var>) <var>distribution(s)</var>; urgency=<var>urgency</var>
+
+ * <var>change details</var>
+ <var>more change details</var>
+ * <var>even more change details</var>
+
+ -- <var>maintainer name and email address</var> <var>date</var>
+ </example>
+ </p>
+
+ <p>
+ <var>package</var> and <var>version</var> are the source
+ package name and version number.
+ </p>
+
+ <p>
+ <var>distribution(s)</var> lists the distributions where
+ this version should be installed when it is uploaded - it
+ is copied to the <tt>Distribution</tt> field in the
+ <tt>.changes</tt> file. See <ref id="pkg-f-Distribution">.
+ </p>
+
+ <p>
+ <var>urgency</var> is the value for the <tt>Urgency</tt>
+ field in the <file>.changes</file> file for the upload. See
+ <ref id="pkg-f-Urgency">. It is not possible to specify an
+ urgency containing commas; commas are used to separate
+ <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>).
+ </p>
+
+ <p>
+ The change details may in fact be any series of lines
+ starting with at least two spaces, but conventionally each
+ change starts with an asterisk and a separating space and
+ continuation lines are indented so as to bring them in
+ line with the start of the text above. Blank lines may be
+ used here to separate groups of changes, if desired.
+ </p>
+
+ <p>
+ The maintainer name and email address should <em>not</em>
+ necessarily be those of the usual package maintainer.
+ They should be the details of the person doing
+ <em>this</em> version. The information here will be
+ copied to the <file>.changes</file> file, and then later used
+ to send an acknowledgement when the upload has been
+ installed.
+ </p>
+
+ <p>
+ The <var>date</var> should be in RFC822 format
+ <footnote>
+ <p>
+ This is generated by the <prgn>822-date</prgn>
+ program.
+ </p>
+ </footnote>; it should include the timezone specified
+ numerically, with the timezone name or abbreviation
+ optionally present as a comment.
+ </p>
+
+ <p>
+ The first "title" line with the package name should start
+ at the left hand margin; the "trailer" line with the
+ maintainer and date details should be preceded by exactly
+ one space. The maintainer details and the date must be
+ separated by exactly two spaces.
+ </p>
+
+ <p>
+ An Emacs mode for editing this format is available: it is
+ called <tt>debian-changelog-mode</tt>. You can have this
+ mode selected automatically when you edit a Debian
+ changelog by adding a local variables clause to the end of
+ the changelog.
+ </p>
+
+ <sect2><heading>Defining alternative changelog formats
+ </heading>
+
+ <p>
+ It is possible to use a different format to the standard
+ one, by providing a parser for the format you wish to
+ use.
+ </p>
+
+ <p>
+ In order to have <tt>dpkg-parsechangelog</tt> run your
+ parser, you must include a line within the last 40 lines
+ of your file matching the Perl regular expression:
+ <tt>\schangelog-format:\s+([0-9a-z]+)\W</tt> The part in
+ parentheses should be the name of the format. For
+ example, you might say:
+ <example>
+ @@@ changelog-format: joebloggs @@@
+ </example>
+ Changelog format names are non-empty strings of alphanumerics.
+ </p>
+
+ <p>
+ If such a line exists then <tt>dpkg-parsechangelog</tt>
+ will look for the parser as
+ <file>/usr/lib/dpkg/parsechangelog/<var>format-name</var></file>
+ or
+ <file>/usr/local/lib/dpkg/parsechangelog/<var>format-name</var></file>;
+ it is an error for it not to find it, or for it not to
+ be an executable program. The default changelog format
+ is <tt>dpkg</tt>, and a parser for it is provided with
+ the <tt>dpkg</tt> package.
+ </p>
+
+ <p>
+ The parser will be invoked with the changelog open on
+ standard input at the start of the file. It should read
+ the file (it may seek if it wishes) to determine the
+ information required and return the parsed information
+ to standard output in the form of a series of control
+ fields in the standard format. By default it should
+ return information about only the most recent version in
+ the changelog; it should accept a
+ <tt>-v<var>version</var></tt> option to return changes
+ information from all versions present <em>strictly
+ after</em> <var>version</var>, and it should then be an
+ error for <var>version</var> not to be present in the
+ changelog.
+ </p>
+
+ <p>
+ The fields are:
+ <list compact="compact">
+ <item>
+ <p><qref id="pkg-f-Source"><tt>Source</tt></qref></p>
+ </item>
+ <item>
+ <p><qref id="versions"><tt>Version</tt></qref> (mandatory)</p>
+ </item>
+ <item>
+ <p>
+ <qref id="pkg-f-Distribution"><tt>Distribution</tt></qref>
+ (mandatory)
+ </p>
+ </item>
+ <item>
+ <p><qref id="pkg-f-Urgency"><tt>Urgency</tt></qref> (mandatory)</p>
+ </item>
+ <item>
+ <p>
+ <qref id="pkg-f-Maintainer"><tt>Maintainer</tt></qref>
+ (mandatory)
+ </p>
+ </item>
+ <item>
+ <p><qref id="pkg-f-Date"><tt>Date</tt></qref></p>
+ </item>
+ <item>
+ <p>
+ <qref id="pkg-f-Changes"><tt>Changes</tt></qref>
+ (mandatory)
+ </p>
+ </item>
+ </list>
+
+ <p>
+ If several versions are being returned (due to the use
+ of <tt>-v</tt>), the urgency value should be of the
+ highest urgency code listed at the start of any of the
+ versions requested followed by the concatenated
+ (space-separated) comments from all the versions
+ requested; the maintainer, version, distribution and
+ date should always be from the most recent version.
+ </p>
+
+ <p>
+ For the format of the <tt>Changes</tt> field see <ref
+ id="pkg-f-Changes">.
+ </p>
+
+ <p>
+ If the changelog format which is being parsed always or
+ almost always leaves a blank line between individual
+ change notes these blank lines should be stripped out,
+ so as to make the resulting output compact.
+ </p>
+
+ <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
+ it or find it from other sources.
+ </p>
+
+ <p>
+ If the changelog does not have the expected format the
+ parser should exit with a nonzero exit status, rather
+ than trying to muddle through and possibly generating
+ incorrect output.
+ </p>
+
+ <p>
+ A changelog parser may not interact with the user at
+ all.</p></sect2>
+ </sect1>
+
+<!-- FIXME: section pkg-srcsubstvars is the same as srcsubstvars -->
+
+ <sect1 id="pkg-srcsubstvars"><heading><file>debian/substvars</file>
+ and variable substitutions
+ </heading>
+
+ <p>
+ When <prgn>dpkg-gencontrol</prgn>,
+ <prgn>dpkg-genchanges</prgn> and <prgn>dpkg-source</prgn>
+ generate control files they do variable substitutions on
+ their output just before writing it. Variable
+ substitutions have the form
+ <tt>${<var>variable-name</var>}</tt>. The optional file
+ <file>debian/substvars</file> contains variable substitutions
+ to be used; variables can also be set directly from
+ <file>debian/rules</file> using the <tt>-V</tt> option to the
+ source packaging commands, and certain predefined
+ variables are available.
+ </p>
+
+ <p>
+ This file is usually generated and modified dynamically by
+ <file>debian/rules</file> targets, in which case it must be
+ removed by the <tt>clean</tt> target.
+ </p>
+
+ <p>
+ See <manref name="dpkg-source" section="1"> for full
+ details about source variable substitutions, including the
+ format of <file>debian/substvars</file>.</p>
+ </sect1>
+
+ <sect1><heading><file>debian/files</file>
+ </heading>
+
+ <p>
+ This file is not a permanent part of the source tree; it
+ is used while building packages to record which files are
+ being generated. <prgn>dpkg-genchanges</prgn> uses it
+ when it generates a <file>.changes</file> file.
+ </p>
+
+ <p>
+ It should not exist in a shipped source package, and so it
+ (and any backup files or temporary files such as
+ <file>files.new</file>
+ <footnote>
+ <p>
+ <file>files.new</file> is used as a temporary file by
+ <prgn>dpkg-gencontrol</prgn> and
+ <prgn>dpkg-distaddfile</prgn> - they write a new
+ version of <file>files</file> here before renaming it,
+ to avoid leaving a corrupted copy if an error
+ occurs
+ </p>
+ </footnote>) should be removed by the
+ <tt>clean</tt> target. It may also be wise to
+ ensure a fresh start by emptying or removing it at the
+ start of the <tt>binary</tt> target.
+ </p>
+
+ <p>
+ <prgn>dpkg-gencontrol</prgn> adds an entry to this file
+ for the <file>.deb</file> file that will be created by
+ <prgn>dpkg-deb</prgn> from the control file that it
+ generates, so for most packages all that needs to be done
+ with this file is to delete it in <tt>clean</tt>.
+ </p>
+
+ <p>
+ If a package upload includes files besides the source
+ package and any binary packages whose control files were
+ made with <prgn>dpkg-gencontrol</prgn> then they should be
+ placed in the parent of the package's top-level directory
+ and <prgn>dpkg-distaddfile</prgn> should be called to add
+ the file to the list in <file>debian/files</file>.</p>
+ </sect1>
+
+ <sect1><heading><file>debian/tmp</file>
+ </heading>
+
+ <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
+ 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
+ id="pkg-bincreating">.
+ </p>
+
+ <p>
+ If several binary packages are generated from the same
+ source tree it is usual to use several
+ <file>debian/tmp<var>something</var></file> directories, for
+ example <file>tmp-a</file> or <file>tmp-doc</file>.
+ </p>
+
+ <p>
+ Whatever <file>tmp</file> directories are created and used by
+ <tt>binary</tt> must of course be removed by the
+ <tt>clean</tt> target.</p></sect1>
+ </sect>
+
+
+ <sect id="pkg-sourcearchives"><heading>Source packages as archives
+ </heading>
+
+ <p>
+ As it exists on the FTP site, a Debian source package
+ consists of three related files. You must have the right
+ versions of all three to be able to use them.
+ </p>
+
+ <p>
+ <taglist>
+ <tag>Debian source control file - <tt>.dsc</tt></tag>
+ <item>
+
+ <p>
+ This file contains a series of fields, identified and
+ separated just like the fields in the control file of
+ a binary package. The fields are listed below; their
+ syntax is described above, in <ref id="pkg-controlfields">.
+ <list compact="compact">
+ <item>
+ <p><qref id="pkg-f-Source"><tt>Source</tt></qref></p>
+ </item>
+ <item>
+ <p><qref id="versions"><tt>Version</tt></qref></p>
+ </item>
+ <item>
+ <p><qref id="pkg-f-Maintainer"><tt>Maintainer</tt></qref></p>
+ </item>
+ <item>
+ <p><qref id="pkg-f-Binary"><tt>Binary</tt></qref></p>
+ </item>
+ <item>
+ <p><qref id="pkg-f-Architecture"><tt>Architecture</tt></qref></p>
+ </item>
+ <item>
+ <p>
+ <qref id="relationships"><tt>Build-Depends</tt> et
+ al.</qref> (source package interrelationships)
+ </p>
+ </item>
+ <item>
+ <p>
+ <qref id="pkg-f-Standards-Version"><tt>Standards-Version</tt></qref></p>
+ </item>
+ <item>
+ <p><qref id="pkg-f-Files"><tt>Files</tt></qref></p>
+ </item>
+ </list>
+
+ <p>
+ The source package control file is generated by
+ <prgn>dpkg-source</prgn> when it builds the source
+ archive, from other files in the source package,
+ described above. When unpacking it is checked against
+ the files and directories in the other parts of the
+ source package, as described below.</p>
+ </item>
+
+ <tag>
+ Original source archive -
+ <file>
+ <var>package</var>_<var>upstream-version</var>.orig.tar.gz
+ </file>
+ </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>
+ </item>
+
+ <tag>
+ Debianisation diff -
+ <file>
+ <var>package</var>_<var>upstream_version-revision</var>.diff.gz
+ </file>
+ </tag>
+ <item>
+
+ <p>
+ This is a unified context diff (<tt>diff -u</tt>)
+ giving the changes which are required to turn the
+ original source into the Debian source. These changes
+ may only include editing and creating plain files.
+ The permissions of files, the targets of symbolic
+ links and the characteristics of special files or
+ pipes may not be changed and no files may be removed
+ or renamed.
+ </p>
+
+ <p>
+ All the directories in the diff must exist, except the
+ <file>debian</file> subdirectory of the top of the source
+ tree, which will be created by
+ <prgn>dpkg-source</prgn> if necessary when unpacking.
+ </p>
+
+ <p>
+ The <prgn>dpkg-source</prgn> program will
+ automatically make the <file>debian/rules</file> file
+ executable (see below).</p></item>
+ </taglist>
+
+
+ <p>
+ If there is no original source code - for example, if the
+ package is specially prepared for Debian or the Debian
+ 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></file>.
+ </p>
+ </sect>
+
+ <sect><heading>Unpacking a Debian source package without
+ <prgn>dpkg-source</prgn>
+ </heading>
+
+ <p>
+ <tt>dpkg-source -x</tt> is the recommended way to unpack a
+ Debian source package. However, if it is not available it
+ is possible to unpack a Debian source archive as follows:
+ <enumlist compact="compact">
+ <item>
+ <p>
+ Untar the tarfile, which will create a <file>.orig</file>
+ directory.</p>
+ </item>
+ <item>
+ <p>Rename the <file>.orig</file> directory to
+ <file><var>package</var>-<var>version</var></file>.</p>
+ </item>
+ <item>
+ <p>
+ Create the subdirectory <file>debian</file> at the top of
+ the source tree.</p>
+ </item>
+ <item><p>Apply the diff using <tt>patch -p0</tt>.</p>
+ </item>
+ <item><p>Untar the tarfile again if you want a copy of the original
+ source code alongside the Debianised version.</p>
+ </item>
+ </enumlist>
+
+ <p>
+ It is not possible to generate a valid Debian source archive
+ without using <prgn>dpkg-source</prgn>. In particular,
+ attempting to use <prgn>diff</prgn> directly to generate the
+ <file>.diff.gz</file> file will not work.
+ </p>
+
+ <sect1><heading>Restrictions on objects in source packages
+ </heading>
+
+ <p>
+ The source package may not contain any hard links
+ <footnote>
+ <p>
+ This is not currently detected when building source
+ packages, but only when extracting
+ them.
+ </p>
+ </footnote>
+ <footnote>
+ <p>
+ Hard links may be permitted at some point in the
+ future, but would require a fair amount of
+ work.
+ </p>
+ </footnote>, device special files, sockets or setuid or
+ setgid files.
+ <footnote>
+ <p>
+ Setgid directories are allowed.
+ </p>
+ </footnote>
+ </p>
+
+ <p>
+ The source packaging tools manage the changes between the
+ original and Debianised source using <prgn>diff</prgn> and
+ <prgn>patch</prgn>. Turning the original source tree as
+ included in the <file>.orig.tar.gz</file> into the debianised
+ source must not involve any changes which cannot be
+ handled by these tools. Problematic changes which cause
+ <prgn>dpkg-source</prgn> to halt with an error when
+ building the source package are:
+ <list compact="compact">
+ <item><p>Adding or removing symbolic links, sockets or pipes.</p>
+ </item>
+ <item><p>Changing the targets of symbolic links.</p>
+ </item>
+ <item><p>Creating directories, other than <file>debian</file>.</p>
+ </item>
+ <item><p>Changes to the contents of binary files.</p></item>
+ </list> Changes which cause <prgn>dpkg-source</prgn> to
+ print a warning but continue anyway are:
+ <list compact="compact">
+ <item>
+ <p>
+ Removing files, directories or symlinks.
+ <footnote>
+ <p>
+ Renaming a file is not treated specially - it is
+ seen as the removal of the old file (which
+ generates a warning, but is otherwise ignored),
+ and the creation of the new
+ one.</p>
+ </footnote>
+ </p>
+ </item>
+ <item>
+ <p>
+ Changed text files which are missing the usual final
+ newline (either in the original or the modified
+ source tree).
+ </p>
+ </item>
+ </list>
+ Changes which are not represented, but which are not detected by
+ <prgn>dpkg-source</prgn>, are:
+ <list compact="compact">
+ <item><p>Changing the permissions of files (other than
+ <file>debian/rules</file>) and directories.</p></item>
+ </list>
+ </p>
+
+ <p>
+ The <file>debian</file> directory and <file>debian/rules</file>
+ 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.
+ </p>
+ </sect1>
+ </sect>
+ </appendix>
+
+ <appendix id="pkg-controlfields"><heading>Control files and their
+ fields (from old Packaging Manual)
+ </heading>
+
+ <p>
+ Many of the tools in the <prgn>dpkg</prgn> suite manipulate
+ data in a common format, known as control files. Binary and
+ source packages have control data as do the <file>.changes</file>
+ files which control the installation of uploaded files, and
+ <prgn>dpkg</prgn>'s internal databases are in a similar
+ format.
+ </p>
+
+ <sect><heading>Syntax of control files
+ </heading>
+
+ <p>
+ A file consists of one or more paragraphs of fields. The
+ paragraphs are separated by blank lines. Some control files
+ only allow one paragraph; others allow several, in which
+ case each paragraph often refers to a different package.
+ </p>
+
+ <p>
+ Each paragraph is a series of fields and values; each field
+ consists of a name, followed by a colon and the value. It
+ ends at the end of the line. Horizontal whitespace (spaces
+ and tabs) may occur before or after the value and is ignored
+ there; it is conventional to put a single space after the
+ colon.
+ </p>
+
+ <p>
+ Some fields' values may span several lines; in this case
+ each continuation line <em>must</em> start with a space or
+ tab. Any trailing spaces or tabs at the end of individual
+ 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 may never appear inside names (of packages,
+ architectures, files or anything else), version numbers or
+ in between the characters of multi-character version
+ relationships.
+ </p>
+
+ <p>
+ Field names are not case-sensitive, but it is usual to
+ capitalise the field names using mixed case as shown below.
+ </p>
+
+ <p>
+ Blank lines, or lines consisting only of spaces and tabs,
+ are not allowed within field values or between fields - that
+ would mean a new paragraph.
+ </p>
+
+ <p>
+ It is important to note that there are several fields which
+ are optional as far as <prgn>dpkg</prgn> and the related
+ tools are concerned, but which must appear in every Debian
+ package, or whose omission may cause problems.
+ </p>
+ </sect>
+
+ <sect><heading>List of fields
+ </heading>
+
+ <sect1 id="pkg-f-Package"><heading><tt>Package</tt>
+ </heading>
+
+ <p>
+ The name of the binary package. Package names consist of
+ the alphanumerics and <tt>+</tt> <tt>-</tt> <tt>.</tt>
+ (plus, minus and full stop).
+ <footnote>
+ <p>
+ The characters <tt>@</tt> <tt>:</tt> <tt>=</tt>
+ <tt>%</tt> <tt>_</tt> (at, colon, equals, percent
+ and underscore) used to be legal and are still
+ accepted when found in a package file, but may not be
+ used in new packages
+ </p>
+ </footnote>
+ </p>
+
+ <p>
+ They must be at least two characters and must start with
+ an alphanumeric. In current versions of dpkg they are
+ sort of case-sensitive<footnote><p>This is a
+ bug.</p></footnote>; use lowercase package names unless
+ the package you're building (or referring to, in other
+ fields) is already using uppercase.</p>
+ </sect1>
+
+ <sect1 id="pkg-f-Version"><heading><tt>Version</tt>
+ </heading>
+
+ <p>
+ This lists the source or binary package's version number -
+ see <ref id="versions">.
+ </p>
+
+ </sect1>
+
+ <sect1 id="pkg-f-Architecture"><heading><tt>Architecture</tt>
+ </heading>
+
+ <p>
+ This is the architecture string; it is a single word for
+ the Debian architecture.
+ </p>
+
+ <p>
+ <prgn>dpkg</prgn> will check the declared architecture of
+ a binary package against its own compiled-in value before
+ it installs it.
+ </p>
+
+ <p>
+ The special value <tt>all</tt> indicates that the package
+ is architecture-independent.
+ </p>
+
+ <p>
+ In the main <file>debian/control</file> file in the source
+ package, or in the source package control file
+ <file>.dsc</file>, a list of architectures (separated by
+ spaces) is also allowed, as is the special value
+ <tt>any</tt>. A list indicates that the source will build
+ an architecture-dependent package, and will only work
+ correctly on the listed architectures. <tt>any</tt>
+ indicates that though the source package isn't dependent
+ on any particular architecture and should compile fine on
+ any one, the binary package(s) produced are not
+ architecture-independent but will instead be specific to
+ whatever the current build architecture is.
+ </p>
+
+ <p>
+ In a <file>.changes</file> file the <tt>Architecture</tt>
+ field lists the architecture(s) of the package(s)
+ currently being uploaded. This will be a list; if the
+ source for the package is being uploaded too the special
+ entry <tt>source</tt> is also present.
+ </p>
+
+ <p>
+ See <ref id="pkg-debianrules"> for information how to get the
+ architecture for the build process.
+ </p>
+ </sect1>
+
+ <sect1 id="pkg-f-Maintainer"><heading><tt>Maintainer</tt>
+ </heading>
+
+ <p>
+ The package maintainer's name and email address. The name
+ should come first, then the email address inside angle
+ brackets <tt><></tt> (in RFC822 format).
+ </p>
+
+ <p>
+ If the maintainer's name contains a full stop then the
+ whole field will not work directly as an email address due
+ to a misfeature in the syntax specified in RFC822; a
+ program using this field as an address must check for this
+ and correct the problem if necessary (for example by
+ putting the name in round brackets and moving it to the
+ end, and bringing the email address forward).
+ </p>
+
+ <p>
+ In a <file>.changes</file> file or parsed changelog data this
+ contains the name and email address of the person
+ responsible for the particular version in question - this
+ may not be the package's usual maintainer.
+ </p>
+
+ <p>
+ This field is usually optional in as far as the
+ <prgn>dpkg</prgn> are concerned, but its absence when
+ building packages usually generates a warning.</p>
+ </sect1>
+
+ <sect1 id="pkg-f-Source"><heading><tt>Source</tt>
+ </heading>
+
+ <p>
+ This field identifies the source package name.
+ </p>
+
+ <p>
+ In a main source control information or a
+ <file>.changes</file> or <file>.dsc</file> file or parsed
+ changelog data this may contain only the name of the
+ source package.
+ </p>
+
+ <p>
+ In the control file of a binary package (or in a
+ <file>Packages</file> file) it may be followed by a version
+ number in parentheses.
+ <footnote>
+ <p>
+ It is usual to leave a space after the package name if
+ a version number is specified.
+ </p>
+ </footnote> This version number may be omitted (and is, by
+ <prgn>dpkg-gencontrol</prgn>) if it has the same value as
+ the <tt>Version</tt> field of the binary package in
+ question. The field itself may be omitted from a binary
+ package control file when the source package has the same
+ name and version as the binary package.
+ </p>
+ </sect1>
+
+ <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>
+ </heading>
+
+ <p>
+ These fields describe the package's relationships with
+ other packages. Their syntax and semantics are described
+ in <ref id="relationships">.</p>
+ </sect1>
+
+ <sect1 id="pkg-f-Description"><heading><tt>Description</tt>
+ </heading>
+
+ <p>
+ In a binary package <tt>Packages</tt> file or main source
+ control file this field contains a description of the
+ binary package, in a special format. See <ref
+ id="descriptions"> for details.
+ </p>
+
+ <p>
+ In a <file>.changes</file> file it contains a summary of the
+ descriptions for the packages being uploaded. The part of
+ the field before the first newline is empty; thereafter
+ each line has the name of a binary package and the summary
+ description line from that binary package. Each line is
+ indented by one space.</p>
+ </sect1>
+
+ <sect1 id="pkg-f-Essential"><heading><tt>Essential</tt>
+ </heading>
+
+ <p>
+ This is a boolean field which may occur only in the
+ control file of a binary package (or in the
+ <file>Packages</file> file) or in a per-package fields
+ paragraph of a main source control data file.
+ </p>
+
+ <p>
+ If set to <tt>yes</tt> then <prgn>dpkg</prgn> and
+ <prgn>dselect</prgn> will refuse to remove the package
+ (though it can be upgraded and/or replaced). The other
+ possible value is <tt>no</tt>, which is the same as not
+ having the field at all.</p>
+ </sect1>
+
+ <sect1 id="pkg-f-classification"><heading><tt>Section</tt> and
+ <tt>Priority</tt>
+ </heading>
+
+ <p>
+ These two fields classify the package. The
+ <tt>Priority</tt> represents how important that it is that
+ the user have it installed; the <tt>Section</tt>
+ represents an application area into which the package has
+ been classified.
+ </p>
+
+ <p>
+ When they appear in the <file>debian/control</file> file these
+ fields give values for the section and priority subfields
+ of the <tt>Files</tt> field of the <file>.changes</file> file,
+ and give defaults for the section and priority of the
+ binary packages.
+ </p>
+
+ <p>
+ The section and priority are represented, though not as
+ separate fields, in the information for each file in the
+ <qref id="pkg-f-Files"><tt>-File</tt></qref>field of a
+ <file>.changes</file> file. The section value in a
+ <file>.changes</file> file is used to decide where to install
+ a package in the FTP archive.
+ </p>
+
+ <p>
+ These fields are not used by by <prgn>dpkg</prgn> proper,
+ but by <prgn>dselect</prgn> when it sorts packages and
+ selects defaults.
+ </p>
+
+ <p>
+ These fields can appear in binary package control files,
+ in which case they provide a default value in case the
+ <file>Packages</file> files are missing the information.
+ <prgn>dpkg</prgn> and <prgn>dselect</prgn> will only use
+ the value from a <file>.deb</file> file if they have no other
+ information; a value listed in a <file>Packages</file> file
+ will always take precedence. By default
+ <prgn>dpkg-gencontrol</prgn> does not include the section
+ and priority in the control file of a binary package - use
+ the <tt>-isp</tt>, <tt>-is</tt> or <tt>-ip</tt> options to
+ achieve this effect.</p>
+ </sect1>
+
+ <sect1 id="pkg-f-Binary"><heading><tt>Binary</tt>
+ </heading>
+
+ <p>
+ This field is a list of binary packages.
+ </p>
+
+ <p>
+ When it appears in the <file>.dsc</file> file it is the list
+ of binary packages which a source package can produce. It
+ does not necessarily produce all of these binary packages
+ for every architecture. The source control file doesn't
+ contain details of which architectures are appropriate for
+ which of the binary packages.
+ </p>
+
+ <p>
+ When it appears in a <file>.changes</file> file it lists the
+ names of the binary packages actually being uploaded.
+ </p>
+
+ <p>
+ The syntax is a list of binary packages separated by
+ commas.
+ <footnote>
+ <p>
+ A space after each comma is conventional.
+ </p>
+ </footnote> Currently the packages must be separated using
+ only spaces in the <file>.changes</file> file.</p>
+ </sect1>
+
+ <sect1 id="pkg-f-Installed-Size"><heading><tt>Installed-Size</tt>
+ </heading>
+
+ <p>
+ This field appears in the control files of binary
+ packages, and in the <file>Packages</file> files. It gives
+ the total amount of disk space required to install the
+ named package.
+ </p>
+
+ <p>
+ The disk space is represented in kilobytes as a simple
+ decimal number.</p>
+ </sect1>
+
+ <sect1 id="pkg-f-Files"><heading><tt>Files</tt>
+ </heading>
+
+ <p>
+ This field contains a list of files with information about
+ each one. The exact information and syntax varies with
+ the context. In all cases the part of the field
+ contents on the same line as the field name is empty. The
+ remainder of the field is one line per file, each line
+ being indented by one space and containing a number of
+ sub-fields separated by spaces.
+ </p>
+
+ <p>
+ In the <file>.dsc</file> (Debian source control) file each
+ line contains the MD5 checksum, size and filename of the
+ tarfile and (if applicable) diff file which make up the
+ remainder of the source package.
+ <footnote>
+ <p>
+ That is, the parts which are not the
+ <tt>.dsc</tt>.
+ </p>
+ </footnote> The exact forms of the filenames are described
+ in <ref id="pkg-sourcearchives">.
+ </p>
+
+ <p>
+ In the <file>.changes</file> file this contains one line per
+ file being uploaded. Each line contains the MD5 checksum,
+ size, section and priority and the filename. The section
+ and priority are the values of the corresponding fields in
+ the main source control file - see <ref
+ id="pkg-f-classification">. If no section or priority is
+ specified then <tt>-</tt> should be used, though section
+ and priority values must be specified for new packages to
+ be installed properly.
+ </p>
+
+ <p>
+ The special value <tt>byhand</tt> for the section in a
+ <tt>.changes</tt> file indicates that the file in question
+ is not an ordinary package file and must by installed by
+ hand by the distribution maintainers. If the section is
+ <tt>byhand</tt> the priority should be <tt>-</tt>.
+ </p>
+
+ <p>
+ If a new Debian revision of a package is being shipped and
+ no new original source archive is being distributed the
+ <tt>.dsc</tt> must still contain the <tt>Files</tt> field
+ entry for the original source archive
+ <file><var>package</var>-<var>upstream-version</var>.orig.tar.gz</file>,
+ but the <file>.changes</file> file should leave it out. In
+ this case the original source archive on the distribution
+ site must match exactly, byte-for-byte, the original
+ source archive which was used to generate the
+ <file>.dsc</file> file and diff which are being uploaded.</p>
+ </sect1>
+
+
+ <sect1
+ id="pkg-f-Standards-Version"><heading><tt>Standards-Version</tt>
+ </heading>
+
+ <p>
+ The most recent version of the standards (the Debian Policy
+ and associated texts) with which the package complies. This
+ is updated manually when editing the source package to
+ conform to newer standards; it can sometimes be used to
+ tell when a package needs attention.
+ </p>
+
+ <p>
+ Its format is the same as that of a version number except
+ that no epoch or Debian revision is allowed - see <ref
+ id="versions">.</p>
+ </sect1>
+
+
+ <sect1 id="pkg-f-Distribution"><heading><tt>Distribution</tt>
+ </heading>
+
+ <p>
+ In a <file>.changes</file> file or parsed changelog output
+ this contains the (space-separated) name(s) of the
+ distribution(s) where this version of the package should
+ be or was installed. Distribution names follow the rules
+ for package names. (See <ref id="pkg-f-Package">).
+ </p>
+
+ <p>
+ Current distribution values are:
+ <taglist>
+ <tag><em>stable</em></tag>
+ <item>
+ <p>
+ This is the current "released" version of Debian
+ GNU/Linux. A new version is released approximately
+ every 3 months after the <em>development</em> code has
+ been <em>frozen</em> for a month of testing. Once the
+ distribution is <em>stable</em> only major bug fixes
+ are allowed. When changes are made to this
+ distribution, the release number is increased
+ (for example: 1.2r1 becomes 1.2r2 then 1.2r3, etc).
+ </p>
+ </item>
+
+ <tag><em>unstable</em></tag>
+ <item>
+ <p>
+ This distribution value refers to the
+ <em>developmental</em> part of the Debian distribution
+ tree. New packages, new upstream versions of packages
+ and bug fixes go into the <em>unstable</em> directory
+ tree. Download from this distribution at your own
+ risk.</p>
+ </item>
+
+ <tag><em>contrib</em></tag>
+ <item>
+ <p>
+ The packages with this distribution value do not meet
+ the criteria for inclusion in the main Debian
+ distribution as defined by the Policy Manual, but meet
+ the criteria for the <em>contrib</em>
+ Distribution. There is currently no distinction
+ between stable and unstable packages in the
+ <em>contrib</em> or <em>non-free</em>
+ distributions. Use your best judgement in downloading
+ from this Distribution.</p>
+ </item>
+
+ <tag><em>non-free</em></tag>
+ <item>
+ <p>
+ Like the packages in the <em>contrib</em> seciton,
+ the packages in <em>non-free</em> do not meet the
+ criteria for inclusion in the main Debian distribution
+ as defined by the Policy Manual. Again, use your best
+ judgement in downloading from this Distribution.</p>
+
+ <tag><em>experimental</em></tag>
+ <item>
+ <p>
+ The packages with this distribution value are deemed
+ by their maintainers to be high risk. Oftentimes they
+ represent early beta or developmental packages from
+ various sources that the maintainers want people to
+ try, but are not ready to be a part of the other parts
+ of the Debian distribution tree. Download at your own
+ risk.</p>
+ </item>
+
+ <tag><em>frozen</em></tag>
+ <item>
+ <p>
+ From time to time, (currently, every 3 months) the
+ <em>unstable</em> distribution enters a state of
+ "code-freeze" in anticipation of release as a
+ <em>stable</em> version. During this period of testing
+ (usually 4 weeks) only fixes for existing or
+ newly-discovered bugs will be allowed.
+ </p>
+ </item>
+ </taglist> You should list <em>all</em> distributions that
+ the package should be installed into. Except in unusual
+ circumstances, installations to <em>stable</em> should also
+ go into <em>frozen</em> (if it exists) and
+ <em>unstable</em>. Likewise, installations into
+ <em>frozen</em> should also go into <em>unstable</em>.</p>
+ </sect1>
+
+ <sect1 id="pkg-f-Urgency"><heading><tt>Urgency</tt>
+ </heading>
+
+ <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>) followed by an optional
+ commentary (separated by a space) which is usually in
+ parentheses. For example:
+ <example>
+ Urgency: LOW (HIGH for diversions users)
+ </example>
+ </p>
+
+ <p>
+ This field appears in the <file>.changes</file> file and in
+ parsed changelogs; its value appears as the value of the
+ <tt>urgency</tt> attribute in a <prgn>dpkg</prgn>-style
+ changelog (see <ref id="pkg-dpkgchangelog">).
+ </p>
+
+ <p>
+ Urgency keywords are not case-sensitive.</p>
+ </sect1>
+
+ <sect1 id="pkg-f-Date"><heading><tt>Date</tt>
+ </heading>
+
+ <p>
+ In <tt>.changes</tt> files and parsed changelogs, this
+ gives the date the package was built or last edited.</p>
+ </sect1>
+
+ <sect1 id="pkg-f-Format"><heading><tt>Format</tt>
+ </heading>
+
+ <p>
+ This field occurs in <file>.changes</file> files, and
+ specifies a format revision for the file. The format
+ described here is version <tt>1.5</tt>. The syntax of the
+ format value is the same as that of a package version
+ number except that no epoch or Debian revision is allowed
+ - see <ref id="versions">.</p>
+ </sect1>
+
+ <sect1 id="pkg-f-Changes"><heading><tt>Changes</tt>
+ </heading>
+
+ <p>
+ In a <file>.changes</file> file or parsed changelog this field
+ contains the human-readable changes data, describing the
+ differences between the last version and the current one.
+ </p>
+
+ <p>
+ 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.
+ </p>
+
+ <p>
+ Each version's change information should be preceded by a
+ "title" line giving at least the version, distribution(s)
+ and urgency, in a human-readable way.
+ </p>
+
+ <p>
+ If data from several versions is being returned the entry
+ for the most recent version should be returned first, and
+ entries should be separated by the representation of a
+ blank line (the "title" line may also be followed by the
+ representation of blank line).</p>
+ </sect1>
+
+ <sect1 id="pkg-f-Filename"><heading><tt>Filename</tt> and
+ <tt>MSDOS-Filename</tt>
+ </heading>
+
+ <p>
+ These fields in <tt>Packages</tt> files give the
+ filename(s) of (the parts of) a package in the
+ distribution directories, relative to the root of the
+ Debian hierarchy. If the package has been split into
+ several parts the parts are all listed in order, separated
+ by spaces.</p>
+ </sect1>
+
+ <sect1 id="pkg-f-Size"><heading><tt>Size</tt> and <tt>MD5sum</tt>
+ </heading>
+
+ <p>
+ These fields in <file>Packages</file> files give the size (in
+ bytes, expressed in decimal) and MD5 checksum of the
+ file(s) which make(s) up a binary package in the
+ distribution. If the package is split into several parts
+ the values for the parts are listed in order, separated by
+ spaces.</p>
+ </sect1>
+
+ <sect1 id="pkg-f-Status"><heading><tt>Status</tt>
+ </heading>
+
+ <p>
+ 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
+ system is. Each of these pieces of information is a
+ single word.</p>
+ </sect1>
+
+ <sect1 id="pkg-f-Config-Version"><heading><tt>Config-Version</tt>
+ </heading>
+
+ <p>
+ If a package is not installed or not configured, this
+ field in <prgn>dpkg</prgn>'s status file records the last
+ version of the package which was successfully
+ configured.</p>
+ </sect1>
+
+ <sect1 id="pkg-f-Conffiles"><heading><tt>Conffiles</tt>
+ </heading>
+
+ <p>
+ This field in <prgn>dpkg</prgn>'s status file contains
+ information about the automatically-managed configuration
+ files held by a package. This field should <em>not</em>
+ appear anywhere in a package!</p>
+ </sect1>
+
+ <sect1><heading>Obsolete fields
+ </heading>
+
+ <p>
+ These are still recognised by <prgn>dpkg</prgn> but should
+ not appear anywhere any more.
+ <taglist compact="compact">
+
+ <tag><tt>Revision</tt></tag>
+ <tag><tt>Package-Revision</tt></tag>
+ <tag><tt>Package_Revision</tt></tag>
+ <item>
+ <p>
+ The Debian revision part of the package version was
+ at one point in a separate control file field. This
+ field went through several names.</p>
+ </item>
+
+ <tag><tt>Recommended</tt></tag>
+ <item><p>Old name for <tt>Recommends</tt></p>
+ </item>
+
+ <tag><tt>Optional</tt></tag>
+ <item><p>Old name for <tt>Suggests</tt>.</p>
+ </item>
+ <tag><tt>Class</tt></tag>
+ <item><p>Old name for <tt>Priority</tt>.</p>
+ </item>
+ </taglist>
+ </p>
+ </sect1>
+ </sect>
+ </appendix>
+
+ <appendix id="pkg-conffiles"><heading>Configuration file handling
+ (from old Packaging Manual)
+ </heading>
+
+ <p>
+ <prgn>dpkg</prgn> can do a certain amount of automatic
+ handling of package configuration files.
+ </p>
+
+ <p>
+ Whether this mechanism is appropriate depends on a number of
+ factors, but basically there are two approaches to any
+ particular configuration file.
+ </p>
+
+ <p>
+ The easy method is to ship a best-effort configuration in the
+ package, and use <prgn>dpkg</prgn>'s conffile mechanism to
+ handle updates. If the user is unlikely to want to edit the
+ file, but you need them to be able to without losing their
+ changes, and a new package with a changed version of the file
+ is only released infrequently, this is a good approach.
+ </p>
+
+ <p>
+ The hard method is to build the configuration file from
+ scratch in the <prgn>postinst</prgn> script, and to take the
+ responsibility for fixing any mistakes made in earlier
+ versions of the package automatically. This will be
+ appropriate if the file is likely to need to be different on
+ each system.
+ </p>
+
+ <sect><heading>Automatic handling of configuration files by
+ <prgn>dpkg</prgn>
+ </heading>
+
+ <p>
+ A package may contain a control area file called
+ <tt>conffiles</tt>. This file should be a list of filenames
+ of configuration files needing automatic handling, separated
+ by newlines. The filenames should be absolute pathnames,
+ and the files referred to should actually exist in the
+ package.
+ </p>
+
+ <p>
+ When a package is upgraded <prgn>dpkg</prgn> will process
+ the configuration files during the configuration stage,
+ shortly before it runs the package's <prgn>postinst</prgn>
+ script,
+ </p>
+
+ <p>
+ For each file it checks to see whether the version of the
+ file included in the package is the same as the one that was
+ included in the last version of the package (the one that is
+ being upgraded from); it also compares the version currently
+ installed on the system with the one shipped with the last
+ version.
+ </p>
+
+ <p>
+ If neither the user nor the package maintainer has changed
+ the file, it is left alone. If one or the other has changed
+ their version, then the changed version is preferred - i.e.,
+ if the user edits their file, but the package maintainer
+ doesn't ship a different version, the user's changes will
+ stay, silently, but if the maintainer ships a new version
+ and the user hasn't edited it the new version will be
+ installed (with an informative message). If both have
+ changed their version the user is prompted about the problem
+ and must resolve the differences themselves.
+ </p>
+
+ <p>
+ The comparisons are done by calculating the MD5 message
+ digests of the files, and storing the MD5 of the file as it
+ was included in the most recent version of the package.
+ </p>
+
+ <p>
+ 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.
+ </p>
+
+ <p>
+ However, note that <prgn>dpkg</prgn> will <em>not</em>
+ replace a conffile that was removed by the user (or by a
+ script). This is necessary because with some programs a
+ missing file produces an effect hard or impossible to
+ achieve in another way, so that a missing file needs to be
+ kept that way if the user did it.
+ </p>
+
+ <p>
+ Note that a package should <em>not</em> modify a
+ <prgn>dpkg</prgn>-handled conffile in its maintainer
+ scripts. Doing this will lead to <prgn>dpkg</prgn> giving
+ the user confusing and possibly dangerous options for
+ conffile update when the package is upgraded.</p>
+ </sect>
+
+ <sect><heading>Fully-featured maintainer script configuration
+ handling
+ </heading>
+
+ <p>
+ For files which contain site-specific information such as
+ the hostname and networking details and so forth, it is
+ better to create the file in the package's
+ <prgn>postinst</prgn> script.
+ </p>
+
+ <p>
+ This will typically involve examining the state of the rest
+ of the system to determine values and other information, and
+ may involve prompting the user for some information which
+ can't be obtained some other way.
+ </p>
+
+ <p>
+ When using this method there are a couple of important
+ issues which should be considered:
+ </p>
+
+ <p>
+ If you discover a bug in the program which generates the
+ configuration file, or if the format of the file changes
+ from one version to the next, you will have to arrange for
+ the postinst script to do something sensible - usually this
+ will mean editing the installed configuration file to remove
+ the problem or change the syntax. You will have to do this
+ very carefully, since the user may have changed the file,
+ perhaps to fix the very problem that your script is trying
+ to deal with - you will have to detect these situations and
+ deal with them correctly.
+ </p>
+
+ <p>
+ If you do go down this route it's probably a good idea to
+ make the program that generates the configuration file(s) a
+ separate program in <file>/usr/sbin</file>, by convention called
+ <file><var>package</var>config</file> and then run that if
+ appropriate from the post-installation script. The
+ <tt><var>package</var>config</tt> program should not
+ unquestioningly overwrite an existing configuration - if its
+ mode of operation is geared towards setting up a package for
+ the first time (rather than any arbitrary reconfiguration
+ later) you should have it check whether the configuration
+ already exists, and require a <tt>--force</tt> flag to
+ overwrite it.</p></sect>
+ </appendix>
+
+ <appendix id="pkg-alternatives"><heading>Alternative versions of
+ an interface - <prgn>update-alternatives</prgn> (from old
+ Packaging Manual)
+ </heading>
+
+ <p>
+ When several packages all provide different versions of the
+ same program or file it is useful to have the system select a
+ default, but to allow the system administrator to change it
+ and have their decisions respected.
+ </p>
+
+ <p>
+ For example, there are several versions of the <prgn>vi</prgn>
+ editor, and there is no reason to prevent all of them from
+ being installed at once, each under their own name
+ (<prgn>nvi</prgn>, <prgn>vim</prgn> or whatever).
+ Nevertheless it is desirable to have the name <tt>vi</tt>
+ refer to something, at least by default.
+ </p>
+
+ <p>
+ If all the packages involved cooperate, this can be done with
+ <prgn>update-alternatives</prgn>.
+ </p>
+
+ <p>
+ Each package provides its own version under its own name, and
+ calls <prgn>update-alternatives</prgn> in its postinst to
+ register its version (and again in its prerm to deregister
+ it).
+ </p>
+
+ <p>
+ See the manpage <manref name="update-alternatives"
+ section="8"> for details.
+ </p>
+
+ <p>
+ If <prgn>update-alternatives</prgn> does not seem appropriate
+ you may wish to consider using diversions instead.</p>
+ </appendix>
+
+ <appendix id="pkg-diversions"><heading>Diversions - overriding a
+ package's version of a file (from old Packaging Manual)
+ </heading>
+
+ <p>
+ It is possible to have <prgn>dpkg</prgn> not overwrite a file
+ when it reinstalls the package it belongs to, and to have it
+ put the file from the package somewhere else instead.
+ </p>
+
+ <p>
+ This can be used locally to override a package's version of a
+ file, or by one package to override another's version (or
+ provide a wrapper for it).
+ </p>
+
+ <p>
+ Before deciding to use a diversion, read <ref
+ id="pkg-alternatives"> to see if you really want a diversion
+ rather than several alternative versions of a program.
+ </p>
+
+ <p>
+ There is a diversion list, which is read by <prgn>dpkg</prgn>,
+ and updated by a special program <prgn>dpkg-divert</prgn>.
+ Please see <manref name="dpkg-divert" section="8"> for full
+ details of its operation.
+ </p>
+
+ <p>
+ When a package wishes to divert a file from another, it should
+ call <prgn>dpkg-divert</prgn> in its preinst to add the
+ diversion and rename the existing file. For example,
+ supposing that a <prgn>smailwrapper</prgn> package wishes to
+ install a wrapper around <file>/usr/sbin/smail</file>:
+ <example>
+ if [ install = "$1" ]; then
+ dpkg-divert --package smailwrapper --add --rename \
+ --divert /usr/sbin/smail.real /usr/sbin/smail
+ fi
+ </example> Testing <tt>$1</tt> is necessary so that the script
+ doesn't try to add the diversion again when
+ <prgn>smailwrapper</prgn> is upgraded. The <tt>--package
+ smailwrapper</tt> ensures that <prgn>smailwrapper</prgn>'s
+ copy of <file>/usr/sbin/smail</file> can bypass the diversion and
+ get installed as the true version.
+ </p>
+
+ <p>
+ The postrm has to do the reverse:
+ <example>
+ if [ remove = "$1" ]; then
+ dpkg-divert --package smailwrapper --remove --rename \
+ --divert /usr/sbin/smail.real /usr/sbin/smail
+ fi
+ </example>
+ </p>
+
+ <p>
+ Do not attempt to divert a file which is vitally important for
+ the system's operation - when using <prgn>dpkg-divert</prgn>
+ there is a time, after it has been diverted but before
+ <prgn>dpkg</prgn> has installed the new version, when the file
+ does not exist.</p>
+ </appendix>
+
</book>
</debiandoc>
+<!-- vim:set ai et sts=2 sw=2 tw=76: -->
projects / debian / debian-policy.git / blobdiff