<!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>
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. The current 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>
</abstract>
-
<copyright>
<copyrightsummary>
- Copyright ©1996,1997,1998 Ian Jackson
+ Copyright © 1996,1997,1998 Ian Jackson
and Christian Schwarz.
</copyrightsummary>
<p>
<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
<taglist compact="compact">
<tag>Standard interfaces</tag>
<item>
- <p>
The material presented represents an interface to
the packaging system that is mandated for use, and
is used by, a significant number of packages, and
compatibility with these interface
definitions. (Control file and changelog file
formats are examples.)
- </p>
</item>
<tag>Chosen Convention</tag>
<item>
- <p>
If there are a number of technically viable choices
that can be made, but one needs to select one of
these options for inter-operability. The version
number format is one example.
- </p>
</item>
</taglist>
Please note that these are not mutually exclusive;
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
<em>may</em> (or <em>optional</em>) are truly optional and
adherence is left to the maintainer's discretion.
</p>
+
<p>
These classifications are roughly equivalent to the bug
severities <em>serious</em> (for <em>must</em> or
<em>normal</em> or <em>important</em>
(for <em>should</em> or <em>recommended</em> directive
violations) and <em>wishlist</em> (for <em>optional</em>
- items).<footnote>
- <p>Compare RFC 2119. Note, however, that these words are
- used in a different way in this document.</p>
+ items).
+ <footnote>
+ Compare RFC 2119. Note, however, that these words are
+ used in a different way in this document.
</footnote>
</p>
+
<p>
Much of the information presented in this manual will be
useful even when building a package which is to be
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: <file>policy.html.tar.gz</file>, <file>policy.pdf.gz</file>
- and <file>policy.ps.gz</file>) 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
- <file>debian-policy</file>.
+ 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
+ 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>
+
+ <sect id="related">
+ <heading>Related documents</heading>
+
+ <p>
+ There are several other documents other than this Policy Manual
+ that are necessary to fully understand some Debian policies and
+ procedures.
+ </p>
+
+ <p>
+ The external "sub-policy" documents are referred to in:
+ <list compact="compact">
+ <item><ref id="fhs"></item>
+ <item><ref id="virtual_pkg"></item>
+ <item><ref id="menus"></item>
+ <item><ref id="mime"></item>
+ <item><ref id="perl"></item>
+ <item><ref id="maintscriptprompt"></item>
+ <item><ref id="emacs"></item>
+ </list>
+ </p>
+
+ <p>
+ In addition to those, which carry the weight of policy, there
+ is the Debian Developer's Reference. This document describes
+ procedures and resources for Debian developers, but it is
+ <em>not</em> normative; rather, it includes things that don't
+ belong into the Policy, such as best practices for developers.
+ </p>
+
+ <p>
+ The Developer's Reference is available in the
+ <package>developers-reference</package> package.
+ It's also available from the Debian web mirrors at
+ <tt><url name="/doc/developers-reference/"
+ id="http://www.debian.org/doc/developers-reference/"></tt>.
+ </p>
</sect>
+
</chapt>
+
<chapt id="archive">
<heading>The Debian Archive</heading>
+
<p>
The Debian GNU/Linux system is maintained and distributed as a
collection of <em>packages</em>. Since there are so many of
<em>sections</em> and given <em>priorities</em> to simplify
the handling of them.
</p>
+
<p>
The effort of the Debian project is to build a free operating
system, but not every package we want to make accessible is
<list compact="compact">
<item>
- <p>to allow us to make as much software available as we
- can,</p>
+ to allow us to make as much software available as we can,
</item>
<item>
- <p>to allow us to encourage everyone to write free
- software, and</p>
+ to allow us to encourage everyone to write free software, and
</item>
<item>
- <p>to allow us to make it easy for people to produce
+ to allow us to make it easy for people to produce
CD-ROMs of our system without violating any licenses,
- import/export restrictions, or any other laws.</p>
+ import/export restrictions, or any other laws.
</item>
</list>
</p>
<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>
<item>
- <p>
The license of a Debian component may not restrict any
party from selling or giving away the software as a
component of an aggregate software distribution
containing programs from several different
sources. The license may not require a royalty or
other fee for such sale.
- </p>
</item>
<tag>Source Code
</tag>
<item>
- <p>
The program must include source code, and must allow
distribution in source code as well as compiled form.
- </p>
</item>
<tag>Derived Works
</tag>
<item>
- <p>
The license must allow modifications and derived
works, and must allow them to be distributed under the
same terms as the license of the original software.
- </p>
</item>
<tag>Integrity of The Author's Source Code
</tag>
<item>
- <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
original software. (This is a compromise. The Debian
Project encourages all authors to not restrict any
files, source or binary, from being modified.)
- </p>
</item>
<tag>No Discrimination Against Persons or Groups
</tag>
<item>
- <p>
The license must not discriminate against any person
or group of persons.
- </p>
</item>
<tag>No Discrimination Against Fields of Endeavor
</tag>
<item>
- <p>
The license must not restrict anyone from making use
of the program in a specific field of endeavor. For
example, it may not restrict the program from being
used in a business, or from being used for genetic
research.
- </p>
</item>
<tag>Distribution of License
</tag>
<item>
- <p>
The rights attached to the program must apply to all
to whom the program is redistributed without the need
for execution of an additional license by those
parties.
- </p>
</item>
<tag>License Must Not Be Specific to Debian
</tag>
<item>
- <p>
The rights attached to the program must not depend on
the program's being part of a Debian system. If the
program is extracted from Debian and used or
the program is redistributed must have the same
rights as those that are granted in conjunction with
the Debian system.
- </p>
</item>
<tag>License Must Not Contaminate Other Software
</tag>
<item>
- <p>
The license must not place restrictions on other
software that is distributed along with the licensed
software. For example, the license must not insist
that all other programs distributed on the same medium
must be free software.
- </p>
</item>
<tag>Example Licenses
</tag>
<item>
- <p>
- The ``GPL,'' ``BSD,'' and ``Artistic'' licenses are
- examples of licenses that we consider <em>free</em>.
- </p>
+ The "GPL," "BSD," and "Artistic" licenses are examples of
+ licenses that we consider <em>free</em>.
</item>
</taglist>
</p>
<p>
Every package in <em>main</em> and <em>non-US/main</em>
must comply with the DFSG (Debian Free Software
- Guidelines).</p>
+ Guidelines).
+ </p>
<p>
In addition, the packages in <em>main</em>
<list compact="compact">
<item>
- <p>
must not require a package outside of <em>main</em>
for compilation or execution (thus, the package must
not declare a "Depends", "Recommends", or
"Build-Depends" relationship on a non-<em>main</em>
package),
- </p>
</item>
<item>
- <p>
must not be so buggy that we refuse to support them,
and
- </p>
</item>
<item>
- <p>
must meet all policy requirements presented in this
manual.
- </p>
</item>
</list>
</p>
+
<p>
Similarly, the packages in <em>non-US/main</em>
<list compact="compact">
<item>
- <p>
must not require a package outside of <em>main</em>
or <em>non-US/main</em> for compilation or
execution,
- </p>
</item>
<item>
- <p>
must not be so buggy that we refuse to support them,
- </p>
</item>
<item>
- <p>
must meet all policy requirements presented in this
manual.
- </p>
</item>
</list>
</p>
+
</sect1>
- <sect1>
+
+ <sect1 id="contrib">
<heading>The contrib section</heading>
+
<p>
Every package in <em>contrib</em> and
<em>non-US/contrib</em> must comply with the DFSG.
<em>non-US/contrib</em>
<list compact="compact">
<item>
- <p>
must not be so buggy that we refuse to support them,
and
- </p>
</item>
<item>
- <p>
must meet all policy requirements presented in this
manual.
- </p>
</item>
</list>
</p>
<em>contrib</em> or <em>non-US/contrib</em> are:
<list compact="compact">
<item>
- <p>
free packages which require <em>contrib</em>,
<em>non-free</em> packages or packages which are not
in our archive at all for compilation or execution,
and
- </p>
</item>
<item>
- <p>
wrapper packages or other sorts of free accessories for
non-free programs.
- </p>
</item>
</list>
</p>
</sect1>
- <sect1>
+
+ <sect1 id="non-free">
<heading>The non-free section</heading>
+
<p>
Packages must be placed in <em>non-free</em> or
<em>non-US/non-free</em> if they are not compliant with
the DFSG or are encumbered by patents or other legal
issues that make their distribution problematic.
</p>
+
<p>
In addition, the packages in <em>non-free</em> and
<em>non-US/non-free</em>
<list compact="compact">
<item>
- <p>
must not be so buggy that we refuse to support them,
and
- </p>
</item>
<item>
- <p>
must meet all policy requirements presented in this
- manual that it is possible for them to meet.<footnote>
- <p>
+ manual that it is possible for them to meet.
+ <footnote>
It is possible that there are policy
requirements which the package is unable to
meet, for example, if the source is
unavailable. These situations will need to be
handled on a case-by-case basis.
- </p>
</footnote>
- </p>
</item>
</list>
</p>
</sect1>
- <sect1>
+ <sect1 id="non-US">
<heading>The non-US sections</heading>
+
+ <p>
+ Non-free programs with cryptographic program code need to
+ be stored on the <em>non-us</em> server because of export
+ restrictions of the U.S.
+ </p>
+
<p>
- 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>.
+ 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>
anywhere in our archives if
<list compact="compact">
<item>
- <p>
their use or distribution would break a law,
- </p>
</item>
<item>
- <p>
there is an ethical conflict in their distribution or
use,
- </p>
</item>
<item>
- <p>
we would have to sign a license for them, or
- </p>
</item>
<item>
- <p>
their distribution would conflict with other project
policies.
- </p>
</item>
</list>
</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>
should be of the form:
<list compact="compact">
<item>
- <p>
<em>subsection</em> if the package is in the
<em>main</em> section,
- </p>
</item>
<item>
- <p>
<em>section/subsection</em> if the package is in
the <em>contrib</em> or <em>non-free</em> section,
and
- </p>
</item>
<item>
- <p>
<tt>non-US</tt>, <tt>non-US/contrib</tt> or
<tt>non-US/non-free</tt> if the package is in
<em>non-US/main</em>, <em>non-US/contrib</em> or
<em>non-US/non-free</em> respectively.
- </p>
</item>
</list>
</p>
<taglist>
<tag><tt>required</tt></tag>
<item>
- <p>
Packages which are necessary for the proper
functioning of the system. You must not remove these
packages or your system may become totally broken and
put things back. Systems with only the
<tt>required</tt> packages are probably unusable, but
they do have enough functionality to allow the
- sysadmin to boot and install more software.</p>
+ sysadmin to boot and install more software.
</item>
<tag><tt>important</tt></tag>
<item>
- <p>
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
trying to produce, amongst other things, a free
Unix.
- </p>
</footnote>
Other packages without which the system will not run
well or be usable must also have priority
<em>not</em> include Emacs, the X Window System, TeX
or any other large applications. The
<tt>important</tt> packages are just a bare minimum of
- commonly-expected and necessary tools.</p>
+ commonly-expected and necessary tools.
</item>
<tag><tt>standard</tt></tag>
<item>
- <p>
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.</p>
+ else. It doesn't include many large applications.
</item>
<tag><tt>optional</tt></tag>
<item>
- <p>
(In a sense everything that isn't required is
optional, but that's not what is meant here.) This is
all the software that you might reasonably want to
and includes the X Window System, a full TeX
distribution, and many applications. Note that
optional packages should not conflict with each other.
- </p>
</item>
<tag><tt>extra</tt></tag>
<item>
- <p>
This contains all packages that conflict with others
with required, important, standard or optional
priorities, or are only likely to be useful if you
already know what they are or have specialised
requirements.
- </p>
</item>
- </taglist></p>
+ </taglist>
+ </p>
<p>
Packages must not depend on packages with lower priority
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>
maintainership of the package until someone else
volunteers for that task. These packages are called
<em>orphaned packages</em>.<footnote>
- <p>
The detailed procedure for doing this gracefully can
- be found in the Debian Developer's Reference, either
- in the <tt>developers-reference</tt> package, or on
- the Debian FTP server
- <ftpsite>ftp.debian.org</ftpsite> as
- <ftppath>/debian/doc/package-developer/developers-reference.txt.gz</ftppath>
- or from the <url
- id="http://www.debian.org/doc/packaging-manuals/developers-reference/"
- name="Debian Developer's Reference"> webpage.
- </p>
+ be found in the Debian Developer's Reference,
+ see <ref id="related">.
</footnote>
</p>
</sect1>
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>
- <sect2>
+ <sect2 id="maintscriptprompt">
<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
- <file>debconf_specification</file> files in the
- <package>debian-policy</package> package.
- You may also find this file on the FTP site
- <ftpsite>ftp.debian.org</ftpsite> in
- <ftppath>/debian/doc/package-developer/debconf_specification.txt.gz</ftppath>
- or on your local mirror.<footnote>
+ necessary. Prompting may be accomplished by
+ hand<footnote>
+ From the Jargon file: by hand 2. By extension,
+ writing code which does something in an explicit or
+ low-level way for which a presupplied library
+ (<em>debconf, in this instance</em>) routine ought
+ to have been available.
+ </footnote> (but this is deprecated), or by communicating
+ through a program which conforms to the Debian Configuration
+ management specification, version 2 or higher, such as
+ <prgn>debconf</prgn><footnote>
<p>
- 4% 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
installation, elimination of redundant prompting,
consistency of user interface, etc.
</p>
+
<p>
With this increasing number of packages using
<package>debconf</package>, plus the existance of a
of the protocol these things use, the time has
finally come to reflect the use of these things in
policy.
-
</p>
- </footnote>
+ </footnote>.
+ </p>
+
+ <p>
+ The Debian Configuration management specification is included
+ in the <file>debconf_specification</file> files in the
+ <package>debian-policy</package> package.
+ It is also available from the Debian web mirrors at
+ <tt><url name="/doc/packaging-manuals/debconf_specification.html"
+ id="http://www.debian.org/doc/packaging-manuals/debconf_specification.html"></tt>
+ and from the Debian archive mirrors at
+ <tt><url name="/doc/package-developer/debconf_specification.txt.gz"
+ id="http://ftp.debian.org/debian/doc/package-developer/debconf_specification.txt.gz"></tt>.
</p>
+
<p>
Packages which use the Debian Configuration management
specification may contain an additional
dependencies or pre-dependancies are satisfied.
Therefore it must work using only the tools present in
<em>essential</em> packages.<footnote>
- <p>
<package>Debconf</package> or another tool that
implements the Debian Configuration management
specification will also be installed, and any
versioned dependencies on it will be satisfied
before preconfiguration begins.
- </p>
</footnote>
</p>
are significant in the <em>Standards-Version</em> control
field, and so either these three components or the all
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>
</footnote>
</p>
package complies with the new standards you should update the
<tt>Standards-Version</tt> source package field and
release it.<footnote>
- <p>
See the file <file>upgrading-checklist</file> for
information about policy which has changed between
different versions of this document.
- </p>
</footnote>
</p>
</sect1>
- <sect1>
+ <sect1 id="pkg-relations">
<heading>Package relationships</heading>
<p>
<file>/usr/share/doc/build-essential/list</file> (which is
contained in the <tt>build-essential</tt>
package).<footnote>
- <p>Rationale:
+ Rationale:
<list compact="compact">
<item>
- <p>This allows maintaining the list separately
+ This allows maintaining the list separately
from the policy documents (the list does not
need the kind of control that the policy
documents do).
- </p>
</item>
<item>
- <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.
- </p>
+ well as allowing other packages such as tasks to
+ require installation of the build-essential
+ packages using the depends relation.
</item>
<item>
- <p>
The separate package allows bug reports against
the list to be categorized separately from
the policy management process in the BTS.
- </p>
</item>
</list>
- </p>
-
</footnote>
</p>
build. It is not necessary to list packages which are
required merely because some other package in the list of
build-time dependencies depends on them.<footnote>
- <p>
The reason for this is that dependencies change, and
you should list all those packages, and <em>only</em>
those packages that <em>you</em> need directly. What
them: installation of <package>libimlib2-dev</package>
will automatically ensure that all of its run-time
dependencies are satisfied.
- </p>
</footnote>
</p>
are properly satisfied.
</p>
+ <p>
+ <ref id="relationships"> explains the technical details.
+ </p>
+
<sect1>
<heading>Changes to the upstream sources</heading>
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 <file>debian/changelog</file> 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
- <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 `dpkg' is.)
- </p>
- </footnote>
+ package properly in the <file>debian/changelog</file> file.
+ For more information, please see <ref id="changelogs">.
</p>
</sect1>
files</em>. Binary and source packages have control files,
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>
<taglist compact="compact">
<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
made to this distribution, the release number is
increased (for example: 2.2r1 becomes 2.2r2 then
2.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>testing</em></tag>
<item>
- <p>
This distribution value refers to the
<em>testing</em> part of the Debian distribution
tree. It receives its packages from the
than unstable, but still risky. It is not
possible to upload packages directly to
<em>testing</em>.
- </p>
</item>
<tag><em>frozen</em></tag>
<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
be allowed. The exact details of this stage are
determined by the Release Manager.
- </p>
</item>
<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
ready to be a part of the other parts of the
Debian distribution tree. Download at your own
risk.
- </p>
</item>
</taglist>
</p>
</sect1>
-
</sect>
+
</chapt>
+
<chapt id="versions"><heading>Version numbering</heading>
<p>
<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')
+ 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);
<p>
The <var>upstream_version</var> may contain only
alphanumerics<footnote>
- <p>Alphanumerics are <tt>A-Za-z0-9</tt> only.</p>
+ Alphanumerics are <tt>A-Za-z0-9</tt> only.
</footnote>
and the characters <tt>.</tt> <tt>+</tt> <tt>-</tt>
<tt>:</tt> (full stop, plus, hyphen, colon) and should
<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>
Maintainers should 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>
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 <tt>build</tt>
to depend on <prgn>build-stamp</prgn> and to do
nothing else, and for the <prgn>build-stamp</prgn>
<tt>.PHONY</tt> target). See the documentation of
<prgn>make</prgn> for more information on phony
targets.
- </p>
</footnote>
</p>
</item>
<p>
The <tt>binary</tt> targets must be invoked as
root.<footnote>
- <p>
The <prgn>fakeroot</prgn> package often allows one
to build a package correctly even without being
root.
- </p>
</footnote>
</p>
</item>
<p>
The architectures we build on and build for are determined
by <prgn>make</prgn> variables using the utility
- <prgn>dpkg-architecture</prgn>. You can determine the
+ <qref id="pkg-dpkgarch"><prgn>dpkg-architecture</prgn></qref>.
+ You can determine the
Debian architecture and the GNU style architecture
specification string for the build machine (the machine type
we are building on) as well as for the host machine (the
supported <prgn>make</prgn> variables:
<list compact="compact">
<item>
- <p><tt>DEB_*_ARCH</tt> (the Debian architecture)</p>
+ <tt>DEB_*_ARCH</tt> (the Debian architecture)
</item>
<item>
- <p><tt>DEB_*_GNU_TYPE</tt> (the GNU style architecture
- specification string)</p>
+ <tt>DEB_*_GNU_TYPE</tt> (the GNU style architecture
+ specification string)
</item>
<item>
- <p><tt>DEB_*_GNU_CPU</tt> (the CPU part of
- <tt>DEB_*_GNU_TYPE</tt>)</p>
+ <tt>DEB_*_GNU_CPU</tt> (the CPU part of
+ <tt>DEB_*_GNU_TYPE</tt>)
</item>
<item>
- <p><tt>DEB_*_GNU_SYSTEM</tt> (the System part of
- <tt>DEB_*_GNU_TYPE</tt>)</p>
+ <tt>DEB_*_GNU_SYSTEM</tt> (the System part of
+ <tt>DEB_*_GNU_TYPE</tt>)
</list>
where <tt>*</tt> is either <tt>BUILD</tt> for specification of
the build machine or <tt>HOST</tt> for specification of the
<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. In such a
case, however, it might be better to maintain the
package as a non-native package.
- </p>
</footnote>.
</p>
<prgn>dpkg</prgn> changelog format (though there is
currently only one useful <var>keyword</var>,
<tt>urgency</tt>).<footnote>
- <p>
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>
inclusion of this package into the Debian archive by
including the string: <tt>closes: Bug#<var>nnnnn</var></tt>
in the change details.<footnote>
- <p>
To be precise, the string should match the following
Perl regular expression:
<example>
Then all of the bug numbers listed will be closed by the
archive maintenance script (<prgn>katie</prgn>), or in
the case of an NMU, marked as fixed.
- </p>
</footnote>
</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 time zone specified
numerically, with the time zone name or abbreviation
optionally present as a comment in parentheses.
</p>
<p>
- The first `title' line with the package name should start
- at the left hand margin; the `trailer' line with the
+ 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>
+<!-- FIXME: section pkg-srcsubstvars is the same as srcsubstvars -->
+
<sect id="srcsubstvars"><heading><file>debian/substvars</file>
and variable substitutions </heading>
<p>
The <file>debian/substvars</file> file is usually generated and
- modified dynamically by <file>debian/rules</file> targets; in
- this case it must be removed by the <tt>clean</tt>
- target.
+ modified dynamically by <file>debian/rules</file> targets, in
+ which case it must be removed by the <tt>clean</tt> target.
</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 <tt>files</tt> here before renaming it,
to avoid leaving a corrupted copy if an error
- occurs
- </p>
+ occurs.
</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
</p>
</footnote>, device special files, sockets or setuid or
setgid files.<footnote>
- <p>
Setgid directories are allowed.
- </p>
</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>
- <p>
- Do not use tab characters. Their effect is not predictable.
- </p>
+ <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>
- </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>
- <p>
+ is OK.<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 when <prgn>dpkg</prgn> attempts to repeat the
action.
- </p>
</footnote>
</p>
</sect>
<p>
<list compact="compact">
<item>
- <p><var>new-preinst</var> <tt>install</tt></p>
+ <var>new-preinst</var> <tt>install</tt>
</item>
<item>
- <p><var>new-preinst</var> <tt>install</tt>
- <var>old-version</var></p>
+ <var>new-preinst</var> <tt>install</tt> <var>old-version</var>
</item>
<item>
- <p><var>new-preinst</var> <tt>upgrade</tt>
- <var>old-version</var></p>
+ <var>new-preinst</var> <tt>upgrade</tt> <var>old-version</var>
</item>
<item>
- <p><var>old-preinst</var> <tt>abort-upgrade</tt>
+ <var>old-preinst</var> <tt>abort-upgrade</tt>
<var>new-version</var>
- </p>
</item>
</list>
<p>
<list compact="compact">
<item>
- <p><var>postinst</var> <tt>configure</tt>
- <var>most-recently-configured-version</var></p>
+ <var>postinst</var> <tt>configure</tt>
+ <var>most-recently-configured-version</var>
</item>
<item>
- <p><var>old-postinst</var> <tt>abort-upgrade</tt>
- <var>new-version</var></p>
+ <var>old-postinst</var> <tt>abort-upgrade</tt>
+ <var>new-version</var>
</item>
<item>
- <p><var>conflictor's-postinst</var> <tt>abort-remove</tt>
+ <var>conflictor's-postinst</var> <tt>abort-remove</tt>
<tt>in-favour</tt> <var>package</var>
- <var>new-version</var></p>
+ <var>new-version</var>
</item>
<item>
- <p>
<var>deconfigured's-postinst</var>
<tt>abort-deconfigure</tt> <tt>in-favour</tt>
<var>failed-install-package</var> <var>version</var>
<tt>removing</tt> <var>conflicting-package</var>
<var>version</var>
- </p>
</item>
</list>
<p>
<list compact="compact">
<item>
- <p><var>prerm</var> <tt>remove</tt></p>
+ <var>prerm</var> <tt>remove</tt>
</item>
<item>
- <p><var>old-prerm</var> <tt>upgrade</tt>
- <var>new-version</var></p>
+ <var>old-prerm</var> <tt>upgrade</tt>
+ <var>new-version</var>
</item>
<item>
- <p><var>new-prerm</var> <tt>failed-upgrade</tt>
- <var>old-version</var></p>
+ <var>new-prerm</var> <tt>failed-upgrade</tt>
+ <var>old-version</var>
</item>
<item>
- <p><var>conflictor's-prerm</var> <tt>remove</tt>
+ <var>conflictor's-prerm</var> <tt>remove</tt>
<tt>in-favour</tt> <var>package</var>
- <var>new-version</var></p>
+ <var>new-version</var>
</item>
<item>
- <p>
<var>deconfigured's-prerm</var> <tt>deconfigure</tt>
<tt>in-favour</tt> <var>package-being-installed</var>
<var>version</var> <tt>removing</tt>
<var>conflicting-package</var>
<var>version</var>
- </p>
</item>
</list>
<p>
<list compact="compact">
<item>
- <p><var>postrm</var> <tt>remove</tt></p>
+ <var>postrm</var> <tt>remove</tt>
</item>
<item>
- <p><var>postrm</var> <tt>purge</tt></p>
+ <var>postrm</var> <tt>purge</tt>
</item>
<item>
- <p>
<var>old-postrm</var> <tt>upgrade</tt>
- <var>new-version</var></p>
+ <var>new-version</var>
</item>
<item>
- <p><var>new-postrm</var> <tt>failed-upgrade</tt>
- <var>old-version</var></p>
+ <var>new-postrm</var> <tt>failed-upgrade</tt>
+ <var>old-version</var>
</item>
<item>
- <p><var>new-postrm</var> <tt>abort-install</tt></p>
+ <var>new-postrm</var> <tt>abort-install</tt>
</item>
<item>
- <p><var>new-postrm</var> <tt>abort-install</tt>
- <var>old-version</var></p>
+ <var>new-postrm</var> <tt>abort-install</tt>
+ <var>old-version</var>
</item>
<item>
- <p><var>new-postrm</var> <tt>abort-upgrade</tt>
- <var>old-version</var></p>
+ <var>new-postrm</var> <tt>abort-upgrade</tt>
+ <var>old-version</var>
</item>
<item>
- <p>
<var>disappearer's-postrm</var> <tt>disappear</tt>
<var>overwriter</var>
- <var>overwriter-version</var></p></item>
+ <var>overwriter-version</var>
+ </item>
</list>
</p>
- <sect id="unpackphase"><heading>Details of unpack phase of
- installation or upgrade
- </heading>
+ <sect id="unpackphase">
+ <heading>Details of unpack phase of installation or upgrade</heading>
<p>
The procedure on installation/upgrade/overwrite/disappear
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>
<item>
- <p>
<enumlist>
<item>
- <p>If a version of the package is already
- installed, call
+ If a version of the package is already installed, call
<example compact="compact">
<var>old-prerm</var> upgrade <var>new-version</var>
- </example></p>
+ </example>
</item>
<item>
- <p>
If the script runs but exits with a non-zero
exit status, <prgn>dpkg</prgn> will attempt:
<example compact="compact">
<example compact="compact">
<var>old-postinst</var> abort-upgrade <var>new-version</var>
</example>
- </p>
</item>
</enumlist>
- </p>
</item>
+
<item>
- <p>If a `conflicting' package is being removed at the same time:
+ If a "conflicting" package is being removed at the same time:
<enumlist>
<item>
- <p>
If any packages depended on that conflicting
package and <tt>--auto-deconfigure</tt> is
specified, call, for each such package:
The deconfigured packages are marked as
requiring configuration, so that if
<tt>--install</tt> is used they will be
- configured again if possible.</p>
+ configured again if possible.
</item>
<item>
- <p>To prepare for removal of the conflicting package, call:
+ To prepare for removal of the conflicting package, call:
<example compact="compact">
<var>conflictor's-prerm</var> remove \
in-favour <var>package</var> <var>new-version</var>
<var>conflictor's-postinst</var> abort-remove \
in-favour <var>package</var> <var>new-version</var>
</example>
- </p>
</item>
</enumlist>
- </p>
</item>
+
<item>
- <p>
<enumlist>
<item>
- <p>If the package is being upgraded, call:
+ If the package is being upgraded, call:
<example compact="compact">
<var>new-preinst</var> upgrade <var>old-version</var>
- </example></p>
+ </example>
</item>
<item>
- <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>
-
+ </example>
+ </item>
<item>
- <p>Otherwise (i.e., the package was completely purged):
+ Otherwise (i.e., the package was completely purged):
<example compact="compact">
<var>new-preinst</var> install
</example>
<var>new-postrm</var> abort-install <var>old-version</var>
<var>new-postrm</var> abort-install
</example>
- </p>
</item>
</enumlist>
- </p>
</item>
+
<item>
<p>
The new package's files are unpacked, overwriting any
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>
Part of the problem is due to what is arguably a
bug in <prgn>dpkg</prgn>.
- </p>
</footnote>
</p>
to a directory or vice versa; instead, the existing
state (symlink or not) will be left alone and
<prgn>dpkg</prgn> will follow the symlink if there is
- one.</p>
+ one.
+ </p>
</item>
<item>
<p>
<enumlist>
<item>
- <p>If the package is being upgraded, call
+ If the package is being upgraded, call
<example compact="compact">
<var>old-postrm</var> upgrade <var>new-version</var>
</example>
- </p>
</item>
<item>
-
<p>If this fails, <prgn>dpkg</prgn> will attempt:
+
If this fails, <prgn>dpkg</prgn> will attempt:
<example compact="compact">
<var>new-postrm</var> failed-upgrade <var>old-version</var>
</example>
<example compact="compact">
<var>old-preinst</var> abort-upgrade <var>new-version</var>
</example>
- </p>
</item>
</enumlist>
</p>
+
<p>
This is the point of no return - if
<prgn>dpkg</prgn> gets this far, it won't back off
things that are irreversible.
</p>
</item>
+
<item>
- <p>
Any files which were in the old version of the package
- but not in the new are removed.</p>
+ but not in the new are removed.
</item>
+
<item>
- <p>The new file list replaces the old.</p>
+ The new file list replaces the old.
</item>
+
<item>
- <p>The new maintainer scripts replace the old.</p>
+ The new maintainer scripts replace the old.
</item>
<item>
- <p>Any packages all of whose files have been overwritten during the
- installation, and which aren't required for
+ Any packages all of whose files have been overwritten
+ during the installation, and which aren't required for
dependencies, are considered to have been removed.
For each such package
<enumlist>
<item>
-
<p><prgn>dpkg</prgn> calls:
+
<prgn>dpkg</prgn> calls:
<example compact="compact">
<var>disappearer's-postrm</var> disappear \
<var>overwriter</var> <var>overwriter-version</var>
</example>
- </p>
</item>
<item>
- <p>The package's maintainer scripts are removed.
- </p>
+ The package's maintainer scripts are removed.
</item>
<item>
- <p>
It is noted in the status database as being in a
sane state, namely not installed (any conffiles
it may have are ignored, rather than being
called, because <prgn>dpkg</prgn> doesn't know
in advance that the package is going to
vanish.
- </p>
</item>
</enumlist>
- </p>
</item>
+
<item>
- <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.)
- </p>
+ of the "conflicting" package if there is one.)
</item>
+
<item>
- <p>
The backup files made during installation, above, are
deleted.
- </p>
</item>
<item>
<p>
The new package's status is now sane, and recorded as
- `unpacked'.
+ "unpacked".
</p>
<p>
</item>
<item>
- <p>
If there was a conflicting package we go and do the
removal actions (described below), starting with the
removal of the conflicting package's files (any that
are also in the package being installed have already
been removed from the conflicting package's file list,
and so do not get removed now).
- </p>
</item>
</enumlist>
</p>
<p>
<enumlist>
<item>
- <p>
<example compact="compact">
<var>prerm</var> remove
</example>
- </p>
</item>
<item>
- <p>
The package's files are removed (except <tt>conffile</tt>s).
- </p>
</item>
<item>
- <p>
<example compact="compact">
<var>postrm</var> remove
</example>
- </p>
</item>
<item>
<p>
that packages which have no <prgn>postrm</prgn> and no
<tt>conffile</tt>s are automatically purged when
removed, as there is no difference except for the
- <prgn>dpkg</prgn> status.</p>
+ <prgn>dpkg</prgn> status.
+ </p>
</item>
<item>
- <p>
The <tt>conffile</tt>s and any backup files
(<tt>~</tt>-files, <tt>#*#</tt> files,
<tt>%</tt>-files, <tt>.dpkg-{old,new,tmp}</tt>, etc.)
- are removed.</p>
+ are removed.
</item>
<item>
- <p>
<example compact="compact">
<var>postrm</var> purge
</example>
- </p>
</item>
<item>
- <p>The package's file list is removed.</p>
+ The package's file list is removed.
</item>
</enumlist>
+
No attempt is made to unwind after errors during
removal.
</p>
</chapt>
- <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>
+ <chapt id="relationships">
+ <heading>Declaring relationships between packages</heading>
- <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>
+ <sect id="depsyntax">
+ <heading>Syntax of relationship fields</heading>
<p>
These fields all have a uniform syntax. They are a list of
<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
package to provide a significant amount of
functionality.
</p>
+
<p>
The <tt>Depends</tt> field should also be used if the
<prgn>postinst</prgn>, <prgn>prerm</prgn> or
<tag><tt>Recommends</tt></tag>
<item>
- <p>This declares a strong, but not absolute, dependency.
+ <p>
+ This declares a strong, but not absolute, dependency.
</p>
<p>
The <tt>Recommends</tt> field should list packages
that would be found together with this one in all but
- unusual installations.</p>
+ unusual installations.
+ </p>
</item>
<tag><tt>Suggests</tt></tag>
<item>
- <p>
This is used to declare that one package may be more
useful with one or more others. Using this field
tells the packaging system and the user that the
listed packages are related to this one and can
perhaps enhance its usefulness, but that installing
this one without them is perfectly reasonable.
- </p>
</item>
<tag><tt>Enhances</tt></tag>
<item>
- <p>
This field is similar to Suggests but works in the
opposite direction. It is used to declare that a
package can enhance the functionality of another
package.
- </p>
</item>
<tag><tt>Pre-Depends</tt></tag>
<prgn>preinst</prgn> script depends on the named
package. It is best to avoid this situation if
possible.
+ </p>
</item>
</taglist>
</p>
+
<p>
When selecting which level of dependency to use you should
consider how important the depended-on package is to the
Recommendations, as appropriate to the components' relative
importance.
</p>
+ </sect>
-
- <sect id="conflicts"><heading>Conflicting binary packages -
- <tt>Conflicts</tt></heading>
+ <sect id="conflicts">
+ <heading>Conflicting binary packages - <tt>Conflicts</tt></heading>
<p>
When one binary package declares a conflict with another
<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>
<item>
- <p>
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>.
- </p>
+ <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>.
</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>.
- </p>
+ invoked: <tt>build</tt>, <tt>clean</tt>,
+ <tt>build-indep</tt>, <tt>binary</tt> and
+ <tt>binary-indep</tt>.
</item>
</taglist>
</p>
</sect>
+
</chapt>
- <chapt id="conffiles"><heading>Configuration file handling
- </heading>
+ <chapt id="conffiles">
+ <heading>Configuration file handling</heading>
<p>
This chapter has been superseded by <ref id="config-files">.
</p>
+ </chapt>
<chapt id="sharedlibs"><heading>Shared libraries</heading>
</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
+ 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>
+ 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>.
+ </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
</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
+ 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
time that <prgn>dpkg</prgn> installs it and the time that
<prgn>ldconfig</prgn> is run in the <prgn>postinst</prgn>
script.<footnote>
- <p>
The package management system requires the library to be
placed before the symbolic link pointing to it in the
<file>.deb</file> file. This is so that when
<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
- <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>
+ <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
- <file>/usr/lib</file> and <file>/lib</file>) or a directory that is
- listed in <file>/etc/ld.so.conf</file><footnote>
- <p>
+ <p>
+ Any package installing shared libraries in one of the default
+ library directories of the dynamic linker (which are currently
+ <file>/usr/lib</file> and <file>/lib</file>) or a directory that is
+ listed in <file>/etc/ld.so.conf</file><footnote>
These are currently
<list compact="compact">
- <item><p>/usr/X11R6/lib/Xaw3d</p></item>
- <item><p>/usr/local/lib</p></item>
- <item><p>/usr/lib/libc5-compat</p></item>
- <item><p>/lib/libc5-compat</p></item>
- <item><p>/usr/X11R6/lib</p></item>
+ <item>/usr/X11R6/lib/Xaw3d</item>
+ <item>/usr/local/lib</item>
+ <item>/usr/lib/libc5-compat</item>
+ <item>/lib/libc5-compat</item>
+ <item>/usr/X11R6/lib</item>
</list>
- </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>.
+ </footnote>
+ 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>
+ 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>
<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!
+ 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>
- <heading>Handling shared library dependencies - the
- <tt>shlibs</tt> system</heading>
+ <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
<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
<list>
<item>
<p><file>debian/shlibs.local</file></p>
+
<p>
This lists overrides for this package. Its use is
described below (see <ref id="shlibslocal">).
<item>
<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><file>DEBIAN/shlibs</file> files in the `build directory'</p>
+ <p><file>DEBIAN/shlibs</file> files in the "build directory"</p>
+
<p>
When packages are being built, any
<file>debian/shlibs</file> files are copied into the
given the name <file>shlibs</file>. These files give
details of any shared libraries included in the
package.<footnote>
- <p>
An example may help here. Let us say that the
source package <tt>foo</tt> generates two binary
packages, <tt>libfoo2</tt> and
all of the individual binary packages'
<tt>shlibs</tt> files have been installed into the
build directory.
- </p>
</footnote>
</p>
</item>
<item>
<p><file>/var/lib/dpkg/info/*.shlibs</file></p>
+
<p>
These are the <file>shlibs</file> files corresponding to
all of the packages installed on the system, and are
<item>
<p><file>/etc/dpkg/shlibs.default</file></p>
+
<p>
This file lists any shared libraries whose packages
have failed to provide correct <file>shlibs</file> files.
</item>
</list>
</p>
- </sect>
+ </sect1>
- <sect>
+ <sect1>
<heading>How to use <prgn>dpkg-shlibdeps</prgn> and the
<file>shlibs</file> files</heading>
</example>
Otherwise, you will need to explicitly list the compiled
binaries and libraries.<footnote>
- <p>
If you are using <tt>debhelper</tt>, the
<prgn>dh_shlibdeps</prgn> program will do this work for
you. It will also correctly handle multi-binary
packages.
- </p>
</footnote>
</p>
For more details on this and other options, see <manref
name="dpkg-shlibdeps" section="1">.
</p>
- </sect>
+ </sect1>
- <sect id="shlibs"><heading>The <file>shlibs</file> File Format
- </heading>
+ <sect1 id="shlibs">
+ <heading>The <file>shlibs</file> File Format</heading>
<p>
Each <file>shlibs</file> file has the same format. Lines
dynamic linker, and is usually of the form
<tt><var>name</var>.so.<var>major-version</var></tt>, in our
example, <tt>libz.so.1</tt>.<footnote>
- <p>
This can be determined using the command
<example compact="compact">
objdump -p /usr/lib/libz.so.1.1.3 | grep SONAME
</example>
- </p>
</footnote>
The version part is the part which comes after
<tt>.so.</tt>, so in our case, it is <tt>1</tt>.
the dynamic linker about using older shared libraries with
newer binaries.
</p>
- </sect>
+ </sect1>
- <sect>
+ <sect1>
<heading>Providing a <file>shlibs</file> file</heading>
<p>
<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 <file>debian/shlibs</file> file itself is ignored by
<prgn>dpkg-shlibdeps</prgn>.
<prgn>dpkg-shlibdeps</prgn> is called on any of the binary
packages.
</p>
- </sect>
+ </sect1>
- <sect id="shlibslocal">
+ <sect1 id="shlibslocal">
<heading>Writing the <file>debian/shlibs.local</file> file</heading>
<p>
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>
<heading>Filesystem hierarchy</heading>
- <sect1>
+ <sect1 id="fhs">
<heading>Filesystem Structure</heading>
<p>
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
+ package or on
<url id="http://www.debian.org/doc/packaging-manuals/fhs/"
- name="FHS (Debian copy)"> alongside this manual. The
+ 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 the FHS mailing list (see the
+ referred to the FHS mailing list (see the
<url id="http://www.pathname.com/fhs/" name="FHS web site"> for
- more information).
+ more information).
</p>
</sect1>
<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>
<p>
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>
<taglist>
<tag><tt>start</tt></tag>
- <item><p>start the service,</p></item>
+ <item>start the service,</item>
<tag><tt>stop</tt></tag>
- <item><p>stop the service,</p></item>
+ <item>stop the service,</item>
<tag><tt>restart</tt></tag>
- <item><p>stop and restart the service,</p></item>
+ <item>stop and restart the service if it's already running,
+ otherwise start the service</item>
<tag><tt>reload</tt></tag>
<item><p>cause the configuration of the service to be
reloaded without actually stopping and restarting
- the service,</p></item>
+ the service,</item>
<tag><tt>force-reload</tt></tag>
- <item><p>cause the configuration to be reloaded if the
+ <item>cause the configuration to be reloaded if the
service supports this, otherwise restart the
- service.</p></item>
+ service.</item>
</taglist>
The <tt>start</tt>, <tt>stop</tt>, <tt>restart</tt>, and
<tt>force-reload</tt> options should be supported by all
scripts in <file>/etc/init.d</file>, the <tt>reload</tt>
- option is optional.</p>
+ option is optional.
+ </p>
<p>
The <file>init.d</file> scripts should ensure that they will
service is already running, or with <tt>stop</tt> when it
isn't, and that they don't kill unfortunately-named user
processes. The best way to achieve this is usually to use
- <prgn>start-stop-daemon</prgn>.</p>
+ <prgn>start-stop-daemon</prgn>.
+ </p>
<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 <file>init.d</file> script
should behave as if the configuration has been reloaded
- successfully.</p>
+ successfully.
+ </p>
<p>
The <file>/etc/init.d</file> scripts must be treated as
must contain only variable settings and comments in POSIX
<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.
+ the package maintainer scripts. See <ref id="config-files">
+ for more details.
</p>
<p>
</sect1>
<sect1>
- <heading>Managing the links</heading>
-
- <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>
+ <heading>Interfacing with the initscript system</heading>
<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.)
+ 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 <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.
+ 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>
-
- <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>
+ <sect2>
+ <heading>Managing the links</heading>
- <p>
- For more information about using <tt>update-rc.d</tt>,
- please consult its manpage <manref name="update-rc.d"
- section="8">.
- </p>
- </sect1>
+ <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>
+ 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>
+ In the future, the use of invoke-rc.d to invoke
+ initscripts shall be made mandatory. Maintainers are
+ advised to switch to invoke-rc.d as soon as
+ possible.
+ </footnote>, instead of calling them directly.
+ </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>
<sect1>
<heading>Boot-time initialization</heading>
boot. This has been deprecated in favour of links from
<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 <file>/etc/rc.boot</file>.</p>
+ place files in <file>/etc/rc.boot</file>.
+ </p>
+ </sect1>
<sect1>
<heading>Example</heading>
interprets the argument <tt>reload</tt> to send the
nameserver a <tt>HUP</tt> signal (causing it to reload its
configuration); this way the system administrator can say
- <file>/etc/init.d/bind reload</file> to reload the name
+ <tt>/etc/init.d/bind reload</tt> to reload the name
server. The script has one configurable value, which can
be used to pass parameters to the named program at
startup; this value is read from
<p>
<list>
<item>
- <p>
Every message should fit in one line (fewer than 80
characters), start with a capital letter and end with
a period (<tt>.</tt>) and line feed (<tt>"\n"</tt>).
- </p>
</item>
<item>
- <p>
If you want to express that the computer is working on
something (that is, performing a specific task, not
starting or stopping a program), we use an "ellipsis"
(three dots: <tt>...</tt>). Note that we don't insert
spaces before or after the dots. If the task has been
completed we write <tt>done.</tt> and a line feed.
- </p>
</item>
<item>
- <p>
Design your messages as if the computer is telling you
what he is doing (let him be polite :-), but don't
mention "him" directly. For example, if you think of
<example compact="compact">
Starting network daemons: nfsd mountd.
</example>
- </p>
</item>
</list>
</p>
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>
are kept on the system in this situation.</p>
</sect>
- <sect>
+ <sect id="menus">
<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>
</p>
</sect>
- <sect>
+ <sect id="mime">
<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>
<taglist>
<tag><tt><--</tt></tag>
- <item><p>delete the character to the left of the cursor</p></item>
+ <item>delete the character to the left of the cursor</item>
<tag><tt>Delete</tt></tag>
- <item><p>delete the character to the right of the cursor</p></item>
+ <item>delete the character to the right of the cursor</item>
<tag><tt>Control+H</tt></tag>
- <item><p>emacs: the help prefix</p></item>
+ <item>emacs: the help prefix</item>
</taglist>
The interpretation of any keyboard events should be
<p>
<list>
- <item><p><tt><--</tt> generates <tt>KB_Backspace</tt>
- in X.</p></item>
+ <item>
+ <tt><--</tt> generates <tt>KB_BackSpace</tt> in X.
+ </item>
- <item><p><tt>Delete</tt> generates <tt>KB_Delete</tt> in
- X.</p></item>
+ <item>
+ <tt>Delete</tt> generates <tt>KB_Delete</tt> in X.
+ </item>
<item>
- <p>
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
translation resources used correspond to the
- <prgn>xmodmap</prgn> settings.</p></item>
+ <prgn>xmodmap</prgn> settings.
+ </item>
<item>
- <p>
The Linux console is configured to make
<tt><--</tt> generate DEL, and <tt>Delete</tt>
- generate <tt>ESC [ 3 ~</tt>.</p></item>
+ generate <tt>ESC [ 3 ~</tt>.
+ </item>
<item>
- <p>
X applications are configured so that <tt><</tt>
deletes left, and <tt>Delete</tt> deletes right. Motif
- applications already work like this.</p></item>
+ applications already work like this.
+ </item>
- <item><p>Terminals should have <tt>stty erase ^?</tt> .</p></item>
+ <item>
+ Terminals should have <tt>stty erase ^?</tt> .
+ </item>
<item>
- <p>
The <tt>xterm</tt> terminfo entry should have <tt>ESC
[ 3 ~</tt> for <tt>kdch1</tt>, just as for
- <tt>TERM=linux</tt> and <tt>TERM=vt220</tt>.</p></item>
+ <tt>TERM=linux</tt> and <tt>TERM=vt220</tt>.
+ </item>
<item>
- <p>
Emacs is programmed to map <tt>KB_Backspace</tt> or
the <tt>stty erase</tt> character to
<tt>delete-backward-char</tt>, and <tt>KB_Delete</tt>
or <tt>kdch1</tt> to <tt>delete-forward-char</tt>, and
- <tt>^H</tt> to <tt>help</tt> as always.</p></item>
+ <tt>^H</tt> to <tt>help</tt> as always.
+ </item>
<item>
- <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".
+ </item>
</list>
</p>
<p>
<list>
<item>
- <p>
Some terminals have a <tt><--</tt> key that cannot
be made to produce anything except <tt>^H</tt>. On
these terminals Emacs help will be unavailable on
<tt>^H</tt> (assuming that the <tt>stty erase</tt>
character takes precedence in Emacs, and has been set
correctly). <tt>M-x help</tt> or <tt>F1</tt> (if
- available) can be used instead.</p></item>
+ available) can be used instead.
+ </item>
<item>
- <p>
Some operating systems use <tt>^H</tt> for <tt>stty
erase</tt>. However, modern telnet versions and all
rlogin versions propagate <tt>stty</tt> settings, and
almost all UNIX versions honour <tt>stty erase</tt>.
Where the <tt>stty</tt> settings are not propagated
correctly, things can be made to work by using
- <tt>stty</tt> manually.</p></item>
+ <tt>stty</tt> manually.
+ </item>
<item>
- <p>
Some systems (including previous Debian versions) use
<prgn>xmodmap</prgn> to arrange for both
<tt><--</tt> and <tt>Delete</tt> to generate
using their resources when things are the other way
around. On displays configured like this
<tt>Delete</tt> will not work, but <tt><--</tt>
- will.</p></item>
+ will.
+ </item>
<item>
- <p>
Some operating systems have different <tt>kdch1</tt>
settings in their <tt>terminfo</tt> database for
<tt>xterm</tt> and others. On these systems the
<tt>Delete</tt> key will not work correctly when you
log in from a system conforming to our policy, but
- <tt><--</tt> will.</p></item>
+ <tt><--</tt> will.
+ </item>
</list>
</p>
</sect>
reasonable defaults. (That's because these environment
variables would have to be set in a system-wide
configuration file like <file>/etc/profile</file>, which is not
- supported by all shells.)</p>
+ supported by all shells.)
+ </p>
<p>
If a program usually depends on environment variables for its
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
- if they are not already defined, and calls the original program.</p>
+ "wrapper" shell script which sets the environment variables
+ if they are not already defined, and calls the original program.
+ </p>
<p>
Here is an example of a wrapper script for this purpose:
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>
+ file.
+ </p>
</sect>
+
</chapt>
+
<chapt id="files">
<heading>Files</heading>
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,
<prgn>install</prgn>, or by calling <prgn>strip</prgn> on
the binaries after they have been copied into
<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 <file>a.out</file>
- 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 <file>debian/rules</file> or
- <file>Makefile</file>s.
- </p>
- </footnote>
+ package.
+ </p>
+
+ <p>
+ Although binaries in the build tree should be compiled with
+ debugging information by default, it can often be difficult
+ to debug programs if they are also subjected to compiler
+ optimization. For this reason, it is recommended to support
+ the standardized environment
+ variable <tt>DEB_BUILD_OPTIONS</tt>. This variable can
+ contain several flags to change how a package is compiled
+ and built.
+ </p>
+
+ <p>
+ <taglist>
+ <tag>noopt</tag>
+ <item>
+ The presence of this string means that the package
+ should be 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.
+ </item>
+ <tag>nostrip</tag>
+ <item>
+ This string means that the debugging symbols should
+ not be stripped from the binary during installation,
+ so that debugging information may be included in the package.
+ </item>
+ </taglist>
+ </p>
+
+ <p>
The following makefile snippet is an example of how one may
- 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>
function perfectly well when stripped, since the symbols for
dynamic linking are in a separate part of the ELF object
file.<footnote>
- <p>
You might also want to use the options
<tt>--remove-section=.comment</tt> and
<tt>--remove-section=.note</tt> on both shared libraries
and executables, and <tt>--strip-debug</tt> on static
libraries.
- </p>
</footnote>
</p>
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'',
+ 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
a library (such as library dependency information for static
linking). Also, they're <em>essential</em> for programs
using <tt>libltdl</tt>.<footnote>
- <p>
Although <prgn>libtool</prgn> is fully capable of
linking against shared libraries which don't have
<tt>.la</tt> files, as it is a mere shell script it can
<file>.la</file> files also store information about
inter-library dependencies which cannot necessarily be
derived after the <file>.la</file> file is deleted.
- </p>
</footnote>
</p>
</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:
- <file><var>libraryname</var><var>soversion</var></file>, 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>
- 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
- <file><var>libraryname</var>-dev</file>; 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,
- <file><var>libraryname</var><var>soversion</var></file>. 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>
All command scripts, including the package maintainer
scripts inside the package and used by <prgn>dpkg</prgn>,
should have a <tt>#!</tt> line naming the shell to be used
- to interpret them.</p>
+ to interpret them.
+ </p>
<p>
In the case of Perl scripts this should be
- <tt>#!/usr/bin/perl</tt>.</p>
+ <tt>#!/usr/bin/perl</tt>.
+ </p>
<p>
Shell scripts (<prgn>sh</prgn> and <prgn>bash</prgn>)
should almost certainly start with <tt>set -e</tt> so that
errors are detected. Every script should use
<tt>set -e</tt> or check the exit status of <em>every</em>
- command.</p>
+ command.
+ </p>
<p>
The standard shell interpreter <file>/bin/sh</file> can be a
symbolic link to any POSIX compatible shell, if <tt>echo
-n</tt> does not generate a newline.<footnote>
- <p>
Debian policy specifies POSIX behavior for
<file>/bin/sh</file>, but <tt>echo -n</tt> has widespread
use in the Linux community (in particular including this
required under POSIX, hence this explicit addition.
Also, rumour has it that this shall be mandated under
the LSB anyway.
- </p>
</footnote>
Thus, shell scripts specifying <file>/bin/sh</file> as
interpreter should only use POSIX features. If a script
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 <file>/bin/sh</file> as its
- interpreter. If your script works with <prgn>ash</prgn>,
- it's probably POSIX compliant, but if you are in doubt, use
+ 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>
Harmful</em>, one of the <tt>comp.unix.*</tt> FAQs, which
can be found at <url
id="http://language.perl.com/versus/csh.whynot">.<footnote>
- <p>
It can also be found on
<url id="http://www.cpan.org/doc/FMTEYEWTK/versus/csh.whynot">
or on the ftp site <ftpsite>ftp.cpan.org</ftpsite> as
<ftppath>/pub/perl/CPAN/doc/FMTEYEWTK/versus/csh.whynot</ftppath>.
- </p>
</footnote>
If an upstream package comes with <prgn>csh</prgn> scripts
then you must make sure that they start with
Any scripts which create files in world-writeable
directories (e.g., in <file>/tmp</file>) must use a
mechanism which will fail if a file with the same name
- already exists.</p>
+ already exists.
+ </p>
<p>
The Debian base system provides the <prgn>tempfile</prgn>
and <prgn>mktemp</prgn> utilities for use by scripts for
- this purpose.</p></sect>
+ 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 <file>/</file>.)</p>
+ directory <file>/</file>.)
+ </p>
<p>
In addition, symbolic links should be specified as short as
possible, i.e., link targets like <file>foo/../bar</file> are
- deprecated.</p>
+ deprecated.
+ </p>
<p>
Note that when creating a relative link using
Simply include the string that should appear as the target
of the link (this will be a pathname relative to the
directory in which the link resides) as the first argument
- to <prgn>ln</prgn>.</p>
+ to <prgn>ln</prgn>.
+ </p>
<p>
For example, in your <prgn>Makefile</prgn> or
ln -fs gcc debian/tmp/usr/bin/cc
ln -fs ../sbin/sendmail $(prefix)/bin/runq
ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
- </example></p>
+ </example>
+ </p>
<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 <file>foo.gz</file> is referenced by a
symbolic link, the filename of the link has to end with
- `<file>.gz</file>' too, as in <file>bar.gz</file>.)
+ "<file>.gz</file>" too, as in <file>bar.gz</file>.)
</p>
</sect>
<p>
Packages must not include device files in the package file
- tree.</p>
+ tree.
+ </p>
<p>
If a package needs any special device files that are not
included in the base system, it must call
<prgn>MAKEDEV</prgn> in the <prgn>postinst</prgn> script,
- after asking the user for permission to do so.</p>
+ after notifying the user<footnote>
+ This notification could be done via a (low-priority)
+ debconf message, or an echo (printf) statement.
+ </footnote>.
+ </p>
<p>
Packages must not remove any device files in the
<prgn>postrm</prgn> or any other script. This is left to the
- system administrator.</p>
+ system administrator.
+ </p>
<p>
Debian uses the serial devices
<file>/dev/ttyS*</file>. Programs using the old
<file>/dev/cu*</file> devices should be changed to use
- <file>/dev/ttyS*</file>.</p>
+ <file>/dev/ttyS*</file>.
+ </p>
</sect>
<sect id="config-files">
<heading>Configuration files</heading>
+
<sect1>
<heading>Definitions</heading>
+
<p>
<taglist>
<tag>configuration file</tag>
<item>
- <p>
A file that affects the operation of a program, or
provides site- or host-specific information, or
otherwise customizes the behavior of a program.
modified by the system administrator (if needed or
desired) to conform to local policy or to provide
more useful site-specific behavior.
- </p>
</item>
<tag><tt>conffile</tt></tag>
<item>
- <p>
A file listed in a package's <tt>conffiles</tt>
file, and is treated specially by <prgn>dpkg</prgn>
(see <ref id="configdetails">).
- </p>
</item>
</taglist>
</p>
<sect1>
<heading>Location</heading>
+
<p>
Any configuration files created or used by your package
- must reside in <file>/etc</file>. If there are several you
- should consider creating a subdirectory of <file>/etc</file>
- named after your package.</p>
+ 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 <file>/etc</file>, and it is not feasible to modify
- the package to use the <file>/etc</file>, you should still put
- the files in <file>/etc</file> and create symbolic links to
- those files from the location that the package
- requires.</p>
+ 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>
<heading>Behavior</heading>
+
<p>
Configuration file handling must conform to the following
behavior:
<list compact="compact">
<item>
- <p>
local changes must be preserved during a package
upgrade, and
- </p>
</item>
<item>
- <p>
configuration files must be preserved when the
package is removed, and only deleted when the
package is purged.
- </p>
</item>
</list>
</p>
In order to ensure that local changes are preserved
correctly, no package may contain or make hard links to
conffiles.<footnote>
- <p>
Rationale: There are two problems with hard links.
The first is that some editors break the link while
editing one of the files, so that the two files may
unwittingly become unlinked and different. The second
is that <prgn>dpkg</prgn> might break the hard link
while upgrading <tt>conffile</tt>s.
- </p>
</footnote>
- </p>
+ </p>
+ <p>
The other way to do it is via the maintainer scripts. In
this case, the configuration file must not be listed as a
<tt>conffile</tt> and must not be part of the package
<sect1>
<heading>Sharing configuration files</heading>
+
<p>
Packages which specify the same file as a
<tt>conffile</tt> must be tagged as <em>conflicting</em>
depend on the owning package if they require the
configuration file to operate. If the other package will
use the configuration file if present, but is capable of
- operating without it, no dependency need be declared.</p>
+ operating without it, no dependency need be declared.
+ </p>
<p>
If it is desirable for two or more related packages to
file, then the following should be done:
<enumlist compact="compact">
<item>
- <p>
One of the related packages (the "owning" package)
will manage the configuration file with maintainer
scripts as described in the previous section.
- </p>
</item>
<item>
- <p>
The owning package should also provide a program
that the other packages may use to modify the
configuration file.
- </p>
</item>
<item>
- <p>
The related packages must use the provided program
to make any desired modifications to the
configuration file. They should either depend on
is not. (This is in addition to the fact that the
configuration file may not even be present in the
latter scenario.)
- </p>
</item>
</enumlist>
</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 to behave as closely to the upstream
default behaviour as possible.
file (for more information see <manref name="logrotate"
section="8">):
<example compact="compact">
-/var/log/foo/* {
+/var/log/foo/*.log {
rotate 12
weekly
compress
security policy by changing the permissions on a binary:
they can do this by using <prgn>dpkg-statoverride</prgn>, as
described below.<footnote>
- <p>
Ordinary files installed by <prgn>dpkg</prgn> (as
opposed to <tt>conffile</tt>s and other similar objects)
normally have their permissions reset to the distributed
remember to describe <prgn>dpkg-statoverride</prgn> in
the package documentation; being a relatively new
addition to Debian, it is probably not yet well-known.
- </p>
</footnote>
Another method you should consider is to create a group for
people allowed to use the program(s) and make any setuid
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
If a program needs to specify an <em>architecture specification
string</em> in some place, the following format should be
used: <var>arch</var>-<var>os</var><footnote>
- <p>
The following architectures and operating systems are
currently recognised by <prgn>dpkg-archictecture</prgn>.
The architecture, <tt><var>arch</var></tt>, is one of
<tt>linux</tt>, <tt>gnu</tt>, <tt>freebsd</tt> and
<tt>openbsd</tt>. Use of <tt>gnu</tt> in this string is
reserved for the GNU/Hurd operating system.
- </p>
</footnote>.
</p>
If a package wants to install an example entry into
<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>
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.
It is not required for a package to depend on
<tt>editor</tt> and <tt>pager</tt>, nor is it required for a
package to provide such virtual packages.<footnote>
- <p>
The Debian base system already provides an editor and a
- pager program,
- </p>
+ pager program.
</footnote>
</p>
</sect>
<p>
<enumlist>
<item>
- <p>
Cgi-bin executable files are installed in the
directory
<example compact="compact">
<example compact="compact">
http://localhost/cgi-bin/<var>cgi-bin-name</var>
</example>
- </p>
</item>
- <item><p>Access to HTML documents</p>
+ <item>
+ <p>Access to HTML documents</p>
<p>
HTML documents for a package are stored in
http://localhost/doc/<var>package</var>/<var>filename</var>
</example>
</p>
- <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
</p>
</item>
- <item><p>Web Document Root</p>
+ <item>
+ <p>Web Document Root</p>
<p>
Web Applications should try to avoid storing files in
</p>
</item>
- </enumlist></p></sect>
-
+ </enumlist>
+ </p>
+ </sect>
<sect id="mail-transport-agents">
<heading>Mail transport, delivery and user agents</heading>
should use <tt>fcntl()</tt> first and dot locking after
this, or alternatively implement the two locking methods in
a non blocking way<footnote>
- <p>
If it is not possible to establish both locks, the
system shouldn't wait for the second lock to be
established, but remove the first lock, wait a (random)
time, and start over locking again.
- </p>
</footnote>. Using the functions <tt>maillock</tt> and
<tt>mailunlock</tt> provided by the
<tt>liblockfile*</tt><footnote>
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>.
<taglist>
<tag><file>/etc/news/organization</file></tag>
- <item><p>A string which should appear as the
+ <item>
+ A string which should appear as the
organization header for all messages posted
- by NNTP clients on the machine</p></item>
+ by NNTP clients on the machine
+ </item>
<tag><file>/etc/news/server</file></tag>
- <item><p>Contains the FQDN of the upstream NNTP
+ <item>
+ Contains the FQDN of the upstream NNTP
server, or localhost if the local machine is
- an NNTP server.</p></item>
+ an NNTP server.
+ </item>
</taglist>
Other global files may be added as required for cross-package news
- configuration.</p></sect>
+ configuration.
+ </p>
+ </sect>
<sect>
indirectly, communicates with real input and display
hardware should declare in their control data that they
provide the virtual package <tt>xserver</tt>.<footnote>
- <p>
This implements current practice, and provides an
actual policy for usage of the <tt>xserver</tt>
virtual package which appears in the virtual packages
another subsystem (e.g., GGI) should provide
<tt>xserver</tt>. Things like <tt>Xvfb</tt>,
<tt>Xnest</tt>, and <tt>Xprt</tt> should not.
- </p>
</footnote>
</p>
</sect1>
<p>
To be an <tt>x-terminal-emulator</tt>, a program must:
<list compact="compact">
- <item><p>
+ <item>
Be able to emulate a DEC VT100 terminal, or a
compatible terminal.
- </p></item>
+ </item>
- <item><p>
+ <item>
Support the command-line option <tt>-e
<var>command</var></tt>, which creates a new
terminal window<footnote>
- <p>
"New terminal window" does not necessarily mean
a new top-level X window directly parented by
the window manager; it could, if the terminal
emulator application were so coded, be a new
"view" in a multiple-document interface (MDI).
- </p>
</footnote>
- and runs the specified <var>command</var>.
- </p></item>
+ 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.
+ </item>
- <item><p>
+ <item>
Support the command-line option <tt>-T
<var>title</var></tt>, which creates a new terminal
window with the window title <var>title</var>.
- </p></item>
+ </item>
</list>
</p>
</sect1>
<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>
+ <item>
+ Start with a priority of 20.
+ </item>
<item>
- <p>
If the window manager supports the Debian menu
system, add 20 points if this support is available
in the package's default configuration (i.e., no
have to be edited to activate the feature); if
configuration files must be modified, add only 10
points.
- </p>
</item>
+ <item>
+ 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.
+ </item>
+
<item>
- <p>
If the window manager permits the X session to be
restarted using a <em>different</em> window manager
(without killing the X server) in its default
configuration, add 10 points; otherwise add none.
- </p>
</item>
</list>
</p>
<p>
Packages that provide fonts for the X Window
System<footnote>
- <p>
For the purposes of Debian Policy, a "font for the X
Window System" is one which is accessed via X protocol
requests. Fonts for the Linux console, for PostScript
definition. Any tool which makes such fonts available
to the X Window System, however, must abide by this
font policy.
- </p>
</footnote>
must do a number of things to ensure that they are both
available without modification of the X or font server
themselves.
<enumlist>
<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
provide an enhancement, a Suggests relationship may
be used. Packages must not Depend on font
packages.<footnote>
- <p>
This is because the X server may retrieve fonts
from the local filesystem or over the network
from an X font server; the Debian package system
is empowered to deal only with the local
filesystem.
- </p>
</footnote>
- </p>
</item>
<item>
- <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>
+ <item>
100 dpi fonts must be placed in
<file>/usr/X11R6/lib/X11/fonts/100dpi/</file>.
- </p></item>
+ </item>
- <item><p>
+ <item>
75 dpi fonts must be placed in
<file>/usr/X11R6/lib/X11/fonts/75dpi/</file>.
- </p></item>
+ </item>
- <item><p>
+ <item>
Character-cell fonts, cursor fonts, and other
low-resolution fonts must be placed in
<file>/usr/X11R6/lib/X11/fonts/misc/</file>.
- </p></item>
+ </item>
</list>
- </p>
</item>
- <item><p>
+ <item>
Speedo fonts must be placed in
<file>/usr/X11R6/lib/X11/fonts/Speedo/</file>.
- </p></item>
+ </item>
- <item><p>
+ <item>
Type 1 fonts must be placed in
<file>/usr/X11R6/lib/X11/fonts/Type1/</file>. If font
metric files are available, they must be placed here
as well.
- </p></item>
+ </item>
<item>
- <p>
Subdirectories of <file>/usr/X11R6/lib/X11/fonts/</file>
other than those listed above must be neither
created nor used. (The <file>PEX</file>, <file>CID</file>,
and <file>cyrillic</file> directories are excepted for
historical reasons, but installation of files into
these directories remains discouraged.)
- </p>
</item>
<item>
- <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>
<item>
- <p>
Font packages should not contain both 75dpi and
100dpi versions of a font. If both are available,
they should be provided in separate binary packages
with <tt>-75dpi</tt> or <tt>-100dpi</tt> appended to
the names of the packages containing the
corresponding fonts.
- </p>
</item>
<item>
- <p>
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
its name.
- </p>
</item>
<item>
- <p>
Font packages must not provide the files
<file>fonts.dir</file>, <file>fonts.alias</file>, or
<file>fonts.scale</file> in a font directory:
<list>
- <item><p>
+ <item>
<file>fonts.dir</file> files must not be provided at all.
- </p></item>
+ </item>
<item>
- <p>
<file>fonts.alias</file> and <file>fonts.scale</file>
files, if needed, should be provided in the
directory
<var>extension</var> is either <tt>scale</tt>
or <tt>alias</tt>, whichever corresponds to
the file contents.
- </p>
</item>
</list>
- </p>
</item>
<item>
- <p>
Font packages must declare a dependency on
<tt>xutils (>> 4.0.3)</tt> in their control
data.
- </p>
</item>
<item>
- <p>
Font packages that provide one or more
<file>fonts.scale</file> files as described above must
invoke <prgn>update-fonts-scale</prgn> on each
<prgn>postinst</prgn> (for all arguments) and
<prgn>postrm</prgn> (for all arguments except
<tt>upgrade</tt>) scripts.
- </p>
</item>
<item>
- <p>
Font packages that provide one or more
<file>fonts.alias</file> files as described above must
invoke <prgn>update-fonts-alias</prgn> on each
<prgn>postinst</prgn> (for all arguments) and
<prgn>postrm</prgn> (for all arguments except
<tt>upgrade</tt>) scripts.
- </p>
</item>
<item>
- <p>
Font packages must invoke
<prgn>update-fonts-dir</prgn> on each directory into
which they installed fonts. This invocation must
occur in both the <prgn>postinst</prgn> (for all
arguments) and <prgn>postrm</prgn> (for all
arguments except <tt>upgrade</tt>) scripts.
- </p>
</item>
<item>
- <p>
Font packages must not provide alias names for the
fonts they include which collide with alias names
already in use by fonts already packaged.
- </p>
</item>
<item>
- <p>
Font packages must not provide fonts with the same
XLFD registry name as another font already packaged.
- </p>
</item>
</enumlist>
</p>
<file>/etc/X11/Xresources/</file> directory, which must
registered as a <tt>conffile</tt> or handled as a
configuration file.<footnote>
- <p>
Note that this mechanism is not the same as using
app-defaults; app-defaults are tied to the client
binary on the local filesystem, whereas X resources
are stored in the X server and affect all connecting
clients.
- </p>
</footnote>
<em>Important:</em> packages that install files into the
<file>/etc/X11/Xresources/</file> directory must conflict with
<prgn>imake</prgn> program it provides, in which case the
packages may transition out of the <file>/usr/X11R6/</file>
directory at the maintainer's discretion.<footnote>
- <p>
<prgn>Imake</prgn>-using programs are exempt because,
as long as they are written correctly, the pathnames
they use to locate resources and install themselves
that is required for these programs is a recompile
against the corresponding X Window System library
development packages.
- </p>
</footnote>
+ </p>
+
+ <p>
Programs that use GNU <prgn>autoconf</prgn> and
<prgn>automake</prgn> are usually easily configured at
compile time to use <file>/usr/</file> instead of
to these programs' tight integration with the mechanisms
of the X Window System. Application-level programs should
use the <file>/etc/</file> directory unless otherwise mandated
- by policy. The installation of files into subdirectories
+ by policy.
+ </p>
+
+ <p>
+ The installation of files into subdirectories
of <file>/usr/X11R6/include/X11/</file> and
<file>/usr/X11R6/lib/X11/</file> is permitted but discouraged;
package maintainers should determine if subdirectories of
instead. (The use of symbolic links from the
<file>X11R6</file> directories to other FHS-compliant
locations is encouraged if the program is not easily
- configured to look elsewhere for its files.) Packages
- must not provide or install files into the directories
+ configured to look elsewhere for its files.)
+ </p>
+
+ <p>
+ Packages must not provide or install files into the directories
<file>/usr/bin/X11/</file>, <file>/usr/include/X11/</file> or
<file>/usr/lib/X11/</file>. Files within a package should,
however, make reference to these directories, rather than
<p>
<em>Programs that require the non-DFSG-compliant OSF/Motif or
OpenMotif libraries</em><footnote>
- <p>
OSF/Motif and OpenMotif are collectively referred to as
"Motif" in this policy document.
- </p>
</footnote>
should be compiled against and tested with LessTif (a free
re-implementation of Motif) instead. If the maintainer
statically against Motif and with <tt>-smotif</tt>
appended to the package name, and one linked dynamically
against Motif and with <tt>-dmotif</tt> appended to the
- package name. Both Motif-linked versions are dependent
+ package name.
+ </p>
+ <p>
+ Both Motif-linked versions are dependent
upon non-DFSG-compliant software and thus cannot be
uploaded to the <em>main</em> distribution; if the
software is itself DFSG-compliant it may be uploaded to
</sect1>
</sect>
- <sect>
+ <sect id="perl">
<heading>Perl programs and modules</heading>
+
+ <p>
+ Perl programs and modules should follow the current Perl policy.
+ </p>
+
<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.
+ 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>
- <sect>
+ <sect id="emacs">
<heading>Emacs lisp programs</heading>
<p>
- Please refer to the `Debian Emacs Policy' (documented in
- <file>debian-emacs-policy.gz</file> 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>
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>
<p>
You should install manual pages in <prgn>nroff</prgn> source
- form, in appropriate places under <file>/usr/share/man</file>. You
- should only use sections 1 to 9 (see the FHS for more
- details). You must not install a preformatted `cat
- page'.</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 to the Debian Bug Tracking System, 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
- <file>debian/rules</file> like this:
- <example compact="compact">
-ln -s ../man7/undocumented.7.gz \
- debian/tmp/usr/share/man/man[1-9]/<var>requested_manpage</var>.[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>
+ 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>.
+ </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
then you should not rely on <prgn>man</prgn> finding your
manpage under those names based solely on the information in
the manpage's header.<footnote>
- <p>
Supporting this in <prgn>man</prgn> often requires
unreasonable processing time to find a manual page or to
report that none exists, and moves knowledge into man's
database that would be better left in the filesystem.
This support is therefore deprecated and will cease to
be present in the future.
- </p>
</footnote>
</p>
</sect>
<p>
Info documents should be installed in <file>/usr/share/info</file>.
- They should be compressed with <tt>gzip -9</tt>.</p>
+ They should be compressed with <tt>gzip -9</tt>.
+ </p>
<p>
Your package should call <prgn>install-info</prgn> to update
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
course!</p>
<p>
- Files in <file>/usr/share/doc</file> 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
- <file>/usr/share/<var>package</var>/</file> with symbolic links
- from <file>/usr/share/doc/<var>package</var>/</file>.
+ Packages must not require the existance of any files in
+ <file>/usr/share/doc/</file> in order to function
+ <footnote>
+ The system administrator should be able to
+ delete files in <file>/usr/share/doc/</file> without causing
+ any programs to break.
+ </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 <file>/usr/doc/<var>package</var></file>. To realize a
- smooth migration to
- <file>/usr/share/doc/<var>package</var></file>, each package
- must maintain a symlink <file>/usr/doc/<var>package</var></file>
- that points to the new location of its documentation in
- <file>/usr/share/doc/<var>package</var></file><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><footnote>
- <p>
- The <tt>debhelper</tt> script
- <prgn>dh_installdocs</prgn> does this automatically.
- </p>
- </footnote>:
- <example compact="compact">
-if [ "$1" = "configure" ]; then
- if [ -d /usr/doc -a ! -e /usr/doc/<var>package</var> \
- -a -d /usr/share/doc/<var>package</var> ]; then
- ln -sf ../share/doc/<var>package</var> /usr/doc/<var>package</var>
- 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/<var>package</var> ]; then
- rm -f /usr/doc/<var>package</var>
-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>
+ 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.
+ </footnote>
</p>
</sect>
package, in the directory
<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.
- </p>
</footnote>
</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>
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>
+ 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>
+ 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.)
+ </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>. If an upstream changelog is
- available, it should be accessible as
+ <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
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 in places for
upstream changelogs merely because they are given
different names or are distributed in HTML format.
- </p>
</footnote>
</p>
there is a separate upstream maintainer, but no upstream
changelog, then the Debian changelog should still be called
<file>changelog.Debian.gz</file>.</p>
+
</sect>
</chapt>
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.
+ 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>
<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>
<p>
The utility programs which are provided with <prgn>dpkg</prgn>
<prgn>install-info</prgn>, are not described in detail here -
please see their manpages.
</p>
-
- <p>
- It does <em>not</em> describe the policy requirements imposed
- on Debian packages, such as the permissions on files and
- directories, documentation requirements, upload procedure, and
- so on. You should see the Debian packaging policy manual for
- these details. (Many of them will probably turn out to be
- helpful even if you don't plan to upload your package and make
- it available as part of the distribution.)
- </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
<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
<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
<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:
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
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
<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>.
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
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
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
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.
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
</item>
</taglist>
</p>
-
+
<sect id="pkg-controlfile">
<heading>
The main control information file: <tt>control</tt>
<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'.
+ <tt>control</tt>. It contains all the package"s "vital
+ statistics".
</p>
- <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
more details.
</p>
- <p>
+ <p>
The fields in binary package control files are:
<list compact="compact">
<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>
<p>
<qref id="pkg-f-Installed-Size"><tt>Installed-Size</tt></qref>
</p>
- </item>
+ </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>
Maintainers are encouraged to preserve the modification
times of the upstream source files in a package, as far as
- is reasonably possible.
+ 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 id="pkg-sourcepkg">
<heading>Source packages (from old Packaging Manual) </heading>
- <p>
+ <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>
- <p>
- There was a previous version of the Debian source format,
- which is now being phased out. Instructions for converting an
- old-style package are given in the Debian policy manual.
- </p>
-
<sect id="pkg-sourcetools">
- <heading>Tools for processing source packages</heading>
+ <heading>Tools for processing source packages</heading>
- <p>
+ <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>
+ <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>
+ <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>
+ <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>
+ <p>
To unpack a package it is typically invoked with
<example>
dpkg-source -x <var>.../path/to/filename</var>.dsc
- </example>
+ </example>
</p>
- <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
the current directory.
</p>
- <p>
+ <p>
To create a packed source archive it is typically invoked:
<example>
dpkg-source -b <var>package</var>-<var>version</var>
required.
</p>
- <p>
+ <p>
See also <ref id="pkg-sourcearchives">.</p>
</sect1>
-
-
+
+
<sect1>
<heading>
<prgn>dpkg-buildpackage</prgn> - overall package-building
control script
</heading>
- <p>
+ <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
package upload.
</p>
- <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>
</p>
</sect1>
-
+
<sect1>
<heading>
<prgn>dpkg-gencontrol</prgn> - generates binary package
control files
</heading>
- <p>
+ <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>
+ <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>
+ <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>
+ <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
are available.
</p>
- <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>
+ <p>
Sources which build several binaries will typically need
something like:
<example>
tells it which package's control file should be generated.
</p>
- <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>
+ <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>
+ <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.
+ called on shared libraries as well.
</p>
<p>
They may be specified either in the locations in the
be included in the binary package's control file.
</p>
- <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
takes effect until the next <tt>-d</tt>.)
</p>
- <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
control file.
</p>
- <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
</example>
</p>
- <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>shlib:</tt> prefix (one invocation of
+ 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
binary package control files.
</p>
</sect1>
-
-
+
+
<sect1>
<heading>
<prgn>dpkg-distaddfile</prgn> - adds a file to
<file>debian/files</file>
</heading>
- <p>
+ <p>
Some packages' uploads need to include files other than
the source and binary package files.
</p>
- <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>
+ <p>
It is usually invoked from the <tt>binary</tt> target of
<file>debian/rules</file>:
<example>
<prgn>dpkg-distaddfile</prgn>.
</p>
- <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>
+ <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>
+ <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
been built.
</p>
</sect1>
-
-
+
+
<sect1><heading><prgn>dpkg-parsechangelog</prgn> - produces parsed representation of
a changelog
</heading>
- <p>
+ <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
information in it to standard output.
</p>
</sect1>
-
+
<sect1 id="pkg-dpkgarch"><heading><prgn>dpkg-architecture</prgn> -
- information about the build and host system
+ 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
</p>
</sect1>
</sect>
-
+
<sect id="pkg-sourcetree"><heading>The Debianised source tree
</heading>
- <p>
+ <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
scripts.
</p>
- <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>
+ <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>
+ <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.
targets depend on must also be non-interactive.
</p>
- <p>
- The targets which are required to be present are:
+ <p>
+ The targets which are required to be present are:
<taglist>
<tag><tt>build</tt></tag>
<item>
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-indep</tt> that are provided in the rules
file.
</p>
-
- <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
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
binary package out of each.
</p>
- <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>
+ <p>
The <tt>build</tt> target may need to run
<tt>clean</tt> first - see below.
</p>
- <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
again it will not rebuild the whole program.
</p>
</item>
-
+
<tag><tt>binary</tt>, <tt>binary-arch</tt>,
<tt>binary-indep</tt>
- </tag>
+ </tag>
<item>
<p>
The <tt>binary</tt> target should be all that is
those which are not.
</p>
- <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>
+ <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
directory.
</p>
- <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,
succeed.
</p>
- <p>
+ <p>
<ref id="pkg-binarypkg"> describes how to construct
binary packages.
</p>
- <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
to be non-interactive.
</p>
- <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
already done.
</p>
- <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
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
in the current directory.
</p>
- <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>
+ <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>
+
+ <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
</item>
<item>
<p><tt>DEB_*_GNU_TYPE</tt> (the GNU style architecture
- specification string)</p>
+ specification string)</p>
</item>
<item>
<p><tt>DEB_*_GNU_CPU</tt> (the CPU part of DEB_*_GNU_TYPE)</p>
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
used for that.
</p>
</sect1>
-
-
+
+
<sect1><heading><file>debian/control</file>
</heading>
- <p>
+ <p>
This file contains version-independent details about the
source package and about the binary packages it creates.
</p>
- <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
that the source tree builds.
</p>
- <p>
+ <p>
The syntax and semantics of the fields are described below
in <ref id="pkg-controlfields">.
</p>
- <p>
+ <p>
The general (binary-package-independent) fields are:
<list compact="compact">
<item>
<item>
<p>
<qref id="pkg-f-classification"><tt>Section</tt> and
- <tt>Priority</tt></qref>
+ <tt>Priority</tt></qref>
(classification, mandatory)
</p>
</item>
<p>
<qref id="pkg-f-Standards-Version"><tt>Standards-Version</tt></qref>
</p>
- </item>
+ </item>
</list>
- <p>
+ <p>
The per-binary-package fields are:
<list compact="compact">
<item>
</item>
</list>
- <p>
+ <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
source control file as part of a source archive.
</p>
- <p>
+ <p>
The fields here may contain variable references - their
values will be substituted by
<prgn>dpkg-gencontrol</prgn>, <prgn>dpkg-genchanges</prgn>
<p> <sect2><heading>User-defined fields
</heading>
- <p>
+ <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>
+ <p>
If you wish to add additional unsupported fields to
these output files you should use the mechanism
described here.
</p>
- <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
(<tt>.changes</tt>) files.
</p>
- <p>
+ <p>
For example, if the main source information control file
contains the field
<example>
</example>
</p>
</sect2>
-
+
</sect1>
<sect1 id="pkg-dpkgchangelog"><heading><file>debian/changelog</file>
</heading>
- <p>
+ <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>
+ <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:
+ 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>
+ <p>
<var>package</var> and <var>version</var> are the source
package name and version number.
- </p>
+ </p>
- <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>
+ <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
<tt>urgency</tt>).
</p>
- <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
used here to separate groups of changes, if desired.
</p>
- <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
installed.
</p>
- <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
+ <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>
+ <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>
+ <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>
+ <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:
Changelog format names are non-empty strings of alphanumerics.
</p>
- <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>
the <tt>dpkg</tt> package.
</p>
- <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
changelog.
</p>
- <p>
+ <p>
The fields are:
<list compact="compact">
<item>
<p>
<qref id="pkg-f-Distribution"><tt>Distribution</tt></qref>
(mandatory)
- </p>
+ </p>
</item>
<item>
<p><qref id="pkg-f-Urgency"><tt>Urgency</tt></qref> (mandatory)</p>
</item>
</list>
- <p>
+ <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
date should always be from the most recent version.
</p>
- <p>
+ <p>
For the format of the <tt>Changes</tt> field see <ref
id="pkg-f-Changes">.
</p>
- <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>
+ <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>
+ <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>
+ <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>
+ <p>
When <prgn>dpkg-gencontrol</prgn>,
<prgn>dpkg-genchanges</prgn> and <prgn>dpkg-source</prgn>
generate control files they do variable substitutions on
variables are available.
</p>
- <p>
- The is usually generated and modified dynamically by
- <file>debian/rules</file> targets; in this case it must be
+ <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>
details about source variable substitutions, including the
format of <file>debian/substvars</file>.</p>
</sect1>
-
+
<sect1><heading><file>debian/files</file>
</heading>
- <p>
+ <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>
+ <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>
+ <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
with this file is to delete it in <tt>clean</tt>.
</p>
- <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
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>
+ <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
id="pkg-bincreating">.
</p>
- <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>
+ <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>
+ <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>
+ <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
</item>
</list>
- <p>
+ <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,
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>
+ </tag>
<item>
-
+
<p>
This is a compressed (with <tt>gzip -9</tt>)
<prgn>tar</prgn> file containing the source code from
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>
+ </tag>
<item>
-
+
<p>
This is a unified context diff (<tt>diff -u</tt>)
giving the changes which are required to turn the
or renamed.
</p>
- <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>
+ <p>
The <prgn>dpkg-source</prgn> program will
automatically make the <file>debian/rules</file> file
executable (see below).</p></item>
</taglist>
-
- <p>
+
+ <p>
If there is no original source code - for example, if the
package is specially prepared for Debian or the Debian
maintainer is the same as the upstream maintainer - the
<file><var>package</var>-<var>version</var></file>.
</p>
</sect>
-
+
<sect><heading>Unpacking a Debian source package without
<prgn>dpkg-source</prgn>
</heading>
- <p>
+ <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>
+ <item>
<p>
Untar the tarfile, which will create a <file>.orig</file>
directory.</p>
source code alongside the Debianised version.</p>
</item>
</enumlist>
-
- <p>
+
+ <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>
+ <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>
+ <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
<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>
+ and the creation of the new one.
</footnote>
</p>
</item>
</list>
</p>
- <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>
fields (from old Packaging Manual)
</heading>
- <p>
+ <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>
<prgn>dpkg</prgn>'s internal databases are in a similar
format.
</p>
-
+
<sect><heading>Syntax of control files
</heading>
- <p>
+ <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>
+ <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
colon.
</p>
- <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>
+ <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,
relationships.
</p>
- <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>
+ <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>
+ <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. When writing
- the control files for Debian packages you <em>must</em> read
- the Debian policy manual in conjuction with the details
- below and the list of fields for the particular file.</p>
+ 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>
+ <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>
+ used in new packages.
</footnote>
</p>
- <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
+ sort of case-sensitive<footnote>
+ This is a bug.
+ </footnote>; use lowercase package names unless
the package you're building (or referring to, in other
- fields) is already using uppercase.</p>
+ fields) is already using uppercase.
+ </p>
</sect1>
-
+
<sect1 id="pkg-f-Version"><heading><tt>Version</tt>
</heading>
- <p>
+ <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>
+ <p>
This is the architecture string; it is a single word for
the Debian architecture.
</p>
- <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>
+ <p>
The special value <tt>all</tt> indicates that the package
is architecture-independent.
</p>
- <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
whatever the current build architecture is.
</p>
- <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
entry <tt>source</tt> is also present.
</p>
- <p>
+ <p>
See <ref id="pkg-debianrules"> for information how to get the
- architecture for the build process.
+ architecture for the build process.
</p>
</sect1>
-
+
<sect1 id="pkg-f-Maintainer"><heading><tt>Maintainer</tt>
</heading>
- <p>
+ <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>
+ <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
end, and bringing the email address forward).
</p>
- <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>
+ <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>
+ <p>
This field identifies the source package name.
</p>
- <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>
+ <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
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>
+ <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>
+ <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>
+ <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
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>
+ <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>
+ <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>
+ <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>
been classified.
</p>
- <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,
binary packages.
</p>
- <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
a package in the FTP archive.
</p>
- <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. See the Debian policy manual for the
- priorities in use and the criteria for selecting the
- priority for a Debian package, and look at the Debian FTP
- archive for a list of currently in-use priorities.
+ selects defaults.
</p>
- <p>
- These fields may appear in binary package control files,
+ <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 <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>
+ <p>
This field is a list of binary packages.
</p>
- <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
which of the binary packages.
</p>
- <p>
+ <p>
When it appears in a <file>.changes</file> file it lists the
names of the binary packages actually being uploaded.
</p>
- <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>
+ <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>
+ <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>
+ <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 the part of the field
+ 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>
+ <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>
+ That is, the parts which are not the <tt>.dsc</tt>.
</footnote> The exact forms of the filenames are described
in <ref id="pkg-sourcearchives">.
</p>
- <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
be installed properly.
</p>
- <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
<tt>byhand</tt> the priority should be <tt>-</tt>.
</p>
- <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
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
- <prgn>dpkg</prgn> programmers' and policy manuals and
- associated texts) with which the package complies. This
+ <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>
+ <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>
+ <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
for package names. (See <ref id="pkg-f-Package">).
</p>
- <p>
+ <p>
Current distribution values are:
<taglist>
<tag><em>stable</em></tag>
<item>
- <p>
- This is the current `released' version of Debian
+ <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
(for example: 1.2r1 becomes 1.2r2 then 1.2r3, etc).
</p>
</item>
-
+
<tag><em>unstable</em></tag>
<item>
<p>
tree. Download from this distribution at your own
risk.</p>
</item>
-
+
<tag><em>contrib</em></tag>
<item>
<p>
distributions. Use your best judgement in downloading
from this Distribution.</p>
</item>
-
+
<tag><em>non-free</em></tag>
<item>
<p>
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>
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
+ "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.
<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>
+ <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>,
</example>
</p>
- <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>
+ <p>
Urgency keywords are not case-sensitive.</p>
</sect1>
-
+
<sect1 id="pkg-f-Date"><heading><tt>Date</tt>
</heading>
- <p>
+ <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>
+ <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
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>
+ <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>
+ <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>
+ <p>
Each version's change information should be preceded by a
- `title' line giving at least the version, distribution(s)
+ "title" line giving at least the version, distribution(s)
and urgency, in a human-readable way.
</p>
- <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
+ 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>
+ <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>
+ by spaces.
+ </p>
</sect1>
-
- <sect1 id="pkg-f-Size"><heading><tt>Size</tt> and <tt>MD5sum</tt>
- </heading>
- <p>
+ <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>
+ spaces.
+ </p>
</sect1>
-
- <sect1 id="pkg-f-Status"><heading><tt>Status</tt>
- </heading>
- <p>
+ <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>
+ single word.
+ </p>
</sect1>
-
- <sect1 id="pkg-f-Config-Version"><heading><tt>Config-Version</tt>
- </heading>
- <p>
+ <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>
+ configured.
+ </p>
</sect1>
-
- <sect1 id="pkg-f-Conffiles"><heading><tt>Conffiles</tt>
- </heading>
- <p>
+ <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>
+ appear anywhere in a package!
+ </p>
</sect1>
-
- <sect1><heading>Obsolete fields
- </heading>
- <p>
+ <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>
+ field went through several names.
</item>
-
+
<tag><tt>Recommended</tt></tag>
- <item><p>Old name for <tt>Recommends</tt></p>
- </item>
-
+ <item>Old name for <tt>Recommends</tt>.</item>
+
<tag><tt>Optional</tt></tag>
- <item><p>Old name for <tt>Suggests</tt>.</p>
- </item>
+ <item>Old name for <tt>Suggests</tt>.</item>
+
<tag><tt>Class</tt></tag>
- <item><p>Old name for <tt>Priority</tt>.</p>
- </item>
+ <item>Old name for <tt>Priority</tt>.</item>
+
</taglist>
</p>
</sect1>
</sect>
+
</appendix>
- <appendix id="pkg-conffiles"><heading>Configuration file handling
- (from old Packaging Manual)
- </heading>
+ <appendix id="pkg-conffiles">
+ <heading>Configuration file handling (from old Packaging Manual)</heading>
- <p>
+ <p>
<prgn>dpkg</prgn> can do a certain amount of automatic
handling of package configuration files.
</p>
- <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>
+ <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
is only released infrequently, this is a good approach.
</p>
- <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
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>
+ <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
package.
</p>
- <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>
+ <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
version.
</p>
- <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.,
and must resolve the differences themselves.
</p>
- <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>
+ <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>
+ <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
kept that way if the user did it.
</p>
- <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>
+ <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>
+ <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>
+ <p>
When using this method there are a couple of important
issues which should be considered:
</p>
- <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
deal with them correctly.
</p>
- <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
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>
+ <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>
+ <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
refer to something, at least by default.
</p>
- <p>
+ <p>
If all the packages involved cooperate, this can be done with
<prgn>update-alternatives</prgn>.
</p>
- <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>
+ <p>
See the manpage <manref name="update-alternatives"
section="8"> for details.
</p>
- <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>
+ <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>
+ <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>
+ <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>
+ <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>
+ <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" -o upgrade = "$1" ]; then
+ if [ install = "$1" ]; then
dpkg-divert --package smailwrapper --add --rename \
--divert /usr/sbin/smail.real /usr/sbin/smail
fi
get installed as the true version.
</p>
- <p>
+ <p>
The postrm has to do the reverse:
<example>
if [ remove = "$1" ]; then
</example>
</p>
- <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
</book>
</debiandoc>
+<!-- vim:set ai et sts=2 sw=2 tw=76: -->
projects / debian / debian-policy.git / blobdiff