<!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.
+ 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, 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
the behavior of the packaging system. Instead, this manual
attempts to define the interface to the package management
system that the developers have to be conversant with.<footnote>
- <p>
Informally, the criteria used for inclusion is that the
material meet one of the following requirements:
<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;
selected conventions often become parts of standard
interfaces.
- </p>
</footnote>
</p>
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><url name="debian-policy"
+ id="http://packages.debian.org/debian-policy"></package>
+ (<httpsite>packages.debian.org</httpsite>
+ <httppath>/debian-policy</httppath>).
+ </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>.
+ (
+ <httpsite>www.debian.org</httpsite>
+ <httppath>/doc/debian-policy/</httppath>)
+ Also available from the same directory are several other
+ formats: <file>policy.html.tar.gz</file>
+ (<httppath>/doc/debian-policy/policy.html.tar.gz</httppath>),
+ <file>policy.pdf.gz</file>
+ (<httppath>/doc/debian-policy/policy.pdf.gz</httppath>)
+ and <file>policy.ps.gz</file>
+ (<httppath>/doc/debian-policy/policy.ps.gz</httppath>).
</p>
<p>
- The <tt>debian-policy</tt> package also includes the file
- <file>upgrading-checklist.txt</file> which indicates policy
+ The <package>debian-policy</package> package also includes the file
+ <file>upgrading-checklist.txt.gz</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 in 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
- them (currently well over 6000), they are split into
+ them (currently well over 15000), they are split into
<em>sections</em> and given <em>priorities</em> to simplify
the handling of them.
</p>
+
<p>
The effort of the Debian project is to build a free operating
system, but not every package we want to make accessible is
<em>free</em> in our sense (see the Debian Free Software
Guidelines, below), or may be imported/exported without
- restrictions. Thus, the archive is split into the sections
- <em>main</em>, <em>non-free</em>, <em>contrib</em>,
- <em>non-US/main</em>, <em>non-US/non-free</em>, and
- <em>non-US/contrib</em>. The sections are explained in detail
- below.
+ restrictions. Thus, the archive is split into the distribution
+ areas or categories based on their licenses and other restrictions.
</p>
<p>
- The <em>main</em> and the <em>non-US/main</em> sections
- together form the <em>Debian GNU/Linux distribution</em>.
+ The aims of this are:
+
+ <list compact="compact">
+ <item>to allow us to make as much software available as we can</item>
+ <item>to allow us to encourage everyone to write free software,
+ and</item>
+ <item>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.</item>
+ </list>
</p>
<p>
- Packages in the other sections are not considered to be part
- of the Debian distribution, although we support their use and
- provide infrastructure for them (such as our bug-tracking
- system and mailing lists). This Debian Policy Manual applies
- to these packages as well.</p>
+ The <em>main</em> category forms the
+ <em>Debian GNU/Linux distribution</em>.
+ </p>
- <sect id="pkgcopyright">
- <heading>Package copyright and sections</heading>
- <p>
- The aims of this section are:
+ <p>
+ Packages in the other distribution areas (<tt>contrib</tt>,
+ <tt>non-free</tt>) are not considered to be part of the Debian
+ distribution, although we support their use and provide
+ infrastructure for them (such as our bug-tracking system and
+ mailing lists). This Debian Policy Manual applies to these
+ packages as well.
+ </p>
- <list compact="compact">
- <item>
- <p>to allow us to make as much software available as we
- can,</p>
- </item>
- <item>
- <p>to allow us to encourage everyone to write free
- software, and</p>
- </item>
- <item>
- <p>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>
- </item>
- </list>
- </p>
- <sect1>
- <heading>The Debian Free Software Guidelines</heading>
- <p>
- The Debian Free Software Guidelines (DFSG) form our
- definition of `free software'. These are:
+ <sect id="dfsg">
+ <heading>The Debian Free Software Guidelines</heading>
+ <p>
+ The Debian Free Software Guidelines (DFSG) form our
+ 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>
- </sect1>
- <sect1>
- <heading>The main section</heading>
+ </p>
+ </sect>
+
+ <sect id="sections">
+ <heading>Categories</heading>
+
+ <sect1 id="main">
+ <heading>The main category</heading>
+
<p>
- Every package in <em>main</em> and <em>non-US/main</em>
- must comply with the DFSG (Debian Free Software
- Guidelines).</p>
+ Every package in <em>main</em> must comply with the DFSG
+ (Debian Free Software 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>
- <heading>The contrib section</heading>
+
+ <sect1 id="contrib">
+ <heading>The contrib category</heading>
+
<p>
- Every package in <em>contrib</em> and
- <em>non-US/contrib</em> must comply with the DFSG.
+ Every package in <em>contrib</em> must comply with the DFSG.
</p>
<p>
- In addition, the packages in <em>contrib</em> and
- <em>non-US/contrib</em>
+ In addition, the packages in <em>contrib</em>
<list compact="compact">
<item>
- <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>
- Furthermore, packages in <em>contrib</em> must not require
- a package in a <em>non-US</em> section for compilation or
- execution.
- </p>
<p>
Examples of packages which would be included in
- <em>contrib</em> or <em>non-US/contrib</em> are:
+ <em>contrib</em> are:
<list compact="compact">
<item>
- <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>
- <heading>The non-free section</heading>
+
+ <sect1 id="non-free">
+ <heading>The non-free category</heading>
+
<p>
- Packages must be placed in <em>non-free</em> or
- <em>non-US/non-free</em> if they are not compliant with
- the DFSG or are encumbered by patents or other legal
- issues that make their distribution problematic.
+ Packages must be placed in <em>non-free</em> if they are
+ not compliant with the DFSG or are encumbered by patents
+ or other legal issues that make their distribution
+ problematic.
</p>
+
<p>
- In addition, the packages in <em>non-free</em> and
- <em>non-US/non-free</em>
+ In addition, the packages in <em>non-free</em>
<list compact="compact">
<item>
- <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>
- <heading>The non-US sections</heading>
- <p>
- Some programs with cryptographic program code need to be
- stored on the <em>non-US</em> server because of United
- States export restrictions. Such programs must be
- distributed in the appropriate <em>non-US</em> section,
- either <em>non-US/main</em>, <em>non-US/contrib</em> or
- <em>non-US/non-free</em>.
- </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.
- </p>
- </sect1>
- <sect1>
- <heading>Further copyright considerations</heading>
- <p>
- Every package must be accompanied by a verbatim copy of
- its copyright and distribution license in the file
- <file>/usr/share/doc/<var>package</var>/copyright</file>
- (see <ref id="copyrightfile"> for further details).
- </p>
- <p>
- We reserve the right to restrict files from being included
- anywhere in our archives if
- <list compact="compact">
- <item>
- <p>
+ </sect>
+
+ <sect id="pkgcopyright">
+ <heading>Copyright considerations</heading>
+
+ <p>
+ Every package must be accompanied by a verbatim copy of
+ its copyright and distribution license in the file
+ <file>/usr/share/doc/<var>package</var>/copyright</file>
+ (see <ref id="copyrightfile"> for further details).
+ </p>
+
+ <p>
+ We reserve the right to restrict files from being included
+ anywhere in our archives if
+ <list compact="compact">
+ <item>
their use or distribution would break a law,
- </p>
- </item>
- <item>
- <p>
+ </item>
+ <item>
there is an ethical conflict in their distribution or
use,
- </p>
- </item>
- <item>
- <p>
+ </item>
+ <item>
we would have to sign a license for them, or
- </p>
- </item>
- <item>
- <p>
+ </item>
+ <item>
their distribution would conflict with other project
policies.
- </p>
- </item>
- </list>
- </p>
+ </item>
+ </list>
+ </p>
- <p>
- Programs whose authors encourage the user to make
- donations are fine for the main distribution, provided
- that the authors do not claim that not donating is
- immoral, unethical, illegal or something similar; in such
- a case they must go in <em>non-free</em>.</p>
+ <p>
+ Programs whose authors encourage the user to make
+ donations are fine for the main distribution, provided
+ that the authors do not claim that not donating is
+ immoral, unethical, illegal or something similar; in such
+ a case they must go in <em>non-free</em>.
+ </p>
- <p>
- Packages whose copyright permission notices (or patent
- problems) do not even allow redistribution of binaries
- only, and where no special permission has been obtained,
- must not be placed on the Debian FTP site and its mirrors
- at all.</p>
+ <p>
+ Packages whose copyright permission notices (or patent
+ problems) do not even allow redistribution of binaries
+ only, and where no special permission has been obtained,
+ must not be placed on the Debian FTP site and its mirrors
+ at all.
+ </p>
- <p>
- Note that under international copyright law (this applies
- in the United States, too), <em>no</em> distribution or
- modification of a work is allowed without an explicit
- notice saying so. Therefore a program without a copyright
- notice <em>is</em> copyrighted and you may not do anything
- to it without risking being sued! Likewise if a program
- has a copyright notice but no statement saying what is
- permitted then nothing is permitted.</p>
+ <p>
+ Note that under international copyright law (this applies
+ in the United States, too), <em>no</em> distribution or
+ modification of a work is allowed without an explicit
+ notice saying so. Therefore a program without a copyright
+ notice <em>is</em> copyrighted and you may not do anything
+ to it without risking being sued! Likewise if a program
+ has a copyright notice but no statement saying what is
+ permitted then nothing is permitted.
+ </p>
- Many authors are unaware of the problems that restrictive
- copyrights (or lack of copyright notices) can cause for
- the users of their supposedly-free software. It is often
- worthwhile contacting such authors diplomatically to ask
- them to modify their license terms. However, this can be a
- politically difficult thing to do and you should ask for
- advice on the <tt>debian-legal</tt> mailing list first, as
- explained below.
- </p>
+ <p>
+ Many authors are unaware of the problems that restrictive
+ copyrights (or lack of copyright notices) can cause for
+ the users of their supposedly-free software. It is often
+ worthwhile contacting such authors diplomatically to ask
+ them to modify their license terms. However, this can be a
+ politically difficult thing to do and you should ask for
+ advice on the <tt>debian-legal</tt> mailing list first, as
+ explained below.
+ </p>
- <p>
- When in doubt about a copyright, send mail to
- <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'.
- </p>
- </sect1>
- <sect1>
- <heading>Subsections</heading>
+ <p>
+ When in doubt about a copyright, send mail to
+ <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".
+ </p>
+ </sect>
- <p>
- The packages in the sections <em>main</em>,
- <em>contrib</em> and <em>non-free</em> are grouped further
- into <em>subsections</em> to simplify handling.
- </p>
+ <sect id="subsections">
+ <heading>Sections</heading>
- <p>
- The section and subsection for each package should be
- specified in the package's <tt>Section</tt> control
- record. However, the maintainer of the Debian archive
- may override this selection to ensure the consistency of
- the Debian distribution. The <tt>Section</tt> field
- should be of the form:
- <list compact="compact">
- <item>
- <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>
+ <p>
+ The packages in the categories <em>main</em>,
+ <em>contrib</em> and <em>non-free</em> are grouped further
+ into <em>sections</em> to simplify handling.
+ </p>
- <p>
- The Debian archive maintainers provide the authoritative
- list of subsections. At present, they are:
- <em>admin</em>, <em>base</em>, <em>comm</em>,
- <em>contrib</em>, <em>devel</em>, <em>doc</em>,
- <em>editors</em>, <em>electronics</em>, <em>games</em>,
- <em>graphics</em>, <em>hamradio</em>,
- <em>interpreters</em>, <em>libs</em>, <em>mail</em>,
- <em>math</em>, <em>misc</em>, <em>net</em>, <em>news</em>,
- <em>non-US</em>, <em>non-free</em>, <em>oldlibs</em>,
- <em>otherosfs</em>, <em>science</em>, <em>shells</em>,
- <em>sound</em>, <em>tex</em>, <em>text</em>,
- <em>utils</em>, <em>web</em>, <em>x11</em>.
- </p>
- </sect1>
- <sect>
+ <p>
+ The category and section for each package should be
+ specified in the package's <tt>Section</tt> control record
+ (see <ref id="f-Section">). However, the maintainer of the
+ Debian archive may override this selection to ensure the
+ consistency of the Debian distribution. The
+ <tt>Section</tt> field should be of the form:
+ <list compact="compact">
+ <item>
+ <em>section</em> if the package is in the
+ <em>main</em> category,
+ </item>
+ <item>
+ <em>segment/section</em> if the package is in
+ the <em>contrib</em> or <em>non-free</em>
+ distribution areas.
+ </item>
+ </list>
+ </p>
+
+ <p>
+ The Debian archive maintainers provide the authoritative
+ list of sections. At present, they are:
+ <em>admin</em>, <em>comm</em>,
+ <em>devel</em>, <em>doc</em>,
+ <em>editors</em>, <em>electronics</em>, <em>embedded</em>,
+ <em>games</em>, <em>gnome</em>, <em>graphics</em>,
+ <em>hamradio</em>, <em>interpreters</em>, <em>kde</em>,
+ <em>libs</em>, <em>libdevel</em>, <em>mail</em>,
+ <em>math</em>, <em>misc</em>, <em>net</em>, <em>news</em>,
+ <em>oldlibs</em>,
+ <em>otherosfs</em>, <em>perl</em>, <em>python</em>,
+ <em>science</em>, <em>shells</em>,
+ <em>sound</em>, <em>tex</em>, <em>text</em>,
+ <em>utils</em>, <em>web</em>, <em>x11</em>.
+ </p>
+ </sect>
+
+ <sect id="priorities">
<heading>Priorities</heading>
<p>
Each package should have a <em>priority</em> value, which is
- included in the package's <em>control record</em>. This
- information is used by the Debian package management tools
- to separate high-priority packages from less-important
- packages.</p>
+ included in the package's <em>control record</em>
+ (see <ref id="f-Priority">).
+ This information is used by the Debian package management tools to
+ separate high-priority packages from less-important packages.
+ </p>
<p>
- The following <em>priority levels</em> are recognised by the
+ The following <em>priority levels</em> are recognized by the
Debian package management tools.
<taglist>
<tag><tt>required</tt></tag>
<item>
- <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
- you may not even be able to use <prgn>dpkg</prgn> to
- put things back. Systems with only the
- <tt>required</tt> packages are probably unusable, but
- they do have enough functionality to allow the
- sysadmin to boot and install more software.</p>
+ functioning of the system (usually, this means that
+ dpkg functionality depends on these packages).
+ Removing a <tt>required</tt> package may cause your
+ system to become totally broken and you may not even
+ be able to use <prgn>dpkg</prgn> to put things back,
+ so only do so if you know what you are doing. Systems
+ with only the <tt>required</tt> packages are probably
+ unusable, but they do have enough functionality to
+ allow the sysadmin to boot and install more software.
</item>
<tag><tt>important</tt></tag>
<item>
- <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
+ already know what they are or have specialized
requirements.
- </p>
</item>
- </taglist></p>
+ </taglist>
+ </p>
<p>
Packages must not depend on packages with lower priority
</p>
</sect>
+ </chapt>
+
+
+ <chapt id="binary">
+ <heading>Binary packages</heading>
+
+ <p>
+ The Debian GNU/Linux distribution is based on the Debian
+ package management system, called <prgn>dpkg</prgn>. Thus,
+ all packages in the Debian distribution must be provided
+ in the <tt>.deb</tt> file format.
+ </p>
+
<sect>
- <heading>Binary packages</heading>
+ <heading>The package name</heading>
+
+ <p>
+ Every package must have a name that's unique within the Debian
+ archive.
+ </p>
+
+ <p>
+ The package name is included in the control field
+ <tt>Package</tt>, the format of which is described
+ in <ref id="f-Package">.
+ The package name is also included as a part of the file name
+ of the <tt>.deb</tt> file.
+ </p>
+ </sect>
+
+ <sect id="versions">
+ <heading>The version of a package</heading>
<p>
- The Debian GNU/Linux distribution is based on the Debian
- package management system, called <prgn>dpkg</prgn>. Thus,
- all packages in the Debian distribution must be provided
- in the <tt>.deb</tt> file format.</p>
+ Every package has a version number recorded in its
+ <tt>Version</tt> control file field, described in
+ <ref id="f-Version">.
+ </p>
+ <p>
+ The package management system imposes an ordering on version
+ numbers, so that it can tell whether packages are being up- or
+ downgraded and so that package system front end applications
+ can tell whether a package it finds available is newer than
+ the one installed on the system. The version number format
+ has the most significant parts (as far as comparison is
+ concerned) at the beginning.
+ </p>
- <sect1>
- <heading>The package name</heading>
+ <p>
+ If an upstream package has problematic version numbers they
+ should be converted to a sane form for use in the
+ <tt>Version</tt> field.
+ </p>
- <p>
- Every package must have a name that's unique within the Debian
- archive.</p>
+ <sect1>
+ <heading>Version numbers based on dates</heading>
<p>
- Package names must consist 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.
+ In general, Debian packages should use the same version
+ numbers as the upstream sources.
</p>
<p>
- The package name is part of the file name of the
- <tt>.deb</tt> file and is included in the control field
- information.
+ However, in some cases where the upstream version number is
+ 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>
- </sect1>
- <sect1>
- <heading>The maintainer of a package</heading>
- <p>
- Every package must have a Debian maintainer (the
- maintainer may be one person or a group of people
- reachable from a common email address, such as a mailing
- list). The maintainer is responsible for ensuring that
- the package is placed in the appropriate distributions.
+ <p>
+ To prevent having to use epochs for every new upstream
+ version, the date based portion of the version number
+ should be changed to the following format in such cases:
+ "19960501", "19961224". It is up to the maintainer whether
+ they want to bother the upstream maintainer to change
+ the version numbers upstream, too.
</p>
<p>
- The maintainer must be specified in the
- <tt>Maintainer</tt> control field with their correct name
- and a working email address. If one person maintains
- several packages, he/she should try to avoid having
- different forms of their name and email address in
- the <tt>Maintainer</tt> fields of those packages.
+ Note that other version formats based on dates which are
+ parsed correctly by the package management system should
+ <em>not</em> be changed.
</p>
<p>
- If the maintainer of a package quits from the Debian
- project, "Debian QA Group"
- <email>packages@qa.debian.org</email> takes over the
- maintainership of the package until someone else
- 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>
- </footnote>
+ 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>
</sect1>
+ </sect>
- <sect1>
- <heading>The description of a package</heading>
+ <sect>
+ <heading>The maintainer of a package</heading>
+
+ <p>
+ Every package must have a Debian maintainer (the
+ maintainer may be one person or a group of people
+ reachable from a common email address, such as a mailing
+ list). The maintainer is responsible for ensuring that
+ the package is placed in the appropriate distributions.
+ </p>
+
+ <p>
+ The maintainer must be specified in the
+ <tt>Maintainer</tt> control field with their correct name
+ and a working email address. If one person maintains
+ several packages, they should try to avoid having
+ different forms of their name and email address in
+ the <tt>Maintainer</tt> fields of those packages.
+ </p>
+
+ <p>
+ The format of the <tt>Maintainer</tt> control field is
+ described in <ref id="f-Maintainer">.
+ </p>
+
+ <p>
+ If the maintainer of a package quits from the Debian
+ project, "Debian QA Group"
+ <email>packages@qa.debian.org</email> takes over the
+ maintainer-ship of the package until someone else
+ volunteers for that task. These packages are called
+ <em>orphaned packages</em>.<footnote>
+ The detailed procedure for doing this gracefully can
+ be found in the Debian Developer's Reference,
+ see <ref id="related">.
+ </footnote>
+ </p>
+ </sect>
+
+ <sect id="descriptions">
+ <heading>The description of a package</heading>
+
+ <p>
+ Every Debian package must have an extended description
+ stored in the appropriate field of the control record.
+ The technical information about the format of the
+ <tt>Description</tt> field is in <ref id="f-Description">.
+ </p>
+
+ <p>
+ The description should describe the package (the program) to a
+ user (system administrator) who has never met it before so that
+ they have enough information to decide whether they want to
+ install it. This description should not just be copied verbatim
+ from the program's documentation.
+ </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.
+ </p>
+
+ <p>
+ The description should also give information about the
+ significant dependencies and conflicts between this package
+ and others, so that the user knows why these dependencies and
+ conflicts have been declared.
+ </p>
+
+ <p>
+ Instructions for configuring or using the package should
+ not be included (that is what installation scripts,
+ manual pages, info files, etc., are for). Copyright
+ statements and other administrivia should not be included
+ either (that is what the copyright file is for).
+ </p>
+
+ <sect1 id="synopsis"><heading>The single line synopsis</heading>
<p>
- Every Debian package must have an extended description
- stored in the appropriate field of the control record.</p>
+ The single line synopsis should be kept brief - certainly
+ under 80 characters.
+ </p>
<p>
- The description should be written so that it gives the
- system administrator enough information to decide whether
- to install the package. This description should not just
- be copied verbatim from the program's documentation.
- Instructions for configuring or using the package should
- not be included (that is what installation scripts,
- manual pages, info files, etc., are for). Copyright
- statements and other administrivia should not be included
- either (that is what the copyright file is for).
+ Do not include the package name in the synopsis line. The
+ display software knows how to display this already, and you
+ do not need to state it. Remember that in many situations
+ the user may only see the synopsis line - make it as
+ informative as you can.
</p>
- </sect1>
+ </sect1>
- <sect1>
- <heading>Dependencies</heading>
+ <sect1 id="extendeddesc"><heading>The extended description</heading>
<p>
- Every package must specify the dependency information
- about other packages that are required for the first to
- work correctly.</p>
+ Do not try to continue the single line synopsis into the
+ extended description. This will not work correctly when
+ the full description is displayed, and makes no sense
+ where only the summary (the single line synopsis) is
+ available.
+ </p>
<p>
- For example, a dependency entry must be provided for any
- shared libraries required by a dynamically-linked executable
- binary in a package.</p>
+ The extended description should describe what the package
+ does and how it relates to the rest of the system (in terms
+ of, for example, which subsystem it is which part of).
+ </p>
<p>
- Packages are not required to declare any dependencies they
- have on other packages which are marked <tt>Essential</tt>
- (see below), and should not do so unless they depend on a
- particular version of that package.</p>
+ 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>
+ 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.
+ </footnote>
+ </p>
- <p>
- Sometimes, a package requires another package to be installed
- <em>and</em> configured before it can be installed. In this
- case, you must specify a <tt>Pre-Depends</tt> entry for
- the package.</p>
+ </sect1>
- <p>
- You should not specify a <tt>Pre-Depends</tt> entry for a
- package before this has been discussed on the
- <tt>debian-devel</tt> mailing list and a consensus about
- doing that has been reached.</p></sect1>
+ </sect>
+ <sect>
+ <heading>Dependencies</heading>
- <sect1>
- <heading>Virtual packages</heading>
+ <p>
+ Every package must specify the dependency information
+ about other packages that are required for the first to
+ work correctly.
+ </p>
- <p>
- Sometimes, there are several packages which offer
- more-or-less the same functionality. In this case, it's
- useful to define a <em>virtual package</em> whose name
- describes that common functionality. (The virtual
- packages only exist logically, not physically; that's why
- they are called <em>virtual</em>.) The packages with this
- particular function will then <em>provide</em> the virtual
- package. Thus, any other package requiring that function
- can simply depend on the virtual package without having to
- specify all possible packages individually.</p>
+ <p>
+ For example, a dependency entry must be provided for any
+ shared libraries required by a dynamically-linked executable
+ binary in a package.
+ </p>
- <p>
- All packages should use virtual package names where
- appropriate, and arrange to create new ones if necessary.
- 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>
+ <p>
+ Packages are not required to declare any dependencies they
+ have on other packages which are marked <tt>Essential</tt>
+ (see below), and should not do so unless they depend on a
+ particular version of that package.<footnote>
+ <p>
+ Essential is defined as the minimal set of functionality
+ that must be available and usable on the system even
+ when packages are in an unconfigured (but unpacked)
+ state. This is needed to avoid unresolvable dependency
+ loops on upgrade. If packages add unnecessary
+ dependencies on packages in this set, the chances that
+ there <strong>will</strong> be an unresolvable
+ dependency loop caused by forcing these Essential
+ packages to be configured first before they need to be
+ is greatly increased. It also increases the chances
+ that frontends will be unable to
+ <strong>calculate</strong> an upgrade path, even if one
+ exists.
+ </p>
+ <p>
+ Also, it's pretty unlikely that functionality from
+ Essential shall ever be removed (which is one reason why
+ care must be taken before adding to the Essential
+ packages set), but <em>packages</em> have been removed
+ from the Essential set when the functionality moved to a
+ different package. So depending on these packages
+ <em>just in case</em> they stop being essential does way
+ more harm than good.
+ </p>
+ </footnote>
+ </p>
- <p>
- 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>
+ <p>
+ Sometimes, a package requires another package to be installed
+ <em>and</em> configured before it can be installed. In this
+ case, you must specify a <tt>Pre-Depends</tt> entry for
+ the package.
+ </p>
+ <p>
+ You should not specify a <tt>Pre-Depends</tt> entry for a
+ package before this has been discussed on the
+ <tt>debian-devel</tt> mailing list and a consensus about
+ doing that has been reached.
+ </p>
- <sect1>
- <heading>Base packages</heading>
+ <p>
+ The format of the package interrelationship control fields is
+ described in <ref id="relationships">.
+ </p>
+ </sect>
- <p>
- The packages included in the <tt>base</tt> section have a
- special function. They form a minimum subset of the Debian
- GNU/Linux system that is installed before everything else
- on a new system. Thus, only very few packages are allowed
- to go into the <tt>base</tt> section to keep the required
- disk usage very small.</p>
+ <sect id="virtual_pkg">
+ <heading>Virtual packages</heading>
- <p>
- Most of these packages will have the priority value
- <tt>required</tt> or at least <tt>important</tt>, and many
- of them will be tagged <tt>essential</tt> (see below).</p>
+ <p>
+ Sometimes, there are several packages which offer
+ more-or-less the same functionality. In this case, it's
+ useful to define a <em>virtual package</em> whose name
+ describes that common functionality. (The virtual
+ packages only exist logically, not physically; that's why
+ they are called <em>virtual</em>.) The packages with this
+ particular function will then <em>provide</em> the virtual
+ package. Thus, any other package requiring that function
+ can simply depend on the virtual package without having to
+ specify all possible packages individually.
+ </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>
+ <p>
+ All packages should use virtual package names where
+ appropriate, and arrange to create new ones if necessary.
+ 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. (See also <ref id="virtual">)
+ </p>
+ <p>
+ The latest version of the authoritative list of virtual
+ package names can be found in the <tt>debian-policy</tt> package.
+ It is also available from the Debian web mirrors at
+ <tt><url name="/doc/packaging-manuals/virtual-package-names-list.txt"
+ id="http://www.debian.org/doc/packaging-manuals/virtual-package-names-list.txt"></tt>.
+ </p>
- <sect1>
- <heading>Essential packages</heading>
+ <p>
+ The procedure for updating the list is described in the preface
+ to the list.
+ </p>
- <p>
- Some packages are tagged <tt>essential</tt>. (They have
- <tt>Essential: yes</tt> in their package control record.)
- This flag is used for packages that are <em>essential</em>
- for a system.</p>
+ </sect>
- <p>
- Since these packages cannot be easily removed (one has to
- specify an extra <em>force option</em> to
- <prgn>dpkg</prgn> to do so), this flag must not be used
- unless absolutely necessary. A shared library package
- must not be tagged <tt>essential</tt>; dependencies will
- prevent its premature removal, and we need to be able to
- remove it when it has been superseded.
- </p>
+ <sect>
+ <heading>Base system</heading>
- <p>
- Since dpkg will not prevent upgrading of other packages
- while an <tt>essential</tt> package is in an unconfigured
+ <p>
+ The <tt>base system</tt> is a minimum subset of the Debian
+ GNU/Linux system that is installed before everything else
+ on a new system. Only very few packages are allowed to form
+ part of the base system, in order to keep the required disk
+ usage very small.
+ </p>
+
+ <p>
+ The base system consists of all those packages with priority
+ <tt>required</tt> or <tt>important</tt>. Many of them will
+ be tagged <tt>essential</tt> (see below).
+ </p>
+ </sect>
+
+ <sect>
+ <heading>Essential packages</heading>
+
+ <p>
+ Some packages are tagged <tt>essential</tt> for a system
+ using the <tt>Essential</tt> control file field.
+ The format of the <tt>Essential</tt> control field is
+ described in <ref id="f-Essential">.
+ </p>
+
+ <p>
+ Since these packages cannot be easily removed (one has to
+ specify an extra <em>force option</em> to
+ <prgn>dpkg</prgn> to do so), this flag must not be used
+ unless absolutely necessary. A shared library package
+ must not be tagged <tt>essential</tt>; dependencies will
+ prevent its premature removal, and we need to be able to
+ remove it when it has been superseded.
+ </p>
+
+ <p>
+ Since dpkg will not prevent upgrading of other packages
+ while an <tt>essential</tt> package is in an unconfigured
state, all <tt>essential</tt> packages must supply all of
their core functionality even when unconfigured. If the
package cannot satisfy this requirement it must not be
tagged as essential, and any packages depending on this
package must instead have explicit dependency fields as
appropriate.
- </p>
+ </p>
- You must not tag any packages <tt>essential</tt> before
- this has been discussed on the <tt>debian-devel</tt>
- mailing list and a consensus about doing that has been
- reached.
- </p>
- </sect1>
+ <p>
+ You must not tag any packages <tt>essential</tt> before
+ this has been discussed on the <tt>debian-devel</tt>
+ mailing list and a consensus about doing that has been
+ reached.
+ </p>
+ </sect>
- <sect1 id="maintscripts">
- <heading>Maintainer scripts</heading>
+ <sect id="maintscripts">
+ <heading>Maintainer Scripts</heading>
- <p>
- The package installation scripts should avoid producing
- output which it is unnecessary for the user to see and
- should rely on <prgn>dpkg</prgn> to stave off boredom on
- the part of a user installing many packages. This means,
- amongst other things, using the <tt>--quiet</tt> option on
- <prgn>install-info</prgn>.</p>
+ <p>
+ The package installation scripts should avoid producing
+ output which is unnecessary for the user to see and
+ should rely on <prgn>dpkg</prgn> to stave off boredom on
+ the part of a user installing many packages. This means,
+ amongst other things, using the <tt>--quiet</tt> option on
+ <prgn>install-info</prgn>.
+ </p>
- Errors which occur during the execution of an installation
- script must be checked and the installation must not
- continue after an error.
- </p>
+ <p>
+ Errors which occur during the execution of an installation
+ script must be checked and the installation must not
+ continue after an error.
+ </p>
- <p>
- Note that in general <ref id="scripts"> applies to package
- maintainer scripts, too.
- </p>
+ <p>
+ Note that in general <ref id="scripts"> applies to package
+ maintainer scripts, too.
+ </p>
+
+ <p>
+ You should not use <prgn>dpkg-divert</prgn> on a file
+ belonging to another package without consulting the
+ maintainer of that package first.
+ </p>
+
+ <p>
+ All packages which supply an instance of a common command
+ name (or, in general, filename) should generally use
+ <prgn>update-alternatives</prgn>, so that they may be
+ installed together. If <prgn>update-alternatives</prgn>
+ is not used, then each package must use
+ <tt>Conflicts</tt> to ensure that other packages are
+ de-installed. (In this case, it may be appropriate to
+ specify a conflict against earlier versions of something
+ that previously did not use
+ <prgn>update-alternatives</prgn>; this is an exception to
+ the usual rule that versioned conflicts should be
+ avoided.)
+ </p>
+ <sect1 id="maintscriptprompt">
+ <heading>Prompting in maintainer scripts</heading>
<p>
- You should not use <prgn>dpkg-divert</prgn> on a file
- belonging to another package without consulting the
- maintainer of that package first.
+ Package maintainer scripts may prompt the user if
+ necessary. Prompting should be done by communicating
+ through a program, such as <prgn>debconf</prgn>, which
+ conforms to the Debian Configuration management
+ specification, version 2 or higher. Prompting the user by
+ other means, such as by hand<footnote>
+ From the Jargon file: by hand 2. By extension,
+ writing code which does something in an explicit or
+ low-level way for which a presupplied library
+ (<em>debconf, in this instance</em>) routine ought
+ to have been available.
+ </footnote>, is now deprecated.
</p>
<p>
- All packages which supply an instance of a common command
- name (or, in general, filename) should generally use
- <prgn>update-alternatives</prgn>, so that they may be
- installed together. If <prgn>update-alternatives</prgn>
- is not used, then each package must use
- <tt>Conflicts</tt> to ensure that other packages are
- de-installed. (In this case, it may be appropriate to
- specify a conflict against earlier versions of something
- that previously did not use
- <prgn>update-alternatives</prgn>; this is an exception to
- the usual rule that versioned conflicts should be
- avoided.)
+ 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>.
</p>
-
- <sect2>
- <heading>Prompting in maintainer scripts</heading>
- <p>
- Package maintainer scripts may prompt the user if
- necessary. Prompting may be accomplished by hand, or by
- communicating with a program, such as
- <prgn>debconf</prgn>, which conforms to the Debian
- Configuration management specification, version 2 or
- higher. 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>
- <p>
- 4% of Debian packages [see <url
- id="http://kitenet.net/programs/debconf/stats/"
- name="Debconf stats">] currently use
- <package>debconf</package> to prompt the user at
- install time, and this number is growing daily. The
- benefits of using debconf are briefly explained at
- <url
- id="http://kitenet.net/doc/debconf-doc/introduction.html"
- name="Debconf introduction">; they include
- preconfiguration, (mostly) noninteractive
- 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
- nascent second implementation of the Debian
- configuration management system
- (<package>cdebconf</package>), and the stabilization
- of the protocol these things use, the time has
- finally come to reflect the use of these things in
- policy.
-
- </p>
- </footnote>
- </p>
- <p>
- Packages which use the Debian Configuration management
- specification may contain an additional
- <prgn>config</prgn> script and a <tt>templates</tt>
- file in their control archive. The <prgn>config</prgn>
- script might be run before the <prgn>preinst</prgn>
- script, and before the package is unpacked or any of its
- dependencies or pre-dependancies are satisfied.
- Therefore it must work using only the tools present in
- <em>essential</em> packages.<footnote>
- <p>
+ <p>
+ Packages which use the Debian Configuration management
+ specification may contain an additional
+ <prgn>config</prgn> script and a <tt>templates</tt>
+ file in their control archive<footnote>
+ The control.tar.gz inside the .deb.
+ See <manref name="deb" section="5">.
+ </footnote>.
+ The <prgn>config</prgn> script might be run before the
+ <prgn>preinst</prgn> script, and before the package is unpacked
+ or any of its dependencies or pre-dependencies are satisfied.
+ Therefore it must work using only the tools present in
+ <em>essential</em> packages.<footnote>
<package>Debconf</package> or another tool that
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>
-
- <p>
- Packages should try to minimize the amount of prompting
- they need to do, and they should ensure that the user
- will only ever be asked each question once. This means
- that packages should try to use appropriate shared
- configuration files (such as <file>/etc/papersize</file> and
- <file>/etc/news/server</file>), and shared
- <package>debconf</package> variables rather than each
- prompting for their own list of required pieces of
- information.
- </p>
-
- <p>
- It also means that an upgrade should not ask the same
- questions again, unless the user has used <tt>dpkg
- --purge</tt> to remove the package's configuration. The
- answers to configuration questions should be stored in an
- appropriate place in <file>/etc</file> so that the user can
- modify them, and how this has been done should be
- documented.</p>
-
- <p>
- If a package has a vitally important piece of
- information to pass to the user (such as "don't run me
- as I am, you must edit the following configuration files
- first or you risk your system emitting badly-formatted
- messages"), it should display this in the
- <prgn>config</prgn> or <prgn>postinst</prgn> script and
- prompt the user to hit return to acknowledge the
- message. Copyright messages do not count as vitally
- important (they belong in
- <file>/usr/share/doc/<var>package</var>/copyright</file>);
- neither do instructions on how to use a program (these
- should be in on-line documentation, where all the users
- can see them).</p>
-
- <p>
- Any necessary prompting should almost always be confined
- to the <prgn>config</prgn> or <prgn>postinst</prgn>
- script. If it is done in the <prgn>postinst</prgn>, it
- should be protected with a conditional so that
- unnecessary prompting doesn't happen if a package's
- installation fails and the <prgn>postinst</prgn> is
- called with <tt>abort-upgrade</tt>,
- <tt>abort-remove</tt> or <tt>abort-deconfigure</tt>.</p>
- </sect1>
- </sect>
-
- <sect>
- <heading>Source packages</heading>
-
- <sect1 id="standardsversion">
- <heading>Standards conformance</heading>
+ </footnote>
+ </p>
<p>
- In the source package's <tt>Standards-Version</tt> control
- field, you should specify the most recent version number
- of this policy document with which your package complied
- when it was last updated. The current version number is
- &version;.
+ Packages which use the Debian Configuration management
+ specification must allow for translation of their messages
+ by using a gettext-based system such as the one provided by
+ the <package>po-debconf</package> package.
</p>
<p>
- This information may be used to file bug reports
- automatically if your package becomes too much out of
- date.
+ Packages should try to minimize the amount of prompting
+ they need to do, and they should ensure that the user
+ will only ever be asked each question once. This means
+ that packages should try to use appropriate shared
+ configuration files (such as <file>/etc/papersize</file> and
+ <file>/etc/news/server</file>), and shared
+ <package>debconf</package> variables rather than each
+ prompting for their own list of required pieces of
+ information.
</p>
<p>
- The version number has four components: major and minor
- version number and major and minor patch level. When the
- standards change in a way that requires every package to
- change the major number will be changed. Significant
- changes that will require work in many packages will be
- signaled by a change to the minor number. The major patch
- level will be changed for any change to the meaning of the
- standards, however small; the minor patch level will be
- changed when only cosmetic, typographical or other edits
- are made which neither change the meaning of the document
- nor affect the contents of packages.</p>
+ It also means that an upgrade should not ask the same
+ questions again, unless the user has used
+ <tt>dpkg --purge</tt> to remove the package's configuration.
+ The answers to configuration questions should be stored in an
+ appropriate place in <file>/etc</file> so that the user can
+ modify them, and how this has been done should be
+ documented.
+ </p>
<p>
- Thus only the first three components of the policy version
- 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'.
- 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
- components may still be used if someone wishes to do
- so.
- </p>
- </footnote>
+ If a package has a vitally important piece of
+ information to pass to the user (such as "don't run me
+ as I am, you must edit the following configuration files
+ first or you risk your system emitting badly-formatted
+ messages"), it should display this in the
+ <prgn>config</prgn> or <prgn>postinst</prgn> script and
+ prompt the user to hit return to acknowledge the
+ message. Copyright messages do not count as vitally
+ important (they belong in
+ <file>/usr/share/doc/<var>package</var>/copyright</file>);
+ neither do instructions on how to use a program (these
+ should be in on-line documentation, where all the users
+ can see them).
</p>
<p>
- You should regularly, and especially if your package has
- become out of date, check for the newest Policy Manual
- available and update your package, if necessary. When your
- 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>
+ Any necessary prompting should almost always be confined
+ to the <prgn>config</prgn> or <prgn>postinst</prgn>
+ script. If it is done in the <prgn>postinst</prgn>, it
+ should be protected with a conditional so that
+ unnecessary prompting doesn't happen if a package's
+ installation fails and the <prgn>postinst</prgn> is
+ called with <tt>abort-upgrade</tt>,
+ <tt>abort-remove</tt> or <tt>abort-deconfigure</tt>.
</p>
</sect1>
+ </sect>
- <sect1>
- <heading>Package relationships</heading>
+ </chapt>
- <p>
- Source packages should specify which binary packages they
- require to be installed or not to be installed in order to
- build correctly. For example, if building a package
- requires a certain compiler, then the compiler should be
- specified as a build-time dependency.
- </p>
- <p>
- It is not necessary to explicitly specify build-time
- relationships on a minimal set of packages that are always
- needed to compile, link and put in a Debian package a
- standard "Hello World!" program written in C or C++. The
- required packages are called <em>build-essential</em>, and
- an informational list can be found in
- <file>/usr/share/doc/build-essential/list</file> (which is
- contained in the <tt>build-essential</tt>
- package).<footnote>
- <p>Rationale:
- <list compact="compact">
- <item>
- <p>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>
+ <chapt id="source">
+ <heading>Source packages</heading>
+
+ <sect id="standardsversion">
+ <heading>Standards conformance</heading>
+
+ <p>
+ Source packages should specify the most recent version number
+ of this policy document with which your package complied
+ when it was last updated.
+ </p>
+
+ <p>
+ This information may be used to file bug reports
+ automatically if your package becomes too much out of date.
+ </p>
+
+ <p>
+ The version is specified in the <tt>Standards-Version</tt>
+ control field.
+ The format of the <tt>Standards-Version</tt> field is
+ described in <ref id="f-Standards-Version">.
+ </p>
+
+ <p>
+ You should regularly, and especially if your package has
+ become out of date, check for the newest Policy Manual
+ available and update your package, if necessary. When your
+ package complies with the new standards you should update the
+ <tt>Standards-Version</tt> source package field and
+ release it.<footnote>
+ See the file <file>upgrading-checklist</file> for
+ information about policy which has changed between
+ different versions of this document.
+ </footnote>
+ </p>
+
+ </sect>
+
+ <sect id="pkg-relations">
+ <heading>Package relationships</heading>
+
+ <p>
+ Source packages should specify which binary packages they
+ require to be installed or not to be installed in order to
+ build correctly. For example, if building a package
+ requires a certain compiler, then the compiler should be
+ specified as a build-time dependency.
+ </p>
+
+ <p>
+ It is not necessary to explicitly specify build-time
+ relationships on a minimal set of packages that are always
+ needed to compile, link and put in a Debian package a
+ standard "Hello World!" program written in C or C++. The
+ required packages are called <em>build-essential</em>, and
+ an informational list can be found in
+ <file>/usr/share/doc/build-essential/list</file> (which is
+ contained in the <tt>build-essential</tt>
+ package).<footnote>
+ Rationale:
+ <list compact="compact">
+ <item>
+ This allows maintaining the list separately
+ from the policy documents (the list does not
+ need the kind of control that the policy
+ documents do).
</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>
+ </footnote>
+ </p>
- <p>
- When specifying the set of build-time dependencies, one
- should list only those packages explicitly required by the
- 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>
+ <p>
+ When specifying the set of build-time dependencies, one
+ should list only those packages explicitly required by the
+ 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>
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>
-
- <p>
- If build-time dependencies are specified, it must be
- possible to build the package and produce working binaries
- on a system with only essential and build-essential
- packages installed and also those required to satisfy the
- build-time relationships (including any implied
- relationships). In particular, this means that version
- clauses should be used rigorously in build-time
- relationships so that one cannot produce bad or
- inconsistently configured packages when the relationships
- are properly satisfied.
- </p>
-
- <sect1>
- <heading>Changes to the upstream sources</heading>
-
- <p>
- If changes to the source code are made that are not
- specific to the needs of the Debian system, they should be
- sent to the upstream authors in whatever form they prefer
- so as to be included in the upstream version of the
- package.</p>
-
- <p>
- If you need to configure the package differently for
- Debian or for Linux, and the upstream source doesn't
- provide a way to do so, you should add such configuration
- facilities (for example, a new <prgn>autoconf</prgn> test
- or <tt>#define</tt>) and send the patch to the upstream
- authors, with the default set to the way they originally
- had it. You can then easily override the default in your
- <file>debian/rules</file> or wherever is appropriate.</p>
-
- <p>
- You should make sure that the <prgn>configure</prgn> utility
- detects the correct architecture specification string
- (refer to <ref id="arch-spec"> for details).</p>
-
- <p>
- If you need to edit a <prgn>Makefile</prgn> where
- GNU-style <prgn>configure</prgn> scripts are used, you
- should edit the <file>.in</file> files rather than editing the
- <prgn>Makefile</prgn> directly. This allows the user to
- reconfigure the package if necessary. You should
- <em>not</em> configure the package and edit the generated
- <prgn>Makefile</prgn>! This makes it impossible for
- someone else to later reconfigure the package.</p></sect1>
-
+ </footnote>
+ </p>
- <sect1>
- <heading>Documenting your changes</heading>
+ <p>
+ If build-time dependencies are specified, it must be
+ possible to build the package and produce working binaries
+ on a system with only essential and build-essential
+ packages installed and also those required to satisfy the
+ build-time relationships (including any implied
+ relationships). In particular, this means that version
+ clauses should be used rigorously in build-time
+ relationships so that one cannot produce bad or
+ inconsistently configured packages when the relationships
+ are properly satisfied.
+ </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>
+ <ref id="relationships"> explains the technical details.
+ </p>
+ </sect>
- <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>
- </p>
- </sect1>
+ <sect>
+ <heading>Changes to the upstream sources</heading>
+ <p>
+ If changes to the source code are made that are not
+ specific to the needs of the Debian system, they should be
+ sent to the upstream authors in whatever form they prefer
+ so as to be included in the upstream version of the
+ package.
+ </p>
- <sect1>
- <heading>Error trapping in makefiles</heading>
+ <p>
+ If you need to configure the package differently for
+ Debian or for Linux, and the upstream source doesn't
+ provide a way to do so, you should add such configuration
+ facilities (for example, a new <prgn>autoconf</prgn> test
+ or <tt>#define</tt>) and send the patch to the upstream
+ authors, with the default set to the way they originally
+ had it. You can then easily override the default in your
+ <file>debian/rules</file> or wherever is appropriate.
+ </p>
- <p>
- When <prgn>make</prgn> invokes a command in a makefile
- (including your package's upstream makefiles and
- <file>debian/rules</file>), it does so using <prgn>sh</prgn>. This
- means that <prgn>sh</prgn>'s usual bad error handling
- properties apply: if you include a miniature script as one
- of the commands in your makefile you'll find that if you
- don't do anything about it then errors are not detected
- and <prgn>make</prgn> will blithely continue after
- problems.</p>
+ <p>
+ You should make sure that the <prgn>configure</prgn> utility
+ detects the correct architecture specification string
+ (refer to <ref id="arch-spec"> for details).
+ </p>
- Every time you put more than one shell command (this
- includes using a loop) in a makefile command you
- must make sure that errors are trapped. For
- simple compound commands, such as changing directory and
- then running a program, using <tt>&&</tt> rather
- than semicolon as a command separator is sufficient. For
- more complex commands including most loops and
- conditionals you should include a separate <tt>set -e</tt>
- command at the start of every makefile command that's
- actually one of these miniature shell scripts.</p></sect1>
+ <p>
+ If you need to edit a <prgn>Makefile</prgn> where GNU-style
+ <prgn>configure</prgn> scripts are used, you should edit the
+ <file>.in</file> files rather than editing the
+ <prgn>Makefile</prgn> directly. This allows the user to
+ reconfigure the package if necessary. You should
+ <em>not</em> configure the package and edit the generated
+ <prgn>Makefile</prgn>! This makes it impossible for someone
+ else to later reconfigure the package without losing the
+ changes you made.
+ </p>
+ </sect>
- <sect1>
- <heading>Obsolete constructs and libraries</heading>
+ <sect id="dpkgchangelog">
+ <heading>Debian changelog: <file>debian/changelog</file></heading>
+
+ <p>
+ Changes in the Debian version of the package should be
+ briefly explained in the Debian changelog file
+ <file>debian/changelog</file>.<footnote>
+ <p>
+ Mistakes in changelogs are usually best rectified by
+ making a new changelog entry rather than "rewriting
+ history" by editing old changelog entries.
+ </p>
+ </footnote>
+ This includes modifications
+ made in the Debian package compared to the upstream one
+ as well as other changes and updates to the package.
+ <footnote>
+ Although there is nothing stopping an author who is also
+ the Debian maintainer from using this changelog 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.
+ </footnote>
+ </p>
- <p>
- The include file <tt><varargs.h></tt> is
- provided to support end-users compiling very old software;
- the library <tt>libtermcap</tt> is provided to support the
- execution of software which has been linked against it
- (either old programs or those such as Netscape which are
- only available in binary form).</p>
+ <p>
+
+ </p>
- <p>
- Debian packages should be patched to use
- <tt><stdarg.h></tt> and <tt>ncurses</tt>
- instead.
- </p>
- </sect1>
- </sect>
- </chapt>
+ <p>
+ The format of the <file>debian/changelog</file> allows the
+ package building tools to discover which version of the package
+ is being built and find out other release-specific information.
+ </p>
- <chapt id="controlfields"><heading>Control files and their fields</heading>
+ <p>
+ That format is a series of entries like this:
- <p>
- Many of the tools in the package management suite manipulate
- data represented in a common format, known as <em>control
- data</em>. The data is often stored in <em>control
- files</em>. Binary and source packages have control files,
- and the <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
- format.
- </p>
+<example compact="compact">
+<var>package</var> (<var>version</var>) <var>distribution(s)</var>; urgency=<var>urgency</var>
+ <var>
+ [optional blank line(s), stripped]
+ </var>
+ * <var>change details</var>
+ <var>more change details</var>
+ <var>
+ [blank line(s), included in output of dpkg-parsechangelog]
+ </var>
+ * <var>even more change details</var>
+ <var>
+ [optional blank line(s), stripped]
+ </var>
+ -- <var>maintainer name</var> <<var>email address</var>><var>[two spaces]</var> <var>date</var>
+</example>
+ </p>
- <sect id="controlsyntax"><heading>Syntax of control files</heading>
+ <p>
+ <var>package</var> and <var>version</var> are the source
+ package name and version number.
+ </p>
<p>
- A control file consists of one or more paragraphs of fields.
- The paragraphs are separated by blank lines. Some control
- files allow only one paragraph; others allow several, in
- which case each paragraph usually refers to a different
- package. (For example, in source packages, the first
- paragraph refers to the source package, and later paragraphs
- refer to binary packages generated from the source.)
+ <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
+ <file>.changes</file> file. See <ref id="f-Distribution">.
</p>
<p>
- Each paragraph consists of a series of data fields; each
- field consists of the field name, followed by a colon and
- then the data/value associated with that field. It ends at
- the end of the line. Horizontal whitespace (spaces and
- tabs) may occur immediately before or after the value and is
- ignored there; it is conventional to put a single space
- after the colon. For example, a field might be:
- <example compact="compact">
-Package: libc6
- </example>
- the field name is <tt>Package</tt> and the field value
- <tt>libc6</tt>.
+ <var>urgency</var> is the value for the <tt>Urgency</tt>
+ field in the <file>.changes</file> file for the upload
+ (see <ref id="f-Urgency">). It is not possible to specify
+ an urgency containing commas; commas are used to separate
+ <tt><var>keyword</var>=<var>value</var></tt> settings in the
+ <prgn>dpkg</prgn> changelog format (though there is
+ currently only one useful <var>keyword</var>,
+ <tt>urgency</tt>).
</p>
<p>
- 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.
+ The change details may in fact be any series of lines
+ starting with at least two spaces, but conventionally each
+ change starts with an asterisk and a separating space and
+ continuation lines are indented so as to bring them in
+ line with the start of the text above. Blank lines may be
+ used here to separate groups of changes, if desired.
</p>
<p>
- Except where otherwise stated only a single line of data is
- allowed and whitespace is not significant in a field body.
- Whitespace must not appear inside names (of packages,
- architectures, files or anything else) or version numbers,
- or between the characters of multi-character version
- relationships.
+ If this upload resolves bugs recorded in the Bug Tracking
+ System (BTS), they may be automatically closed on the
+ inclusion of this package into the Debian archive by
+ including the string: <tt>closes: Bug#<var>nnnnn</var></tt>
+ in the change details.<footnote>
+ To be precise, the string should match the following
+ Perl regular expression:
+ <example>
+/closes:\s*(?:bug)?\#?\s?\d+(?:,\s*(?:bug)?\#?\s?\d+)*/i
+ </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.
+ </footnote>
+ This information is conveyed via the <tt>Closes</tt> field
+ in the <tt>.changes</tt> file (see <ref id="f-Closes">).
</p>
<p>
- Field names are not case-sensitive, but it is usual to
- capitalize the field names using mixed case as shown below.
+ The maintainer name and email address used in the changelog
+ should be the details of the person uploading <em>this</em>
+ version. They are <em>not</em> necessarily those of the
+ usual package maintainer. The information here will be
+ copied to the <tt>Changed-By</tt> field in the
+ <tt>.changes</tt> file (see <ref id="f-Changed-By">),
+ and then later used to send an acknowledgement when the
+ upload has been installed.
</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.
+ The <var>date</var> should be in RFC822 format<footnote>
+ This is generated by <tt>date -R</tt>.
+ </footnote>; it should include the time zone specified
+ numerically, with the time zone name or abbreviation
+ optionally present as a comment in parentheses.
</p>
- </sect>
+ <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>
- <sect><heading>List of fields</heading>
<p>
- This list here is not supposed to be exhaustive. Most fields
- are dealt with elsewhere in this document.
+ For more information on placement of the changelog files
+ within binary packages, please see <ref id="changelogs">.
</p>
- <sect1 id="f-Package"><heading><tt>Package</tt>
- </heading>
+
+ <sect1><heading>Alternative changelog formats</heading>
<p>
- The name of the binary package. Package names consist of
- the alphanumerics and <tt>+</tt> <tt>-</tt> <tt>.</tt>
- (plus, minus and full stop).
+ In non-experimental packages you must use a format for
+ <file>debian/changelog</file> which is supported by the most
+ recent released version of <prgn>dpkg</prgn>.
</p>
<p>
- 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>
+ It is possible to use a format different from the standard
+ one by providing a changelog parser for the format you wish
+ to use. The parser must have an API compatible with that
+ expected by <prgn>dpkg-genchanges</prgn> and
+ <prgn>dpkg-gencontrol</prgn>, and it must not interact with
+ the user at all.
+ <footnote>
+ If there is general interest in the new format, you should
+ contact the <package>dpkg</package> maintainer to have the
+ parser script for it included in the <prgn>dpkg</prgn>
+ package. (You will need to agree that the parser and its
+ man page may be distributed under the GNU GPL, just as the rest
+ of <prgn>dpkg</prgn> is.)
+ </footnote>
+ </p>
</sect1>
+ </sect>
+ <sect id="dpkgcopyright">
+ <heading>Copyright: <file>debian/copyright</file></heading>
+ <p>
+ Every package must be accompanied by a verbatim copy of
+ its copyright and distribution license in the file
+ <file>/usr/share/doc/<var>package</var>/copyright</file>
+ (see <ref id="copyrightfile"> for further details). Also see
+ <ref id="pkgcopyright"> for further considerations relayed
+ to copyrights for packages.
+ </p>
+ </sect>
+ <sect>
+ <heading>Error trapping in makefiles</heading>
- <sect1 id="f-Version"><heading><tt>Version</tt>
- </heading>
+ <p>
+ When <prgn>make</prgn> invokes a command in a makefile
+ (including your package's upstream makefiles and
+ <file>debian/rules</file>), it does so using <prgn>sh</prgn>. This
+ means that <prgn>sh</prgn>'s usual bad error handling
+ properties apply: if you include a miniature script as one
+ of the commands in your makefile you'll find that if you
+ don't do anything about it then errors are not detected
+ and <prgn>make</prgn> will blithely continue after
+ problems.
+ </p>
- <p>
- This lists the source or binary package's version number -
- see <ref id="versions">.
- </p>
+ <p>
+ Every time you put more than one shell command (this
+ includes using a loop) in a makefile command you
+ must make sure that errors are trapped. For
+ simple compound commands, such as changing directory and
+ then running a program, using <tt>&&</tt> rather
+ than semicolon as a command separator is sufficient. For
+ more complex commands including most loops and
+ conditionals you should include a separate <tt>set -e</tt>
+ command at the start of every makefile command that's
+ actually one of these miniature shell scripts.
+ </p>
+ </sect>
- </sect1>
+ <sect id="timestamps">
+ <heading>Time Stamps</heading>
+ <p>
+ Maintainers should preserve the modification times of the
+ upstream source files in a package, as far as is reasonably
+ possible.<footnote>
+ 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.
+ </footnote>
+ </p>
+ </sect>
- <sect1
- id="f-Standards-Version"><heading><tt>Standards-Version</tt>
- </heading>
+ <sect id="restrictions">
+ <heading>Restrictions on objects in source packages</heading>
- <p>
- The most recent version of the standards (the policy
- manual 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.
- Its format is described above; see
- <ref id="standardsversion">.
- </p>
- </sect1>
+ <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>
+ <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>
+ Setgid directories are allowed.
+ </footnote>
+ </p>
+ </sect>
+ <sect id="debianrules">
+ <heading>Main building script: <file>debian/rules</file></heading>
- <sect1 id="f-Distribution"><heading><tt>Distribution</tt>
- </heading>
-
- <p>
- In a <file>.changes</file> file or parsed changelog output
- this contains the (space-separated) name(s) of the
- distribution(s) where this version of the package should
- be installed. Valid distributions are determined by the
- archive maintainers.<footnote>
- Current distribution names are:
- <taglist compact="compact">
- <tag><em>stable</em></tag>
- <item>
- <p>
- 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
- unstable distribution after a short time lag to
- ensure that there are no major issues with the
- unstable packages. It is less prone to breakage
- 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
- 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
- developmental packages from various sources that
- the maintainers want people to try, but are not
- ready to be a part of the other parts of the
- Debian distribution tree. Download at your own
- risk.
- </p>
- </item>
- </taglist>
-
- You should list <em>all</em> distributions that the
- package should be installed into.
- </footnote>
- </p>
- </sect1>
-
-
- </sect>
- </chapt>
-
- <chapt id="versions"><heading>Version numbering</heading>
-
- <p>
- Every package has a version number recorded in its
- <tt>Version</tt> control file field.
- </p>
-
- <p>
- The package management system imposes an ordering on version
- numbers, so that it can tell whether packages are being up- or
- downgraded and so that package system front end applications
- can tell whether a package it finds available is newer than
- the one installed on the system. The version number format
- has the most significant parts (as far as comparison is
- concerned) at the beginning.
- </p>
-
- <p>
- The version number format is:
- [<var>epoch</var><tt>:</tt>]<var>upstream_version</var>[<tt>-</tt><var>debian_revision</var>]
- </p>
-
- <p>
- The three components here are:
- <taglist>
- <tag><var>epoch</var></tag>
- <item>
- <p>
- This is a single (generally small) unsigned integer. It
- may be omitted, in which case zero is assumed. If it is
- omitted then the <var>upstream_version</var> may not
- contain any colons.
- </p>
-
- <p>
- It is provided to allow mistakes in the version numbers
- of older versions of a package, and also a package's
- previous version numbering schemes, to be left behind.
- </p>
- </item>
-
- <tag><var>upstream_version</var></tag>
- <item>
- <p>
- This is the main part of the version number. It is
- usually the version number of the original (`upstream')
- package from which the <file>.deb</file> file has been made,
- if this is applicable. Usually this will be in the same
- format as that specified by the upstream author(s);
- however, it may need to be reformatted to fit into the
- package management system's format and comparison
- scheme.
- </p>
-
- <p>
- The comparison behavior of the package management system
- with respect to the <var>upstream_version</var> is
- described below. The <var>upstream_version</var>
- portion of the version number is mandatory.
- </p>
-
- <p>
- The <var>upstream_version</var> may contain only
- alphanumerics<footnote>
- <p>Alphanumerics are <tt>A-Za-z0-9</tt> only.</p>
- </footnote>
- and the characters <tt>.</tt> <tt>+</tt> <tt>-</tt>
- <tt>:</tt> (full stop, plus, hyphen, colon) and should
- start with a digit. If there is no
- <var>debian_revision</var> then hyphens are not allowed;
- if there is no <var>epoch</var> then colons are not
- allowed.</p>
- </item>
-
- <tag><var>debian_revision</var></tag>
- <item>
- <p>
- This part of the version number specifies the version of
- the Debian package based on the upstream version. It
- may contain only alphanumerics and the characters
- <tt>+</tt> and <tt>.</tt> (plus and full stop) and is
- compared in the same way as the
- <var>upstream_version</var> is.
- </p>
-
- <p>
- It is optional; if it isn't present then the
- <var>upstream_version</var> may not contain a hyphen.
- This format represents the case where a piece of
- software was written specifically to be turned into a
- Debian package, and so there is only one `debianization'
- of it and therefore no revision indication is required.
- </p>
-
- <p>
- It is conventional to restart the
- <var>debian_revision</var> at <tt>1</tt> each time the
- <var>upstream_version</var> is increased.
- </p>
-
- <p>
- The package management system will break the version
- number apart at the last hyphen in the string (if there
- is one) to determine the <var>upstream_version</var> and
- <var>debian_revision</var>. The absence of a
- <var>debian_revision</var> compares earlier than the
- presence of one (but note that the
- <var>debian_revision</var> is the least significant part
- of the version number).
- </p>
- </item>
- </taglist>
- </p>
-
- <p>
- The <var>upstream_version</var> and <var>debian_revision</var>
- parts are compared by the package management system using the
- same algorithm:
- </p>
-
- <p>
- The strings are compared from left to right.
- </p>
-
- <p>
- First the initial part of each string consisting entirely of
- non-digit characters is determined. These two parts (one of
- which may be empty) are compared lexically. If a difference
- is found it is returned. The lexical comparison is a
- comparison of ASCII values modified so that all the letters
- sort earlier than all the non-letters.
- </p>
-
- <p>
- Then the initial part of the remainder of each string which
- consists entirely of digit characters is determined. The
- numerical values of these two parts are compared, and any
- difference found is returned as the result of the comparison.
- For these purposes an empty string (which can only occur at
- the end of one or both version strings being compared) counts
- as zero.
- </p>
-
- <p>
- These two steps (comparing and removing initial non-digit
- strings and initial digit strings) are repeated until a
- difference is found or both strings are exhausted.
- </p>
-
- <p>
- Note that the purpose of epochs is to allow us to leave behind
- mistakes in version numbering, and to cope with situations
- where the version numbering scheme changes. It is
- <em>not</em> intended to cope with version numbers containing
- strings of letters which the package management system cannot
- interpret (such as <tt>ALPHA</tt> or <tt>pre-</tt>), or with
- silly orderings (the author of this manual has heard of a
- package whose versions went <tt>1.1</tt>, <tt>1.2</tt>,
- <tt>1.3</tt>, <tt>1</tt>, <tt>2.1</tt>, <tt>2.2</tt>,
- <tt>2</tt> and so forth).
- </p>
-
- <p>
- If an upstream package has problematic version numbers they
- should be converted to a sane form for use in the
- <tt>Version</tt> field.
- </p>
-
- <sect>
- <heading>Version numbers based on dates</heading>
- <p>
- In general, Debian packages should use the same version
- numbers as the upstream sources.</p>
-
- <p>
- However, in some cases where the upstream version number is
- 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>
-
- <p>
- To prevent having to use epochs for every new upstream
- version, the version number should be changed to the
- following format in such cases: `19960501', `19961224'. It
- is up to the maintainer whether he/she wants to bother the
- upstream maintainer to change the version numbers upstream,
- too.</p>
-
- <p>
- Note that other version formats based on dates which are
- parsed correctly by the package management system should
- <em>not</em> be changed.</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>
- </sect>
- </chapt>
-
- <chapt id="miscellaneous"><heading>Packaging Considerations</heading>
-
- <sect id="timestamps"><heading>Time Stamps</heading>
- <p>
- 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>
-
- <sect id="debianrules"><heading><file>debian/rules</file> - the
- main building script</heading>
-
- <p>
- This file must be an executable makefile, and contains the
- package-specific recipes for compiling the package and
- building binary package(s) from the source.
- </p>
+ <p>
+ This file must be an executable makefile, and contains the
+ package-specific recipes for compiling the package and
+ building binary package(s) from the source.
+ </p>
<p>
It must start with the line <tt>#!/usr/bin/make -f</tt>,
</p>
<p>
- The required and optional targets are as follows:
+ The targets are as follows (required unless stated otherwise):
<taglist>
- <tag><tt>build</tt>, <tt>build-arch</tt> (optional),
- <tt>build-indep</tt> (optional)</tag>
+ <tag><tt>build</tt></tag>
<item>
<p>
- The <tt>build</tt> target should perform all
- non-interactive configuration and compilation of the
- package. If a package has an interactive pre-build
+ The <tt>build</tt> target should perform all the
+ configuration and compilation of the package.
+ If a package has an interactive pre-build
configuration routine, the Debianized source package
must either be built after this has taken place (so
that the binary package can be built without rerunning
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>
+ <tag><tt>build-arch</tt> (optional),
+ <tt>build-indep</tt> (optional)
+ </tag>
+ <item>
+ <p>
+ A package may also provide both of the targets
+ <tt>build-arch</tt> and <tt>build-indep</tt>.
+ The <tt>build-arch</tt> target, if provided, should
+ perform all the configuration and compilation required
+ for producing all architecture-dependant binary packages
+ (those packages for which the body of the
+ <tt>Architecture</tt> field in <tt>debian/control</tt>
+ is not <tt>all</tt>).
+ Similarly, the <tt>build-indep</tt> target, if
+ provided, should perform all the configuration and
+ compilation required for producing all
+ architecture-independent binary packages
+ (those packages for which the body of the
+ <tt>Architecture</tt> field in <tt>debian/control</tt>
+ is <tt>all</tt>).
+ The <tt>build</tt> target should depend on those of the
+ targets <tt>build-arch</tt> and <tt>build-indep</tt> that
+ are provided in the rules file.
+ </p>
+
+ <p>
+ If one or both of the targets <tt>build-arch</tt> and
+ <tt>build-indep</tt> are not provided, then invoking
+ <file>debian/rules</file> with one of the not-provided
+ targets as arguments should produce a exit status code
+ of 2. Usually this is provided automatically by make
+ if the target is missing.
+ </p>
+
+ <p>
+ The <tt>build-arch</tt> and <tt>build-indep</tt> targets
+ must not do anything that might require root privilege.
+ </p>
+ </item>
+
<tag><tt>binary</tt>, <tt>binary-arch</tt>,
<tt>binary-indep</tt>
</tag>
<p>
The <tt>binary</tt> target must be all that is
necessary for the user to build the binary package(s)
- produced from this source package. All of these
- targets are required to be non-interactive. It is
+ produced from this source package. It is
split into two parts: <prgn>binary-arch</prgn> builds
the binary packages which are specific to a particular
architecture, and <tt>binary-indep</tt> builds
<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>
and <tt>binary</tt> targets may have had, except
that it should leave alone any output files created in
the parent directory by a run of a <tt>binary</tt>
- target. This target must be non-interactive.
+ target.
</p>
<p>
possible is a good idea.
</p>
</item>
+
+ <tag><tt>patch</tt> (optional)</tag>
+ <item>
+ <p>
+ This target performs whatever additional actions are
+ required to make the source ready for editing (unpacking
+ additional upstream archives, applying patches, etc.).
+ It is recommended to be implemented for any package where
+ <tt>dpkg-source -x</tt> does not result in source ready
+ for additional modification. See
+ <ref id="readmesource">.
+ </p>
+ </item>
</taglist>
<p>
<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-dpkg-architecture"><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
or system information; the GNU style variables should be
used for that.
</p>
+
+ <sect1 id="debianrules-options">
+ <heading><file>debian/rules</file> and
+ <tt>DEB_BUILD_OPTIONS</tt></heading>
+
+ <p>
+ Supporting the standardized environment variable
+ <tt>DEB_BUILD_OPTIONS</tt> is recommended. This variable can
+ contain several flags to change how a package is compiled and
+ built. Each flag must be in the form <var>flag</var> or
+ <var>flag</var>=<var>options</var>. If multiple flags are
+ given, they must be separated by whitespace.<footnote>
+ Some packages support any delimiter, but whitespace is the
+ easiest to parse inside a makefile and avoids ambiguity with
+ flag values that contain commas.
+ </footnote>
+ <var>flag</var> must start with a lowercase letter
+ (<tt>a-z</tt>) and consist only of lowercase letters,
+ numbers (<tt>0-9</tt>), and the characters
+ <tt>-</tt> and <tt>_</tt> (hyphen and underscore).
+ <var>options</var> must not contain whitespace. The same
+ tag should not be given multiple times with conflicting
+ values. Package maintainers may assume that
+ <tt>DEB_BUILD_OPTIONS</tt> will not contain conflicting tags.
+ </p>
+
+ <p>
+ The meaning of the following tags has been standardized:
+ <taglist>
+ <tag>noopt</tag>
+ <item>
+ The presence of this tag means that the package should
+ be compiled with a minimum of optimization. For C
+ programs, it is best to add <tt>-O0</tt> to
+ <tt>CFLAGS</tt> (although this is usually the default).
+ Some programs might fail to build or run at this level
+ of optimization; it may be necessary to use
+ <tt>-O1</tt>, for example.
+ </item>
+ <tag>nostrip</tag>
+ <item>
+ This tag means that the debugging symbols should not be
+ stripped from the binary during installation, so that
+ debugging information may be included in the package.
+ </item>
+ <tag>parallel=n</tag>
+ <item>
+ This tag means that the package should be built using up
+ to <tt>n</tt> parallel processes if the package build
+ system supports this.<footnote>
+ Packages built with <tt>make</tt> can often implement
+ this by passing the <tt>-j</tt><var>n</var> option to
+ <tt>make</tt>.
+ </footnote>
+ If the package build system does not support parallel
+ builds, this string must be ignored. If the package
+ build system only supports a lower level of concurrency
+ than <var>n</var>, the package should be built using as
+ many parallel processes as the package build system
+ supports. It is up to the package maintainer to decide
+ whether the package build times are long enough and the
+ package build system is robust enough to make supporting
+ parallel builds worthwhile.
+ </item>
+ </taglist>
+ </p>
+
+ <p>
+ Unknown flags must be ignored by <file>debian/rules</file>.
+ </p>
+
+ <p>
+ The following makefile snippet is an example of how one may
+ implement the build options; you will probably have to
+ massage this example in order to make it work for your
+ package.
+ <example compact="compact">
+CFLAGS = -Wall -g
+INSTALL = install
+INSTALL_FILE = $(INSTALL) -p -o root -g root -m 644
+INSTALL_PROGRAM = $(INSTALL) -p -o root -g root -m 755
+INSTALL_SCRIPT = $(INSTALL) -p -o root -g root -m 755
+INSTALL_DIR = $(INSTALL) -p -d -o root -g root -m 755
+
+ifneq (,$(filter noopt,$(DEB_BUILD_OPTIONS)))
+ CFLAGS += -O0
+else
+ CFLAGS += -O2
+endif
+ifeq (,$(filter nostrip,$(DEB_BUILD_OPTIONS)))
+ INSTALL_PROGRAM += -s
+endif
+ifneq (,$(filter parallel=%,$(DEB_BUILD_OPTIONS)))
+ NUMJOBS = $(patsubst parallel=%,%,$(filter parallel=%,$(DEB_BUILD_OPTIONS)))
+ MAKEFLAGS += -j$(NUMJOBS)
+endif
+ </example>
+ </p>
+ </sect1>
</sect>
- <sect id="dpkgchangelog"><heading><file>debian/changelog</file>
- </heading>
+<!-- FIXME: section pkg-srcsubstvars is the same as substvars -->
+ <sect id="substvars">
+ <heading>Variable substitutions: <file>debian/substvars</file></heading>
<p>
- This file records the changes to the Debian-specific parts of the
- package<footnote>
- <p>
- Though there is nothing stopping an author who is also
- the Debian maintainer from using it for all their
- changes, it will have to be renamed if the Debian and
- upstream maintainers become different people. In such a
- case, however, it might be better to maintain the
- package as a non-native package.
- </p>
- </footnote>.
+ When <prgn>dpkg-gencontrol</prgn>,
+ <prgn>dpkg-genchanges</prgn> and <prgn>dpkg-source</prgn>
+ generate control files they perform variable substitutions
+ on their output just before writing it. Variable
+ substitutions have the form <tt>${<var>variable</var>}</tt>.
+ The optional file <file>debian/substvars</file> contains
+ variable substitutions to be used; variables can also be set
+ directly from <file>debian/rules</file> using the <tt>-V</tt>
+ option to the source packaging commands, and certain
+ predefined variables are also available.
</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.
+ The <file>debian/substvars</file> file is usually generated and
+ modified dynamically by <file>debian/rules</file> targets, in
+ which case it must be removed by the <tt>clean</tt> target.
</p>
<p>
- That format is a series of entries like this:
- <example compact="compact">
-<var>package</var> (<var>version</var>) <var>distribution(s)</var>; urgency=<var>urgency</var>
- <comment>
- <p>[optional blank line(s), stripped]</p>
- </comment>
- * <var>change details</var>
- <var>more change details</var>
- <comment>
- <p>[blank line(s), included in output of dpkg-parsechangelog]</p>
- </comment>
- * <var>even more change details</var>
- <comment>
- <p>[optional blank line(s), stripped]</p>
- </comment>
- -- <var>maintainer name</var> <<var>email
- address</var>><var>[two spaces]</var> <var>date</var>
- </example>
- </p>
+ See <manref name="dpkg-source" section="1"> for full
+ details about source variable substitutions, including the
+ format of <file>debian/substvars</file>.</p>
+ </sect>
+
+ <sect id="debianwatch">
+ <heading>Optional upstream source location: <file>debian/watch</file></heading>
+
+ <p>
+ This is an optional, recommended control file for the
+ <tt>uscan</tt> utility which defines how to automatically
+ scan ftp or http sites for newly available updates of the
+ package. This is used by <url id="
+ http://dehs.alioth.debian.org/"> and other Debian QA tools
+ to help with quality control and maintenance of the
+ distribution as a whole.
+ </p>
+
+ </sect>
+
+ <sect id="debianfiles">
+ <heading>Generated files list: <file>debian/files</file></heading>
<p>
- <var>package</var> and <var>version</var> are the source
- package name and version number.
- </p>
-
- <p>
- <var>distribution(s)</var> lists the distributions where
- this version should be installed when it is uploaded - it
- is copied to the <tt>Distribution</tt> field in the
- <file>.changes</file> file. See <ref id="f-Distribution">.
- </p>
-
- <p>
- <var>urgency</var> is the value for the <tt>Urgency</tt>
- field in the <file>.changes</file> file for the upload. It is
- not possible to specify an urgency containing commas; commas
- are used to separate
- <tt><var>keyword</var>=<var>value</var></tt> settings in the
- <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>
-
- <p>
- The change details may in fact be any series of lines
- starting with at least two spaces, but conventionally each
- change starts with an asterisk and a separating space and
- continuation lines are indented so as to bring them in
- line with the start of the text above. Blank lines may be
- used here to separate groups of changes, if desired.
- </p>
-
- <p>
- If this upload resolves bugs recorded in the Bug Tracking
- System (BTS), they may be automatically closed on the
- 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>
-/closes:\s*(?:bug)?\#?\s?\d+(?:,\s*(?:bug)?\#?\s?\d+)*/i
- </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 maintainer name and email address used in the changelog
- should be the details of the person uploading <em>this</em>
- version. They are <em>not</em> necessarily those of the
- usual package maintainer. The information here will be
- copied to the <tt>Changed-By</tt> field in the
- <tt>.changes</tt> file, and then later used to send an
- acknowledgement when the upload has been installed.
- </p>
-
- <p>
- The <var>date</var> should be in RFC822 format<footnote>
- <p>
- This is generated by the <prgn>822-date</prgn>
- program.
- </p>
- </footnote>; it should include the time zone specified
- numerically, with the time zone name or abbreviation
- optionally present as a comment in parentheses.
- </p>
-
- <p>
- The first `title' line with the package name should start
- at the left hand margin; the `trailer' line with the
- maintainer and date details should be preceded by exactly
- one space. The maintainer details and the date must be
- separated by exactly two spaces.
- </p>
-
- <sect1><heading>Defining alternative changelog formats</heading>
-
- <p>
- It is possible to use a different format to the standard
- one, by providing a parser for the format you wish to
- use.
- </p>
- <p>
- A changelog parser must not interact with the user at
- all.
- </p>
- </sect1>
- </sect>
-
- <sect id="srcsubstvars"><heading><file>debian/substvars</file>
- and variable substitutions </heading>
-
- <p>
- When <prgn>dpkg-gencontrol</prgn>,
- <prgn>dpkg-genchanges</prgn> and <prgn>dpkg-source</prgn>
- generate control files they perform variable substitutions
- on their output just before writing it. Variable
- substitutions have the form <tt>${<var>variable</var>}</tt>.
- The optional file <file>debian/substvars</file> contains
- variable substitutions to be used; variables can also be set
- directly from <file>debian/rules</file> using the <tt>-V</tt>
- option to the source packaging commands, and certain
- predefined variables are also available.
- </p>
-
- <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.
- </p>
-
- <p>
- See <manref name="dpkg-source" section="1"> for full
- details about source variable substitutions, including the
- format of <file>debian/substvars</file>.</p>
- </sect>
-
- <sect id="debianfiles"><heading><file>debian/files</file>
- </heading>
-
- <p>
- This file is not a permanent part of the source tree; it
- is used while building packages to record which files are
- being generated. <prgn>dpkg-genchanges</prgn> uses it
- when it generates a <file>.changes</file> file.
+ This file is not a permanent part of the source tree; it
+ is used while building packages to record which files are
+ being generated. <prgn>dpkg-genchanges</prgn> uses it
+ when it generates a <file>.changes</file> file.
</p>
<p>
It should not exist in a shipped source package, and so it
(and any backup files or temporary files such as
<file>files.new</file><footnote>
- <p>
<file>files.new</file> is used as a temporary file by
<prgn>dpkg-gencontrol</prgn> and
<prgn>dpkg-distaddfile</prgn> - they write a new
version of <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
the file to the list in <file>debian/files</file>.</p>
</sect>
- <sect id="restrictions"><heading>Restrictions on objects in source packages
- </heading>
+ <sect id="embeddedfiles">
+ <heading>Convenience copies of code</heading>
<p>
- The source package may not contain any hard links<footnote>
- <p>
- This is not currently detected when building source
- packages, but only when extracting
- them.
- </p>
- <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>
+ Some software packages include in their distribution convenience
+ copies of code from other software packages, generally so that
+ users compiling from source don't have to download multiple
+ packages. Debian packages should not make use of these
+ convenience copies unless the included package is explicitly
+ intended to be used in this way.<footnote>
+ For example, parts of the GNU build system work like this.
+ </footnote>
+ If the included code is already in the Debian archive in the
+ form of a library, the Debian packaging should ensure that
+ binary packages reference the libraries already in Debian and
+ the convenience copy is not used. If the included code is not
+ already in Debian, it should be packaged separately as a
+ prerequisite if possible.
+ <footnote>
+ Having multiple copies of the same code in Debian is
+ inefficient, often creates either static linking or shared
+ library conflicts, and, most importantly, increases the
+ difficulty of handling security vulnerabilities in the
+ duplicated code.
</footnote>
</p>
</sect>
- <sect id="descriptions"><heading>Descriptions of packages - the
- <tt>Description</tt> field </heading>
+
+ <sect id="readmesource">
+ <heading>Source package handling:
+ <file>debian/README.source</file></heading>
<p>
- The description is intended to describe the program to a user
- who has never met it before so that they know whether they
- want to install it. It should also give information about the
- significant dependencies and conflicts between this package
- and others, so that the user knows why these dependencies and
- conflicts have been declared.
+ If running <prgn>dpkg-source -x</prgn> on a source package
+ doesn't produce the source of the package, ready for editing,
+ and allow one to make changes and run
+ <prng>dpkg-buildpackage</prgn> to produce a modified package
+ without taking any additional steps, creating a
+ <file>debian/README.source</file> documentation file is
+ recommended. This file should explain how to do all of the
+ following:
+ <enumlist>
+ <item>Generate the fully patched source, in a form ready for
+ editing, that would be built to create Debian
+ packages. Doing this with a <tt>patch</tt> target in
+ <file>debian/rules</file> is recommended; see
+ <ref id="debianrules">.</item>
+ <item>Modify the source and save those modifications so that
+ they will be applied when building the package.</item>
+ <item>Remove source modifications that are currently being
+ applied when building the package.</item>
+ <item>Optionally, document what steps are necessary to
+ upgrade the Debian source package to a new upstream version,
+ if applicable.</item>
+ </enumlist>
+ This explanation should include specific commands and mention
+ any additional required Debian packages. It should not assume
+ familiarity with any specific Debian packaging system or patch
+ management tools.
</p>
- <sect1><heading>Notes about writing descriptions
- </heading>
+ <p>
+ This explanation may refer to a documentation file installed by
+ one of the package's build dependencies provided that the
+ referenced documentation clearly explains these tasks and is not
+ a general reference manual.
+ </p>
- <p>
- The single line synopsis should be kept brief - certainly
- under 80 characters.
- </p>
+ <p>
+ <file>debian/README.source</file> may also include any other
+ information that would be helpful to someone modifying the
+ source package. Even if the package doesn't fit the above
+ description, maintainers are encouraged to document in a
+ <file>debian/README.source</file> file any source package with a
+ particularly complex or unintuitive source layout or build
+ system (for example, a package that builds the same source
+ multiple times to generate different binary packages).
+ </p>
+ </sect>
+ </chapt>
- <p>
- Do not include the package name in the synopsis line. The
- display software knows how to display this already, and you
- do not need to state it. Remember that in many situations
- the user may only see the synopsis line - make it as
- informative as you can.
- </p>
- <p>
- Do not try to continue the single line synopsis into the
- extended description. This will not work correctly when
- the full description is displayed, and makes no sense
- where only the summary (the single line synopsis) is
- available.
- </p>
+ <chapt id="controlfields">
+ <heading>Control files and their fields</heading>
- <p>
- The extended description should describe what the package
- does and how it relates to the rest of the system (in terms
- of, for example, which subsystem it is which part of).
- </p>
+ <p>
+ The package management system manipulates data represented in
+ a common format, known as <em>control data</em>, stored in
+ <em>control files</em>.
+ Control files are used for source packages, binary packages and
+ the <file>.changes</file> files which control the installation
+ of uploaded files<footnote>
+ <prgn>dpkg</prgn>'s internal databases are in a similar
+ format.
+ </footnote>.
+ </p>
- <p>
- 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>
+ <sect id="controlsyntax">
+ <heading>Syntax of control files</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>
+ <p>
+ A control file consists of one or more paragraphs of
+ fields<footnote>
+ The paragraphs are also sometimes referred to as stanzas.
+ </footnote>.
+ The paragraphs are separated by blank lines. Some control
+ files allow only one paragraph; others allow several, in
+ which case each paragraph usually refers to a different
+ package. (For example, in source packages, the first
+ paragraph refers to the source package, and later paragraphs
+ refer to binary packages generated from the source.)
+ </p>
- <p>
- You may include information about dependencies and so forth
- in the extended description, if you wish.
- </p>
+ <p>
+ Each paragraph consists of a series of data fields; each
+ field consists of the field name, followed by a colon and
+ then the data/value associated with that field. It ends at
+ the end of the (logical) line. Horizontal whitespace
+ (spaces and tabs) may occur immediately before or after the
+ value and is ignored there; it is conventional to put a
+ single space after the colon. For example, a field might
+ be:
+ <example compact="compact">
+Package: libc6
+ </example>
+ the field name is <tt>Package</tt> and the field value
+ <tt>libc6</tt>.
+ </p>
- <p>
- Do not use tab characters. Their effect is not predictable.
- </p>
+ <p>
+ Many fields' values may span several lines; in this case
+ each continuation line must start with a space or a tab.
+ Any trailing spaces or tabs at the end of individual
+ lines of a field value are ignored.
+ </p>
- </sect1>
- </sect>
- </chapt>
+ <p>
+ In fields where it is specified that lines may not wrap,
+ only a single line of data is allowed and whitespace is not
+ significant in a field body. Whitespace must not appear
+ inside names (of packages, architectures, files or anything
+ else) or version numbers, or between the characters of
+ multi-character version relationships.
+ </p>
+ <p>
+ Field names are not case-sensitive, but it is usual to
+ capitalize the field names using mixed case as shown below.
+ </p>
- <chapt id="maintainerscripts"><heading>Package maintainer scripts
- and installation procedure
- </heading>
+ <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>
- <sect><heading>Introduction to package maintainer scripts
- </heading>
+ </sect>
+
+ <sect id="sourcecontrolfiles">
+ <heading>Source package control files -- <file>debian/control</file></heading>
<p>
- It is possible to supply scripts as part of a package which
- the package management system will run for you when your
- package is installed, upgraded or removed.
+ The <file>debian/control</file> file contains the most vital
+ (and version-independent) information about the source package
+ and about the binary packages it creates.
</p>
<p>
- These scripts are the files <prgn>preinst</prgn>,
- <prgn>postinst</prgn>, <prgn>prerm</prgn> and <prgn>postrm</prgn> in the
- control area of the package. They must be proper executable
- files; if they are scripts (which is recommended), they must
- start with the usual <tt>#!</tt> convention. They should be
- readable and executable by anyone, and not world-writable.
+ The first paragraph of the control file contains information about
+ the source package in general. The subsequent sets each describe a
+ binary package that the source tree builds.
</p>
<p>
- The package management system looks at the exit status from
- these scripts. It is important that they exit with a
- non-zero status if there is an error, so that the package
- management system can stop its processing. For shell
- scripts this means that you <em>almost always</em> need to
- use <tt>set -e</tt> (this is usually true when writing shell
- scripts, in fact). It is also important, of course, that
- they don't exit with a non-zero status if everything went
- well.
+ The fields in the general paragraph (the first one, for the source
+ package) are:
+
+ <list compact="compact">
+ <item><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</item>
+ <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
+ <item><qref id="f-Uploaders"><tt>Uploaders</tt></qref></item>
+ <item><qref id="f-Section"><tt>Section</tt></qref> (recommended)</item>
+ <item><qref id="f-Priority"><tt>Priority</tt></qref> (recommended)</item>
+ <item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
+ <item><qref id="f-Standards-Version"><tt>Standards-Version</tt></qref> (recommended)</item>
+ <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
+ </list>
</p>
<p>
- When a package is upgraded a combination of the scripts from
- the old and new packages is called during the upgrade
- procedure. If your scripts are going to be at all
- complicated you need to be aware of this, and may need to
- check the arguments to your scripts.
+ The fields in the binary package paragraphs are:
+
+ <list compact="compact">
+ <item><qref id="f-Package"><tt>Package</tt></qref> (mandatory)</item>
+ <item><qref id="f-Architecture"><tt>Architecture</tt></qref> (mandatory)</item>
+ <item><qref id="f-Section"><tt>Section</tt></qref> (recommended)</item>
+ <item><qref id="f-Priority"><tt>Priority</tt></qref> (recommended)</item>
+ <item><qref id="f-Essential"><tt>Essential</tt></qref></item>
+ <item><qref id="binarydeps"><tt>Depends</tt> et al</qref></item>
+ <item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
+ <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
+ </list>
</p>
<p>
- Broadly speaking the <prgn>preinst</prgn> is called before
- (a particular version of) a package is installed, and the
- <prgn>postinst</prgn> afterwards; the <prgn>prerm</prgn>
- before (a version of) a package is removed and the
- <prgn>postrm</prgn> afterwards.
+ The syntax and semantics of the fields are described below.
</p>
+<!-- stuff -->
+
<p>
- Programs called from maintainer scripts should not normally
- have a path prepended to them. Before installation is
- started, the package management system checks to see if the
- programs <prgn>ldconfig</prgn>,
- <prgn>start-stop-daemon</prgn>, <prgn>install-info</prgn>,
- and <prgn>update-rc.d</prgn> can be found via the
- <tt>PATH</tt> environment variable. Those programs, and any
- other program that one would expect to be on the
- <tt>PATH</tt>, should thus be invoked without an absolute
- pathname. Maintainer scripts should also not reset the
- <tt>PATH</tt>, though they might choose to modify it by
- prepending or appending package-specific directories. These
- considerations really apply to all shell scripts.</p>
- </sect>
-
- <sect>
- <heading>Maintainer scripts Idempotency</heading>
+ These fields are used by <prgn>dpkg-gencontrol</prgn> to
+ generate control files for binary packages (see below), by
+ <prgn>dpkg-genchanges</prgn> to generate the
+ <tt>.changes</tt> file to accompany the upload, and by
+ <prgn>dpkg-source</prgn> when it creates the
+ <file>.dsc</file> source control file as part of a source
+ archive. Many fields are permitted to span multiple lines in
+ <file>debian/control</file> but not in any other control
+ file. These tools are responsible for removing the line
+ breaks from such fields when using fields from
+ <file>debian/control</file> to generate other control files.
+ </p>
<p>
- It is necessary for the error recovery procedures that the
- scripts be idempotent. This means that if it is run
- successfully, and then it is called again, it doesn't bomb
- out or cause any harm, but just ensures that everything is
- the way it ought to be. If the first call failed, or
- 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>
- 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>
+ The fields here may contain variable references - their
+ values will be substituted by <prgn>dpkg-gencontrol</prgn>,
+ <prgn>dpkg-genchanges</prgn> or <prgn>dpkg-source</prgn>
+ when they generate output control files.
+ See <ref id="substvars"> for details.
</p>
+
</sect>
- <sect>
- <heading>Controlling terminal for maintainer scripts</heading>
+ <sect id="binarycontrolfiles">
+ <heading>Binary package control files -- <file>DEBIAN/control</file></heading>
<p>
- The maintainer scripts are guaranteed to run with a
- controlling terminal and can interact with the user.
- If they need to prompt for passwords, do full-screen
- interaction or something similar you should do these
- things to and from <file>/dev/tty</file>, since
- <prgn>dpkg</prgn> will at some point redirect scripts'
- standard input and output so that it can log the
- installation process. Likewise, because these scripts
- may be executed with standard output redirected into a
- pipe for logging purposes, Perl scripts should set
- unbuffered output by setting <tt>$|=1</tt> so that the
- output is printed immediately rather than being
- buffered.
+ The <file>DEBIAN/control</file> file contains the most vital
+ (and version-dependent) information about a binary package.
</p>
<p>
- Each script should return a zero exit status for
- success, or a nonzero one for failure.
+ The fields in this file are:
+
+ <list compact="compact">
+ <item><qref id="f-Package"><tt>Package</tt></qref> (mandatory)</item>
+ <item><qref id="f-Source"><tt>Source</tt></qref></item>
+ <item><qref id="f-Version"><tt>Version</tt></qref> (mandatory)</item>
+ <item><qref id="f-Section"><tt>Section</tt></qref> (recommended)</item>
+ <item><qref id="f-Priority"><tt>Priority</tt></qref> (recommended)</item>
+ <item><qref id="f-Architecture"><tt>Architecture</tt></qref> (mandatory)</item>
+ <item><qref id="f-Essential"><tt>Essential</tt></qref></item>
+ <item><qref id="binarydeps"><tt>Depends</tt> et al</qref></item>
+ <item><qref id="f-Installed-Size"><tt>Installed-Size</tt></qref></item>
+ <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
+ <item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
+ <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
+ </list>
</p>
</sect>
- <sect id="mscriptsinstact"><heading>Summary of ways maintainer
- scripts are called
- </heading>
+ <sect id="debiansourcecontrolfiles">
+ <heading>Debian source control files -- <tt>.dsc</tt></heading>
<p>
- <list compact="compact">
- <item>
- <p><var>new-preinst</var> <tt>install</tt></p>
- </item>
- <item>
- <p><var>new-preinst</var> <tt>install</tt>
- <var>old-version</var></p>
- </item>
- <item>
- <p><var>new-preinst</var> <tt>upgrade</tt>
- <var>old-version</var></p>
- </item>
- <item>
- <p><var>old-preinst</var> <tt>abort-upgrade</tt>
- <var>new-version</var>
- </p>
- </item>
- </list>
+ This file contains a series of fields, identified and
+ separated just like the fields in the control file of
+ a binary package. The fields are listed below; their
+ syntax is described above, in <ref id="pkg-controlfields">.
+
+ <list compact="compact">
+ <item><qref id="f-Format"><tt>Format</tt></qref> (mandatory)</item>
+ <item><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</item>
+ <item><qref id="f-Version"><tt>Version</tt></qref> (mandatory)</item>
+ <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
+ <item><qref id="f-Uploaders"><tt>Uploaders</tt></qref></item>
+ <item><qref id="f-Binary"><tt>Binary</tt></qref></item>
+ <item><qref id="f-Architecture"><tt>Architecture</tt></qref></item>
+ <item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
+ <item><qref id="f-Standards-Version"><tt>Standards-Version</tt></qref> (recommended)</item>
+ <item><qref id="f-Files"><tt>Files</tt></qref> (mandatory)</item>
+ <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
+ </list>
+ </p>
<p>
- <list compact="compact">
- <item>
- <p><var>postinst</var> <tt>configure</tt>
- <var>most-recently-configured-version</var></p>
- </item>
- <item>
- <p><var>old-postinst</var> <tt>abort-upgrade</tt>
- <var>new-version</var></p>
- </item>
- <item>
- <p><var>conflictor's-postinst</var> <tt>abort-remove</tt>
- <tt>in-favour</tt> <var>package</var>
- <var>new-version</var></p>
- </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>
+ The source package control file is generated by
+ <prgn>dpkg-source</prgn> when it builds the source
+ archive, from other files in the source package,
+ described above. When unpacking, it is checked against
+ the files and directories in the other parts of the
+ source package.
+ </p>
+
+ </sect>
+
+ <sect id="debianchangesfiles">
+ <heading>Debian changes files -- <file>.changes</file></heading>
<p>
- <list compact="compact">
- <item>
- <p><var>prerm</var> <tt>remove</tt></p>
- </item>
- <item>
- <p><var>old-prerm</var> <tt>upgrade</tt>
- <var>new-version</var></p>
- </item>
- <item>
- <p><var>new-prerm</var> <tt>failed-upgrade</tt>
- <var>old-version</var></p>
- </item>
- <item>
- <p><var>conflictor's-prerm</var> <tt>remove</tt>
- <tt>in-favour</tt> <var>package</var>
- <var>new-version</var></p>
- </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>
+ The .changes files are used by the Debian archive maintenance
+ software to process updates to packages. They contain one
+ paragraph which contains information from the
+ <tt>debian/control</tt> file and other data about the
+ source package gathered via <tt>debian/changelog</tt>
+ and <tt>debian/rules</tt>.
+ </p>
<p>
+ The fields in this file are:
+
<list compact="compact">
- <item>
- <p><var>postrm</var> <tt>remove</tt></p>
- </item>
- <item>
- <p><var>postrm</var> <tt>purge</tt></p>
- </item>
- <item>
- <p>
- <var>old-postrm</var> <tt>upgrade</tt>
- <var>new-version</var></p>
- </item>
- <item>
- <p><var>new-postrm</var> <tt>failed-upgrade</tt>
- <var>old-version</var></p>
- </item>
- <item>
- <p><var>new-postrm</var> <tt>abort-install</tt></p>
- </item>
- <item>
- <p><var>new-postrm</var> <tt>abort-install</tt>
- <var>old-version</var></p>
- </item>
- <item>
- <p><var>new-postrm</var> <tt>abort-upgrade</tt>
- <var>old-version</var></p>
- </item>
- <item>
- <p>
- <var>disappearer's-postrm</var> <tt>disappear</tt>
- <var>overwriter</var>
- <var>overwriter-version</var></p></item>
+ <item><qref id="f-Format"><tt>Format</tt></qref> (mandatory)</item>
+ <item><qref id="f-Date"><tt>Date</tt></qref> (mandatory)</item>
+ <item><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</item>
+ <item><qref id="f-Binary"><tt>Binary</tt></qref> (mandatory)</item>
+ <item><qref id="f-Architecture"><tt>Architecture</tt></qref> (mandatory)</item>
+ <item><qref id="f-Version"><tt>Version</tt></qref> (mandatory)</item>
+ <item><qref id="f-Distribution"><tt>Distribution</tt></qref> (mandatory)</item>
+ <item><qref id="f-Urgency"><tt>Urgency</tt></qref> (recommended)</item>
+ <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
+ <item><qref id="f-Changed-By"><tt>Changed-By</tt></qref></item>
+ <item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
+ <item><qref id="f-Closes"><tt>Closes</tt></qref></item>
+ <item><qref id="f-Changes"><tt>Changes</tt></qref> (mandatory)</item>
+ <item><qref id="f-Files"><tt>Files</tt></qref> (mandatory)</item>
</list>
</p>
+ </sect>
+ <sect id="controlfieldslist">
+ <heading>List of fields</heading>
- <sect id="unpackphase"><heading>Details of unpack phase of
- installation or upgrade
- </heading>
+ <sect1 id="f-Source">
+ <heading><tt>Source</tt></heading>
- <p>
- The procedure on installation/upgrade/overwrite/disappear
- (i.e., when running <tt>dpkg --unpack</tt>, or the unpack
- stage of <tt>dpkg --install</tt>) is as follows. In each
- 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
- below.
+ <p>
+ This field identifies the source package name.
+ </p>
- <enumlist>
- <item>
- <p>
- <enumlist>
- <item>
- <p>If a version of the package is already
- installed, call
- <example compact="compact">
-<var>old-prerm</var> upgrade <var>new-version</var>
- </example></p>
- </item>
- <item>
- <p>
- If the script runs but exits with a non-zero
- exit status, <prgn>dpkg</prgn> will attempt:
- <example compact="compact">
-<var>new-prerm</var> failed-upgrade <var>old-version</var>
- </example>
- Error unwind, for both the above cases:
- <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:
- <enumlist>
- <item>
- <p>
- If any packages depended on that conflicting
- package and <tt>--auto-deconfigure</tt> is
- specified, call, for each such package:
- <example compact="compact">
-<var>deconfigured's-prerm</var> deconfigure \
- in-favour <var>package-being-installed</var> <var>version</var> \
- removing <var>conflicting-package</var> <var>version</var>
- </example>
- Error unwind:
- <example compact="compact">
-<var>deconfigured's-postinst</var> abort-deconfigure \
- in-favour <var>package-being-installed-but-failed</var> <var>version</var> \
- removing <var>conflicting-package</var> <var>version</var>
- </example>
- The deconfigured packages are marked as
- requiring configuration, so that if
- <tt>--install</tt> is used they will be
- configured again if possible.</p>
- </item>
- <item>
- <p>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>
- </example>
- Error unwind:
- <example compact="compact">
-<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:
- <example compact="compact">
-<var>new-preinst</var> upgrade <var>old-version</var>
- </example></p>
- </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):
- <example compact="compact">
-<var>new-preinst</var> install <var>old-version</var>
- </example></p>
+ <p>
+ In <file>debian/control</file> or a <file>.dsc</file> file,
+ this field must contain only the name of the source package.
+ </p>
- <item>
- <p>Otherwise (i.e., the package was completely purged):
- <example compact="compact">
-<var>new-preinst</var> install
- </example>
- Error unwind actions, respectively:
- <example compact="compact">
-<var>new-postrm</var> abort-upgrade <var>old-version</var>
-<var>new-postrm</var> abort-install <var>old-version</var>
-<var>new-postrm</var> abort-install
- </example>
- </p>
- </item>
- </enumlist>
- </p>
- </item>
- <item>
- <p>
- The new package's files are unpacked, overwriting any
- that may be on the system already, for example any
- from the old version of the same package or from
- another package. Backups of the old files are kept
- temporarily, and if anything goes wrong the package
- management system will attempt to put them back as
- part of the error unwind.
- </p>
+ <p>
+ In a binary package control file or a <file>.changes</file>
+ file, the source package name may be followed by a version
+ number in parentheses<footnote>
+ It is customary to leave a space after the package name
+ if a version number is specified.
+ </footnote>.
+ This version number may be omitted (and is, by
+ <prgn>dpkg-gencontrol</prgn>) if it has the same value as
+ the <tt>Version</tt> field of the binary package in
+ question. The field itself may be omitted from a binary
+ package control file when the source package has the same
+ name and version as the binary package.
+ </p>
+ </sect1>
- <p>
- It is an error for a package to contains files which
- are on the system in another package, unless
- <tt>Replaces</tt> is used (see <ref id="replaces">).
- <!--
- The following paragraph is not currently the case:
- Currently the <tt>- - force-overwrite</tt> flag is
- enabled, downgrading it to a warning, but this may not
- always be the case.
- -->
- </p>
+ <sect1 id="f-Maintainer">
+ <heading><tt>Maintainer</tt></heading>
- <p>
- It is a more serious error for a package to contain a
- plain file or other kind of non-directory where another
- package has a directory (again, unless
- <tt>Replaces</tt> is used). This error can be
- overridden if desired using
- <tt>--force-overwrite-dir</tt>, but this is not
- advisable.
- </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>
- 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
- 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>
+ <p>
+ If the maintainer's name contains a full stop then the
+ whole field will not work directly as an email address due
+ to a misfeature in the syntax specified in RFC822; a
+ program using this field as an address must check for this
+ and correct the problem if necessary (for example by
+ putting the name in round brackets and moving it to the
+ end, and bringing the email address forward).
+ </p>
+ </sect1>
- <p>
- A directory will never be replaced by a symbolic link
- 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>
- </item>
+ <sect1 id="f-Uploaders">
+ <heading><tt>Uploaders</tt></heading>
- <item>
- <p>
- <enumlist>
- <item>
- <p>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:
- <example compact="compact">
-<var>new-postrm</var> failed-upgrade <var>old-version</var>
- </example>
- Error unwind, for both cases:
- <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
- past this point if an error occurs. This will
- leave the package in a fairly bad state, which
- will require a successful re-installation to clear
- up, but it's when <prgn>dpkg</prgn> starts doing
- 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>
- </item>
- <item>
- <p>The new file list replaces the old.</p>
- </item>
- <item>
- <p>The new maintainer scripts replace the old.</p>
- </item>
+ <p>
+ List of the names and email addresses of co-maintainers of
+ the package, if any. If the package has other maintainers
+ beside the one named in the
+ <qref id="f-Maintainer">Maintainer field</qref>, their
+ names and email addresses should be listed here. The
+ format is the same as that of the Maintainer tag, and
+ multiple entries should be comma separated. Currently,
+ this field is restricted to a single line of data. This
+ is an optional field.
+ </p>
+ <p>
+ Any parser that interprets the Uploaders field in
+ <file>debian/control</file> must permit it to span multiple
+ lines. Line breaks in an Uploaders field that spans multiple
+ lines are not significant and the semantics of the field are
+ the same as if the line breaks had not been present.
+ </p>
+ </sect1>
- <item>
- <p>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:
- <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>
- </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
- removed by <prgn>dpkg</prgn>). Note that
- disappearing packages do not have their prerm
- 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>
- </item>
- <item>
- <p>
- The backup files made during installation, above, are
- deleted.
- </p>
- </item>
+ <sect1 id="f-Changed-By">
+ <heading><tt>Changed-By</tt></heading>
- <item>
- <p>
- The new package's status is now sane, and recorded as
- `unpacked'.
- </p>
+ <p>
+ The name and email address of the person who changed the
+ said package. Usually the name of the maintainer.
+ All the rules for the Maintainer field apply here, too.
+ </p>
+ </sect1>
- <p>
- Here is another point of no return - if the
- conflicting package's removal fails we do not unwind
- the rest of the installation; the conflicting package
- is left in a half-removed limbo.
- </p>
- </item>
+ <sect1 id="f-Section">
+ <heading><tt>Section</tt></heading>
- <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>
- </sect>
+ <p>
+ This field specifies an application area into which the package
+ has been classified. See <ref id="subsections">.
+ </p>
- <sect id="configdetails"><heading>Details of configuration</heading>
+ <p>
+ When it appears in the <file>debian/control</file> file,
+ it gives the value for the subfield of the same name in
+ the <tt>Files</tt> field of the <file>.changes</file> file.
+ It also gives the default for the same field in the binary
+ packages.
+ </p>
+ </sect1>
- <p>
- When we configure a package (this happens with <tt>dpkg
- --install</tt> and <tt>dpkg --configure</tt>), we first
- update any <tt>conffile</tt>s and then call:
- <example compact="compact">
-<var>postinst</var> configure <var>most-recently-configured-version</var>
- </example>
- </p>
+ <sect1 id="f-Priority">
+ <heading><tt>Priority</tt></heading>
- <p>
- No attempt is made to unwind after errors during
- configuration.
- </p>
+ This field represents how important that it is that the user
+ have the package installed. See <ref id="priorities">.
+ </p>
- <p>
- If there is no most recently configured version
- <prgn>dpkg</prgn> will pass a null argument; older versions
- of dpkg may pass <tt><unknown></tt> (including the
- angle brackets) in this case. Even older ones do not pass a
- second argument at all, under any circumstances.
- </p>
- </sect>
+ When it appears in the <file>debian/control</file> file,
+ it gives the value for the subfield of the same name in
+ the <tt>Files</tt> field of the <file>.changes</file> file.
+ It also gives the default for the same field in the binary
+ packages.
+ </p>
+ </sect1>
- <sect id="removedetails"><heading>Details of removal and/or
- configuration purging</heading>
+ <sect1 id="f-Package">
+ <heading><tt>Package</tt></heading>
- <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>
- All the maintainer scripts except the <prgn>postrm</prgn>
- are removed.
- </p>
+ <p>
+ The name of the binary package.
+ </p>
- <p>
- If we aren't purging the package we stop here. Note
- 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>
- </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>
- </item>
- <item>
- <p>
- <example compact="compact">
-<var>postrm</var> purge
- </example>
- </p>
- </item>
- <item>
- <p>The package's file list is removed.</p>
- </item>
- </enumlist>
- No attempt is made to unwind after errors during
- removal.
- </p>
- </sect>
- </chapt>
+ <p>
+ 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 start
+ with an alphanumeric character.
+ </p>
+ </sect1>
+ <sect1 id="f-Architecture">
+ <heading><tt>Architecture</tt></heading>
+
+ <p>
+ Depending on context and the control file used, the
+ <tt>Architecture</tt> field can include the following sets of
+ values:
+ <list>
+ <item>A unique single word identifying a Debian machine
+ architecture, see <ref id="arch-spec">.
+ <item><tt>all</tt>, which indicates an
+ architecture-independent package.
+ <item><tt>any</tt>, which indicates a package available
+ for building on any architecture.
+ <item><tt>source</tt>, which indicates a source package.
+ </list>
+ </p>
- <chapt id="relationships"><heading>Declaring relationships between
- packages</heading>
+ <p>
+ In the main <file>debian/control</file> file in the source
+ package, or in the source package control file
+ <file>.dsc</file>, one may specify a list of architectures
+ separated by spaces, or the special values <tt>any</tt> or
+ <tt>all</tt>.
+ </p>
- <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>
+ Specifying <tt>any</tt> indicates that the source package
+ isn't dependent on any particular architecture and should
+ compile fine on any one. The produced binary package(s)
+ will be specific to whatever the current build architecture
+ is.<footnote>
+ This is the most often used setting, and is recommended
+ for new packages that aren't <tt>Architecture: all</tt>.
+ </footnote>
+ </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>
+ Specifying a list of architectures indicates that the source
+ will build an architecture-dependent package, and will only
+ work correctly on the listed architectures.<footnote>
+ This is a setting used for a minority of cases where the
+ program is not portable. Generally, it should not be used
+ for new packages.
+ </footnote>
+ </p>
- <p>
- Source packages may declare relationships to binary packages,
- saying that they require certain binary packages to be
- installed or absent at the time of building the package.
- </p>
+ <p>
+ In a <file>.changes</file> file, the <tt>Architecture</tt>
+ field lists the architecture(s) of the package(s)
+ currently being uploaded. This will be a list; if the
+ source for the package is also being uploaded, the special
+ entry <tt>source</tt> is also present.
+ </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>
+ See <ref id="debianrules"> for information how to get the
+ architecture for the build process.
+ </p>
+ </sect1>
- <sect id="depsyntax"><heading>Syntax of relationship fields
- </heading>
+ <sect1 id="f-Essential">
+ <heading><tt>Essential</tt></heading>
- <p>
- These fields all have a uniform syntax. They are a list of
- package names separated by commas.
- </p>
+ <p>
+ This is a boolean field which may occur only in the
+ control file of a binary package or in a per-package fields
+ paragraph of a main source control data file.
+ </p>
- <p>
- In the <tt>Depends</tt>, <tt>Recommends</tt>,
- <tt>Suggests</tt>, <tt>Pre-Depends</tt>,
- <tt>Build-Depends</tt> and <tt>Build-Depends-Indep</tt>
- control file fields of the package, which declare
- dependencies on other packages, the package names listed may
- also include lists of alternative package names, separated
- by vertical bar (pipe) symbols <tt>|</tt>. In such a case,
- if any one of the alternative packages is installed, that
- part of the dependency is considered to be satisfied.
- </p>
+ <p>
+ If set to <tt>yes</tt> then the package management system
+ will refuse to remove the package (upgrading and replacing
+ it is still possible). The other possible value is <tt>no</tt>,
+ which is the same as not having the field at all.
+ </p>
+ </sect1>
- <p>
- All of the fields except for <tt>Provides</tt> may restrict
- their applicability to particular versions of each named
- package. This is done in parentheses after each individual
- package name; the parentheses should contain a relation from
- the list below followed by a version number, in the format
- described in <ref id="versions">.
- </p>
+ <sect1>
+ <heading>Package interrelationship fields:
+ <tt>Depends</tt>, <tt>Pre-Depends</tt>,
+ <tt>Recommends</tt>, <tt>Suggests</tt>,
+ <tt>Breaks</tt>, <tt>Conflicts</tt>,
+ <tt>Provides</tt>, <tt>Replaces</tt>, <tt>Enhances</tt>
+ </heading>
- <p>
- The relations allowed are <tt><<</tt>, <tt><=</tt>,
- <tt>=</tt>, <tt>>=</tt> and <tt>>></tt> for
- strictly earlier, earlier or equal, exactly equal, later or
- equal and strictly later, respectively. The deprecated
- forms <tt><</tt> and <tt>></tt> were used to mean
- earlier/later or equal, rather than strictly earlier/later,
- so they should not appear in new packages (though
- <prgn>dpkg</prgn> still supports them).
- </p>
+ <p>
+ These fields describe the package's relationships with
+ other packages. Their syntax and semantics are described
+ in <ref id="relationships">.</p>
+ </sect1>
- <p>
- Whitespace may appear at any point in the version
- specification subject to the rules in <ref
- id="controlsyntax">, and must appear where it's necessary to
- disambiguate; it is not otherwise significant. For
- consistency and in case of future changes to
- <prgn>dpkg</prgn> it is recommended that a single space be
- used after a version relationship and before a version
- number; it is also conventional to put a single space after
- each comma, on either side of each vertical bar, and before
- each open parenthesis.
- </p>
+ <sect1 id="f-Standards-Version">
+ <heading><tt>Standards-Version</tt></heading>
- <p>
- For example, a list of dependencies might appear as:
- <example compact="compact">
-Package: mutt
-Version: 1.3.17-1
-Depends: libc6 (>= 2.2.1), exim | mail-transport-agent
- </example>
- </p>
+ <p>
+ The most recent version of the standards (the policy
+ manual and associated texts) with which the package
+ complies.
+ </p>
- <p>
- All fields that specify build-time relationships
- (<tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
- <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>)
- may be restricted to a certain set of architectures. This
- is indicated in brackets after each individual package name and
- the optional version specification. The brackets enclose a
- list of Debian architecture names separated by whitespace.
- Exclamation marks may be prepended to each of the names.
- (It is not permitted for some names to be prepended with
- exclamation marks and others not.) If the current Debian
- host architecture is not in this list and there are no
- exclamation marks in the list, or it is in the list with a
- prepended exclamation mark, the package name and the
- associated version specification are ignored completely for
- the purposes of defining the relationships.
- </p>
+ <p>
+ The version number has four components: major and minor
+ version number and major and minor patch level. When the
+ standards change in a way that requires every package to
+ change the major number will be changed. Significant
+ changes that will require work in many packages will be
+ signaled by a change to the minor number. The major patch
+ level will be changed for any change to the meaning of the
+ standards, however small; the minor patch level will be
+ changed when only cosmetic, typographical or other edits
+ are made which neither change the meaning of the document
+ nor affect the contents of packages.
+ </p>
- <p>
- For example:
- <example compact="compact">
-Source: glibc
-Build-Depends-Indep: texinfo
-Build-Depends: kernel-headers-2.2.10 [!hurd-i386],
- hurd-dev [hurd-i386], gnumach-dev [hurd-i386]
- </example>
- </p>
+ <p>
+ Thus only the first three components of the policy version
+ 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>
+ In the past, people specified the full version number
+ 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
+ components may still be used if someone wishes to do so.
+ </footnote>
+ </p>
- <p>
- Note that the binary package relationship fields such as
- <tt>Depends</tt> appear in one of the binary package
- sections of the control file, whereas the build-time
- relationships such as <tt>Build-Depends</tt> appear in the
- source package section of the control file (which is the
- first section).
- </p>
- </sect>
+ </sect1>
- <sect>
- <heading>Binary Dependencies - <tt>Depends</tt>,
- <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
- <tt>Pre-Depends</tt>
- </heading>
+ <sect1 id="f-Version">
+ <heading><tt>Version</tt></heading>
- <p>
- These five fields are used to declare a dependency
- relationship by one package on another. Except for
- <tt>Enhances</tt>, they appear in the depending (binary)
- package's control file. (<tt>Enhances</tt> appears in the
- recommending package's control file.)
- </p>
+ <p>
+ The version number of a package. The format is:
+ [<var>epoch</var><tt>:</tt>]<var>upstream_version</var>[<tt>-</tt><var>debian_revision</var>]
+ </p>
- <p>
- A <tt>Depends</tt> field takes effect <em>only</em> when a
- package is to be configured. It does not prevent a package
- being on the system in an unconfigured state while its
- dependencies are unsatisfied, and it is possible to replace
- a package whose dependencies are satisfied and which is
- properly installed with a different version whose
- dependencies are not and cannot be satisfied; when this is
- done the depending package will be left unconfigured (since
- attempts to configure it will give errors) and will not
- function properly. If it is necessary, a
- <tt>Pre-Depends</tt> field can be used, which has a partial
- effect even when a package is being unpacked, as explained
- in detail below. (The other three dependency fields,
- <tt>Recommends</tt>, <tt>Suggests</tt> and
- <tt>Enhances</tt>, are only used by the various front-ends
- to <prgn>dpkg</prgn> such as <prgn>dselect</prgn>.)
- </p>
+ The three components here are:
+ <taglist>
+ <tag><var>epoch</var></tag>
+ <item>
+ <p>
+ This is a single (generally small) unsigned integer. It
+ may be omitted, in which case zero is assumed. If it is
+ omitted then the <var>upstream_version</var> may not
+ contain any colons.
+ </p>
+
+ <p>
+ It is provided to allow mistakes in the version numbers
+ of older versions of a package, and also a package's
+ previous version numbering schemes, to be left behind.
+ </p>
+ </item>
- <p>
- For this reason packages in an installation run are usually
- all unpacked first and all configured later; this gives
- later versions of packages with dependencies on later
- versions of other packages the opportunity to have their
- dependencies satisfied.
- </p>
+ <tag><var>upstream_version</var></tag>
+ <item>
+ <p>
+ This is the main part of the version number. It is
+ usually the version number of the original ("upstream")
+ package from which the <file>.deb</file> file has been made,
+ if this is applicable. Usually this will be in the same
+ format as that specified by the upstream author(s);
+ however, it may need to be reformatted to fit into the
+ package management system's format and comparison
+ scheme.
+ </p>
+
+ <p>
+ The comparison behavior of the package management system
+ with respect to the <var>upstream_version</var> is
+ described below. The <var>upstream_version</var>
+ portion of the version number is mandatory.
+ </p>
+
+ <p>
+ The <var>upstream_version</var> may contain only
+ alphanumerics<footnote>
+ Alphanumerics are <tt>A-Za-z0-9</tt> only.
+ </footnote>
+ and the characters <tt>.</tt> <tt>+</tt> <tt>-</tt>
+ <tt>:</tt> <tt>~</tt> (full stop, plus, hyphen, colon,
+ tilde) and should start with a digit. If there is no
+ <var>debian_revision</var> then hyphens are not allowed;
+ if there is no <var>epoch</var> then colons are not
+ allowed.
+ </p>
+ </item>
- <p>
- The <tt>Depends</tt> field thus allows package maintainers
- to impose an order in which packages should be configured.
- </p>
+ <tag><var>debian_revision</var></tag>
+ <item>
+ <p>
+ This part of the version number specifies the version of
+ the Debian package based on the upstream version. It
+ may contain only alphanumerics and the characters
+ <tt>+</tt> <tt>.</tt> <tt>~</tt> (plus, full stop,
+ tilde) and is compared in the same way as the
+ <var>upstream_version</var> is.
+ </p>
+
+ <p>
+ It is optional; if it isn't present then the
+ <var>upstream_version</var> may not contain a hyphen.
+ This format represents the case where a piece of
+ software was written specifically to be turned into a
+ Debian package, and so there is only one "debianisation"
+ of it and therefore no revision indication is required.
+ </p>
+
+ <p>
+ It is conventional to restart the
+ <var>debian_revision</var> at <tt>1</tt> each time the
+ <var>upstream_version</var> is increased.
+ </p>
+
+ <p>
+ The package management system will break the version
+ number apart at the last hyphen in the string (if there
+ is one) to determine the <var>upstream_version</var> and
+ <var>debian_revision</var>. The absence of a
+ <var>debian_revision</var> compares earlier than the
+ presence of one (but note that the
+ <var>debian_revision</var> is the least significant part
+ of the version number).
+ </p>
+ </item>
+ </taglist>
+ </p>
- <p>
- The meaning of the five dependency fields is as follows:
- <taglist>
- <tag><tt>Depends</tt></tag>
- <item>
- <p>
- This declares an absolute dependency. A package will
- not be configured unless all of the packages listed in
- its <tt>Depends</tt> field have been correctly
- configured.
- </p>
+ <p>
+ The <var>upstream_version</var> and <var>debian_revision</var>
+ parts are compared by the package management system using the
+ same algorithm:
+ </p>
- <p>
- The <tt>Depends</tt> field should be used if the
- depended-on package is required for the depending
- 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
- <prgn>postrm</prgn> scripts require the package to be
- present in order to run. Note, however, that the
- <prgn>postrm</prgn> cannot rely on any non-essential
- packages to be present during the <tt>purge</tt>
- phase.
- </item>
+ <p>
+ The strings are compared from left to right.
+ </p>
- <tag><tt>Recommends</tt></tag>
- <item>
- <p>This declares a strong, but not absolute, dependency.
- </p>
+ <p>
+ First the initial part of each string consisting entirely of
+ non-digit characters is determined. These two parts (one of
+ which may be empty) are compared lexically. If a difference
+ is found it is returned. The lexical comparison is a
+ comparison of ASCII values modified so that all the letters
+ sort earlier than all the non-letters and so that a tilde
+ sorts before anything, even the end of a part. For example,
+ the following parts are in sorted order from earliest to
+ latest: <tt>~~</tt>, <tt>~~a</tt>, <tt>~</tt>, the empty part,
+ <tt>a</tt>.<footnote>
+ One common use of <tt>~</tt> is for upstream pre-releases.
+ For example, <tt>1.0~beta1~svn1245</tt> sorts earlier than
+ <tt>1.0~beta1</tt>, which sorts earlier than <tt>1.0</tt>.
+ </footnote>
+ </p>
- <p>
- The <tt>Recommends</tt> field should list packages
- that would be found together with this one in all but
- unusual installations.</p>
+ <p>
+ Then the initial part of the remainder of each string which
+ consists entirely of digit characters is determined. The
+ numerical values of these two parts are compared, and any
+ difference found is returned as the result of the comparison.
+ For these purposes an empty string (which can only occur at
+ the end of one or both version strings being compared) counts
+ as zero.
+ </p>
+
+ <p>
+ These two steps (comparing and removing initial non-digit
+ strings and initial digit strings) are repeated until a
+ difference is found or both strings are exhausted.
+ </p>
+
+ <p>
+ Note that the purpose of epochs is to allow us to leave behind
+ mistakes in version numbering, and to cope with situations
+ where the version numbering scheme changes. It is
+ <em>not</em> intended to cope with version numbers containing
+ strings of letters which the package management system cannot
+ interpret (such as <tt>ALPHA</tt> or <tt>pre-</tt>), or with
+ silly orderings (the author of this manual has heard of a
+ package whose versions went <tt>1.1</tt>, <tt>1.2</tt>,
+ <tt>1.3</tt>, <tt>1</tt>, <tt>2.1</tt>, <tt>2.2</tt>,
+ <tt>2</tt> and so forth).
+ </p>
+ </sect1>
+
+ <sect1 id="f-Description">
+ <heading><tt>Description</tt></heading>
+
+ <p>
+ In a source or binary control file, the <tt>Description</tt>
+ field contains a description of the binary package, consisting
+ 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 lines in the extended description can have these formats:
+ </p>
+
+ <p><list>
+
+ <item>
+ Those starting with a single space are part of a paragraph.
+ Successive lines of this form will be word-wrapped when
+ displayed. The leading space will usually be stripped off.
</item>
- <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>
+ Those starting with two or more spaces. These will be
+ displayed verbatim. If the display cannot be panned
+ horizontally, the displaying program will line wrap them "hard"
+ (i.e., without taking account of word breaks). If it can they
+ will be allowed to trail off to the right. None, one or two
+ initial spaces may be deleted, but the number of spaces
+ deleted from each line will be the same (so that you can have
+ indenting work correctly, for example).
</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>
+ 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>
- <tag><tt>Pre-Depends</tt></tag>
<item>
- <p>
- This field is like <tt>Depends</tt>, except that it
- also forces <prgn>dpkg</prgn> to complete installation
- of the packages named before even starting the
- installation of the package which declares the
- pre-dependency, as follows:
- </p>
+ Those containing a space, a full stop and some more characters.
+ These are for future expansion. Do not use them.
+ </item>
- <p>
- When a package declaring a pre-dependency is about to
- be <em>unpacked</em> the pre-dependency can be
- satisfied if the depended-on package is either fully
- configured, <em>or even if</em> the depended-on
- package(s) are only unpacked or half-configured,
- provided that they have been configured correctly at
- some point in the past (and not removed or partially
- removed since). In this case, both the
- previously-configured and currently unpacked or
- half-configured versions must satisfy any version
- clause in the <tt>Pre-Depends</tt> field.
- </p>
+ </list></p>
- <p>
- When the package declaring a pre-dependency is about
- to be <em>configured</em>, the pre-dependency will be
- treated as a normal <tt>Depends</tt>, that is, it will
- be considered satisfied only if the depended-on
- package has been correctly configured.
- </p>
+ <p>
+ Do not use tab characters. Their effect is not predictable.
+ </p>
- <p>
- <tt>Pre-Depends</tt> should be used sparingly,
- preferably only by packages whose premature upgrade or
- installation would hamper the ability of the system to
- continue with any upgrade that might be in progress.
- </p>
+ <p>
+ See <ref id="descriptions"> for further information on this.
+ </p>
- <p>
- <tt>Pre-Depends</tt> are also required if the
- <prgn>preinst</prgn> script depends on the named
- package. It is best to avoid this situation if
- possible.
- </item>
- </taglist>
- </p>
- <p>
- When selecting which level of dependency to use you should
- consider how important the depended-on package is to the
- functionality of the one declaring the dependency. Some
- packages are composed of components of varying degrees of
- importance. Such a package should list using
- <tt>Depends</tt> the package(s) which are required by the
- more important components. The other components'
- requirements may be mentioned as Suggestions or
- Recommendations, as appropriate to the components' relative
- importance.
- </p>
+ <p>
+ In a <file>.changes</file> file, the <tt>Description</tt> field
+ contains a summary of the descriptions for the packages being
+ uploaded.
+ </p>
+ <p>
+ The part of the field before the first newline is empty;
+ thereafter each line has the name of a binary package and
+ the summary description line from that binary package.
+ Each line is indented by one space.
+ </p>
- <sect id="conflicts"><heading>Conflicting binary packages -
- <tt>Conflicts</tt></heading>
+ </sect1>
- <p>
- When one binary package declares a conflict with another
- using a <tt>Conflicts</tt> field, <prgn>dpkg</prgn> will
- refuse to allow them to be installed on the system at the
- same time.
- </p>
+ <sect1 id="f-Distribution">
+ <heading><tt>Distribution</tt></heading>
- <p>
- If one package is to be installed, the other must be removed
- first - if the package being installed is marked as
- replacing (see <ref id="replaces">) the one on the system,
- or the one on the system is marked as deselected, or both
- packages are marked <tt>Essential</tt>, then
- <prgn>dpkg</prgn> will automatically remove the package
- which is causing the conflict, otherwise it will halt the
- installation of the new package with an error. This
- mechanism is specifically designed to produce an error when
- the installed package is <tt>Essential</tt>, but the new
- package is not.
- </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
+ be installed. Valid distributions are determined by the
+ archive maintainers.<footnote>
+ Current distribution names are:
+ <taglist compact="compact">
+ <tag><em>stable</em></tag>
+ <item>
+ 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).
+ </item>
- <p>
- A package will not cause a conflict merely because its
- configuration files are still installed; it must be at least
- half-installed.
- </p>
+ <tag><em>unstable</em></tag>
+ <item>
+ 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.
+ </item>
- <p>
- A special exception is made for packages which declare a
- conflict with their own package name, or with a virtual
- package which they provide (see below): this does not
- prevent their installation, and allows a package to conflict
- with others providing a replacement for it. You use this
- feature when you want the package in question to be the only
- package providing some feature.
- </p>
+ <tag><em>testing</em></tag>
+ <item>
+ This distribution value refers to the
+ <em>testing</em> part of the Debian distribution
+ tree. It receives its packages from the
+ unstable distribution after a short time lag to
+ ensure that there are no major issues with the
+ unstable packages. It is less prone to breakage
+ than unstable, but still risky. It is not
+ possible to upload packages directly to
+ <em>testing</em>.
+ </item>
- <p>
- A <tt>Conflicts</tt> entry should almost never have an
- `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.
- </p>
- </sect>
+ <tag><em>frozen</em></tag>
+ <item>
+ From time to time, the <em>testing</em>
+ 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.
+ </item>
- <sect id="virtual"><heading>Virtual packages - <tt>Provides</tt>
- </heading>
+ <tag><em>experimental</em></tag>
+ <item>
+ The packages with this distribution value are
+ deemed by their maintainers to be high
+ risk. Oftentimes they represent early beta or
+ developmental packages from various sources that
+ the maintainers want people to try, but are not
+ ready to be a part of the other parts of the
+ Debian distribution tree. Download at your own
+ risk.
+ </item>
+ </taglist>
- <p>
- 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'.
- </p>
+ <p>
+ You should list <em>all</em> distributions that the
+ package should be installed into.
+ </p>
- <p>
- A <em>virtual package</em> is one which appears in the
- <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.
- </p>
+ More information is available in the Debian Developer's
+ Reference, section "The Debian archive".
+ </p>
+ </footnote>
+ </p>
+ </sect1>
- <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
- <example compact="compact">
-Package: foo
-Depends: bar
- </example>
- and someone else releases an enhanced version of the
- <tt>bar</tt> package (for example, a non-US variant), they
- can say:
- <example compact="compact">
-Package: bar-plus
-Provides: bar
- </example>
- and the <tt>bar-plus</tt> package will now also satisfy the
- dependency for the <tt>foo</tt> package.
- </p>
+ <sect1 id="f-Date">
+ <heading><tt>Date</tt></heading>
- <p>
- If a dependency or a conflict has a version number attached
- then only real packages will be considered to see whether
- the relationship is satisfied (or the prohibition violated,
- for a conflict) - it is assumed that a real package which
- provides the virtual package is not of the `right' version.
- So, a <tt>Provides</tt> field may not contain version
- numbers, and the version number of the concrete package
- which provides a particular virtual package will not be
- looked at when considering a dependency on or conflict with
- the virtual package name.
- </p>
+ <p>
+ This field includes the date the package was built or last edited.
+ </p>
- <p>
- It is likely that the ability will be added in a future
- release of <prgn>dpkg</prgn> to specify a version number for
- each virtual package it provides. This feature is not yet
- present, however, and is expected to be used only
- infrequently.
- </p>
+ <p>
+ The value of this field is usually extracted from the
+ <file>debian/changelog</file> file - see
+ <ref id="dpkgchangelog">).
+ </p>
+ </sect1>
- <p>
- If you want to specify which of a set of real packages
- should be the default to satisfy a particular dependency on
- a virtual package, you should list the real package as an
- alternative before the virtual one.
- </p>
- </sect>
+ <sect1 id="f-Format">
+ <heading><tt>Format</tt></heading>
+ <p>
+ This field specifies a format revision for the file.
+ The most current format described in the Policy Manual
+ is version <strong>1.5</strong>. The syntax of the
+ format value is the same as that of a package version
+ number except that no epoch or Debian revision is allowed
+ - see <ref id="f-Version">.
+ </p>
+ </sect1>
- <sect id="replaces"><heading>Overwriting files and replacing
- packages - <tt>Replaces</tt></heading>
+ <sect1 id="f-Urgency">
+ <heading><tt>Urgency</tt></heading>
- <p>
- The <tt>Replaces</tt> control file field has two distinct
- purposes, which come into play in different situations.
- </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 taking one of the values <tt>low</tt>,
+ <tt>medium</tt>, <tt>high</tt>, <tt>emergency</tt>, or
+ <tt>critical</tt><footnote>
+ Other urgency values are supported with configuration
+ changes in the archive software but are not used in Debian.
+ The urgency affects how quickly a package will be considered
+ for inclusion into the <tt>testing</tt> distribution and
+ gives an indication of the importance of any fixes included
+ in the upload. <tt>Emergency</tt> and <tt>critical</tt> are
+ treated as synonymous.
+ </footnote> (not case-sensitive) followed by an optional
+ commentary (separated by a space) which is usually in
+ parentheses. For example:
- <sect1><heading>Overwriting files in other packages</heading>
+ <example>
+ Urgency: low (HIGH for users of diversions)
+ </example>
- <p>
- Firstly, as mentioned before, it is usually an error for a
- package to contain files which are on the system in
- another package.
</p>
<p>
- However, if the overwriting package declares that it
- <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.
+ The value of this field is usually extracted from the
+ <file>debian/changelog</file> file - see
+ <ref id="dpkgchangelog">.
</p>
+ </sect1>
+
+ <sect1 id="f-Changes">
+ <heading><tt>Changes</tt></heading>
<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
- 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
- will have been taken over by the overwriting package. The
- package's <prgn>postrm</prgn> script will be run with a
- special argument to allow the package to do any final
- cleanup required. See <ref id="mscriptsinstact">.
+ This field contains the human-readable changes data, describing
+ the differences between the last version and the current one.
</p>
<p>
- If an installed package, <tt>foo</tt> say, declares that
- it replaces another, <tt>bar</tt>, and an attempt is made
- to install <tt>bar</tt>, <prgn>dpkg</prgn> will discard
- files in the <tt>bar</tt> package which would overwrite
- those already present in <tt>foo</tt>. This is so that
- you can install an older version of a package without
- problems.
+ 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
+ consisting only of a space and a full stop.
</p>
<p>
- For this usage of <tt>Replaces</tt>, virtual packages (see
- <ref id="virtual">) are not considered when looking at a
- <tt>Replaces</tt> field - the packages declared as being
- replaced must be mentioned by their real names.
+ The value of this field is usually extracted from the
+ <file>debian/changelog</file> file - see
+ <ref id="dpkgchangelog">).
</p>
<p>
- Furthermore, this usage of <tt>Replaces</tt> only takes
- effect when both packages are at least partially on the
- system at once, so that it can only happen if they do not
- conflict or if the conflict has been overridden.
+ Each version's change information should be preceded by a
+ "title" line giving at least the version, distribution(s)
+ and urgency, in a human-readable way.
</p>
+ <p>
+ If data from several versions is being returned the entry
+ for the most recent version should be returned first, and
+ entries should be separated by the representation of a
+ blank line (the "title" line may also be followed by the
+ representation of blank line).
+ </p>
</sect1>
- <sect1><heading>Replacing whole packages, forcing their
- removal</heading>
+ <sect1 id="f-Binary">
+ <heading><tt>Binary</tt></heading>
<p>
- Secondly, <tt>Replaces</tt> allows the packaging system to
- resolve which package should be removed when there is a
- conflict - see <ref id="conflicts">. This usage only
- takes effect when the two packages <em>do</em> conflict,
- so that the two usages of this field do not interfere with
- each other.
+ This field is a list of binary packages.
</p>
<p>
- In this situation, the package declared as being replaced
- can be a virtual package, so for example, all mail
- transport agents (MTAs) would have the following fields in
- their control files:
- <example compact="compact">
-Provides: mail-transport-agent
-Conflicts: mail-transport-agent
-Replaces: mail-transport-agent
- </example>
- ensuring that only one MTA can be installed at any one
- time.
- </sect1>
- </sect>
+ When it appears in the <file>.dsc</file> file it is the list
+ of binary packages which a source package can produce. It
+ does not necessarily produce all of these binary packages
+ for every architecture. The source control file doesn't
+ contain details of which architectures are appropriate for
+ which of the binary packages.
+ </p>
- <sect><heading>Relationships between source and binary packages -
- <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
- <tt>Build-Conflicts</tt>, <tt>Build-Conflicts-Indep</tt>
- </heading>
+ <p>
+ When it appears in a <file>.changes</file> file it lists the
+ names of the binary packages actually being uploaded.
+ </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>.
- 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:
+ <p>
+ The syntax is a list of binary packages separated by
+ commas<footnote>
+ A space after each comma is conventional.
+ </footnote>. Currently the packages must be separated using
+ only spaces in the <file>.changes</file> file.
+ </p>
+ </sect1>
- <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>
- </item>
- <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>
- </item>
- </taglist>
+ <sect1 id="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>
- </sect>
- </chapt>
+ <p>
+ The disk space is represented in kilobytes as a simple
+ decimal number.
+ </p>
+ </sect1>
+ <sect1 id="f-Files">
+ <heading><tt>Files</tt></heading>
- <chapt id="conffiles"><heading>Configuration file handling
- </heading>
+ <p>
+ This field contains a list of files with information about
+ each one. The exact information and syntax varies with
+ the context. In all cases the part of the field
+ contents on the same line as the field name is empty. The
+ remainder of the field is one line per file, each line
+ being indented by one space and containing a number of
+ sub-fields separated by spaces.
+ </p>
- <p>
- This chapter has been superseded by <ref id="config-files">.
- </p>
+ <p>
+ In the <file>.dsc</file> file, each line contains the MD5
+ checksum, size and filename of the tar file and (if applicable)
+ diff file which make up the remainder of the source
+ package<footnote>
+ 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>
+ 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 <qref id="f-Section">section</qref>
+ and <qref id="f-Priority">priority</qref>
+ are the values of the corresponding fields in
+ the main source control file. If no section or priority is
+ specified then <tt>-</tt> should be used, though section
+ and priority values must be specified for new packages to
+ be installed properly.
+ </p>
- <chapt id="sharedlibs"><heading>Shared libraries</heading>
+ <p>
+ The special value <tt>byhand</tt> for the section in a
+ <tt>.changes</tt> file indicates that the file in question
+ is not an ordinary package file and must by installed by
+ hand by the distribution maintainers. If the section is
+ <tt>byhand</tt> the priority should be <tt>-</tt>.
+ </p>
- <p>
- Packages containing shared libraries must be constructed with
- a little care to make sure that the shared library is always
- available. This is especially important for packages whose
- shared libraries are vitally important, such as the C library
- (currently <tt>libc6</tt>).
- </p>
+ <p>
+ If a new Debian revision of a package is being shipped and
+ no new original source archive is being distributed the
+ <tt>.dsc</tt> must still contain the <tt>Files</tt> field
+ entry for the original source archive
+ <file><var>package</var>-<var>upstream-version</var>.orig.tar.gz</file>,
+ but the <file>.changes</file> file should leave it out. In
+ this case the original source archive on the distribution
+ site must match exactly, byte-for-byte, the original
+ source archive which was used to generate the
+ <file>.dsc</file> file and diff which are being uploaded.</p>
+ </sect1>
- <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
- <file>/usr/lib/libgdbm.so.1.7.3</file>. The files should not be
- renamed or re-linked by any <prgn>prerm</prgn> or
- <prgn>postrm</prgn> scripts; <prgn>dpkg</prgn> will take care
- of renaming things safely without affecting running programs,
- and attempts to interfere with this are likely to lead to
- problems.
- </p>
+ <sect1 id="f-Closes">
+ <heading><tt>Closes</tt></heading>
- <p>
- Secondly, the package should include the symbolic link that
- <prgn>ldconfig</prgn> would create for the shared libraries.
- For example, the <prgn>libgdbmg1</prgn> package should include
- a symbolic link from <file>/usr/lib/libgdbm.so.1</file> to
- <file>libgdbm.so.1.7.3</file>. This is needed so that the dynamic
- linker (for example <prgn>ld.so</prgn> or
- <prgn>ld-linux.so.*</prgn>) can find the library between the
- time that <prgn>dpkg</prgn> installs it and the time that
- <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
- <prgn>dpkg</prgn> comes to install the symlink
- (overwriting the previous symlink pointing at an older
- version of the library), the new shared library is already
- in place. In the past, this was achieved by creating the
- library in the temporary packaging directory before
- creating the symlink. Unfortunately, this was not always
- effective, since the building of the tar file in the
- <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.
- Starting with release <tt>1.7.0</tt>, <prgn>dpkg</prgn>
- will reorder the files itself as necessary when building a
- package. Thus it is no longer important to concern
- oneself with the order of file creation.
+ A space-separated list of bug report numbers that the upload
+ governed by the .changes file closes.
</p>
- </footnote>
- </p>
+ </sect1>
- <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="f-Homepage">
+ <heading><tt>Homepage</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>
- 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>
- </list>
+ The URL of the web site for this package, preferably (when
+ applicable) the site from which the original source can be
+ obtained and any additional upstream documentation or
+ information may be found. The content of this field is a
+ simple URL without any surrounding characters such as
+ <tt><></tt>.
</p>
- </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>.
- </p>
+ </sect1>
- <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!
- </p>
+ </sect>
<sect>
- <heading>Handling shared library dependencies - the
- <tt>shlibs</tt> system</heading>
+ <heading>User-defined fields</heading>
<p>
- If a package contains a binary or library which links to a
- shared library, we must ensure that when the package is
- installed on the system, all of the libraries needed are
- also installed. This requirement led to the creation of the
- <tt>shlibs</tt> system, which is very simple in its design:
- any package which <em>provides</em> a shared library also
- provides information on the package dependencies required to
- ensure the presence of this library, and any package which
- <em>uses</em> a shared library uses this information to
- determine the dependencies it requires. The files which
- contain the mapping from shared libraries to the necessary
- dependency information are called <file>shlibs</file> files.
+ 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>
- Thus, when a package is built which contains any shared
- libraries, it must provide a <file>shlibs</file> file for other
- packages to use, and when a package is built which contains
- any shared libraries or compiled binaries, it must run
- <prgn>dpkg-shlibdeps</prgn> on these to determine the
- libraries used and hence the dependencies needed by this
- package.<footnote>
- <p>
- In the past, the shared libraries linked to were
- determined by calling <prgn>ldd</prgn>, but now
- <prgn>objdump</prgn> is used to do this. The only
- change this makes to package building is that
- <prgn>dpkg-shlibdeps</prgn> must also be run on shared
- libraries, whereas in the past this was unnecessary.
- The rest of this footnote explains the advantage that
- this method gives.
- </p>
-
- <p>
- We say that a binary <tt>foo</tt> <em>directly</em> uses
- a library <tt>libbar</tt> if it is explicitly linked
- with that library (that is, it uses the flag
- <tt>-lbar</tt> during the linking stage). Other
- libraries that are needed by <tt>libbar</tt> are linked
- <em>indirectly</em> to <tt>foo</tt>, and the dynamic
- linker will load them automatically when it loads
- <tt>libbar</tt>. A package should depend on
- the libraries it directly uses, and the dependencies for
- those libraries should automatically pull in the other
- libraries.
- </p>
-
- <p>
- Unfortunately, the <prgn>ldd</prgn> program shows both
- the directly and indirectly used libraries, meaning that
- the dependencies determined included both direct and
- indirect dependencies. The use of <prgn>objdump</prgn>
- avoids this problem by determining only the directly
- used libraries.
- </p>
+ If you wish to add additional unsupported fields to
+ these output files you should use the mechanism
+ described here.
+ </p>
- <p>
- A good example of where this helps is the following. We
- could update <tt>libimlib</tt> with a new version that
- supports a new graphics format called dgf (but retaining
- the same major version number). If we used the old
- <prgn>ldd</prgn> method, every package that uses
- <tt>libimlib</tt> would need to be recompiled so it
- would also depend on <tt>libdgf</tt> or it wouldn't run
- due to missing symbols. However with the new system,
- packages using <tt>libimlib</tt> can rely on
- <tt>libimlib</tt> itself having the dependency on
- <tt>libdgf</tt> and so they would not need rebuilding.
- </p>
- </footnote>
+ <p>
+ Fields in the main source control information file with
+ names starting <tt>X</tt>, followed by one or more of
+ the letters <tt>BCS</tt> and a hyphen <tt>-</tt>, will
+ be copied to the output files. Only the part of the
+ field name after the hyphen will be used in the output
+ file. Where the letter <tt>B</tt> is used the field
+ will appear in binary package control files, where the
+ letter <tt>S</tt> is used in source package control
+ files and where <tt>C</tt> is used in upload control
+ (<tt>.changes</tt>) files.
</p>
<p>
- In the following sections, we will first describe where the
- various <tt>shlibs</tt> files are to be found, then how to
- use <prgn>dpkg-shlibdeps</prgn>, and finally the
- <tt>shlibs</tt> file format and how to create them if your
- package contains a shared library.
+ For example, if the main source information control file
+ contains the field
+ <example>
+ XBS-Comment: I stand between the candle and the star.
+ </example>
+ then the binary and source package control files will contain the
+ field
+ <example>
+ Comment: I stand between the candle and the star.
+ </example>
</p>
+
</sect>
- <sect><heading>The <tt>shlibs</tt> files present on the system
- </heading>
+ </chapt>
+
+
+ <chapt id="maintainerscripts">
+ <heading>Package maintainer scripts and installation procedure</heading>
+
+ <sect>
+ <heading>Introduction to package maintainer scripts</heading>
<p>
- There are several places where <tt>shlibs</tt> files are
- found. The following list gives them in the order in which
- they are read by <prgn>dpkg-shlibdeps</prgn>. (The first
- one which gives the required information is used.)
+ It is possible to supply scripts as part of a package which
+ the package management system will run for you when your
+ package is installed, upgraded or removed.
</p>
<p>
- <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">).
- </p>
- </item>
+ These scripts are the files <prgn>preinst</prgn>,
+ <prgn>postinst</prgn>, <prgn>prerm</prgn> and
+ <prgn>postrm</prgn> in the control area of the package.
+ They must be proper executable files; if they are scripts
+ (which is recommended), they must start with the usual
+ <tt>#!</tt> convention. They should be readable and
+ executable by anyone, and must not be world-writable.
+ </p>
- <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
- administrator.
- </p>
- </item>
+ <p>
+ The package management system looks at the exit status from
+ these scripts. It is important that they exit with a
+ non-zero status if there is an error, so that the package
+ management system can stop its processing. For shell
+ scripts this means that you <em>almost always</em> need to
+ use <tt>set -e</tt> (this is usually true when writing shell
+ scripts, in fact). It is also important, of course, that
+ they don't exit with a non-zero status if everything went
+ well.
+ </p>
- <item>
- <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
- control file area of the temporary build directory and
- 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
- <tt>foo-runtime</tt>. When building the binary
- packages, the two packages are created in the
- directories <file>debian/libfoo2</file> and
- <file>debian/foo-runtime</file> respectively.
- (<file>debian/tmp</file> could be used instead of one
- of these.) Since <tt>libfoo2</tt> provides the
- <tt>libfoo</tt> shared library, it will require a
- <tt>shlibs</tt> file, which will be installed in
- <file>debian/libfoo2/DEBIAN/shlibs</file>, eventually
- to become
- <file>/var/lib/dpkg/info/libfoo2.shlibs</file>. Then
- when <prgn>dpkg-shlibdeps</prgn> is run on the
- executable
- <file>debian/foo-runtime/usr/bin/foo-prog</file>, it
- will examine the
- <file>debian/libfoo2/DEBIAN/shlibs</file> file to
- determine whether <tt>foo-prog</tt>'s library
- dependencies are satisfied by any of the libraries
- provided by <tt>libfoo2</tt>. For this reason,
- <prgn>dpkg-shlibdeps</prgn> must only be run once
- all of the individual binary packages'
- <tt>shlibs</tt> files have been installed into the
- build directory.
- </p>
- </footnote>
- </p>
- </item>
+ <p>
+ Additionally, packages interacting with users using
+ <tt>debconf</tt> in the <prgn>postinst</prgn> script should
+ install a <prgn>config</prgn> script in the control area,
+ see <ref id="maintscriptprompt"> for details.
+ </p>
- <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
- maintained by the relevant package maintainers.
- </p>
- </item>
+ <p>
+ When a package is upgraded a combination of the scripts from
+ the old and new packages is called during the upgrade
+ procedure. If your scripts are going to be at all
+ complicated you need to be aware of this, and may need to
+ check the arguments to your scripts.
+ </p>
- <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.
- It was used when the <file>shlibs</file> setup was first
- introduced, but it is now normally empty. It is
- maintained by the <tt>dpkg</tt> maintainer.
- </p>
- </item>
- </list>
+ <p>
+ Broadly speaking the <prgn>preinst</prgn> is called before
+ (a particular version of) a package is installed, and the
+ <prgn>postinst</prgn> afterwards; the <prgn>prerm</prgn>
+ before (a version of) a package is removed and the
+ <prgn>postrm</prgn> afterwards.
</p>
+
+ <p>
+ Programs called from maintainer scripts should not normally
+ have a path prepended to them. Before installation is
+ started, the package management system checks to see if the
+ programs <prgn>ldconfig</prgn>,
+ <prgn>start-stop-daemon</prgn>, <prgn>install-info</prgn>,
+ and <prgn>update-rc.d</prgn> can be found via the
+ <tt>PATH</tt> environment variable. Those programs, and any
+ other program that one would expect to be in the
+ <tt>PATH</tt>, should thus be invoked without an absolute
+ pathname. Maintainer scripts should also not reset the
+ <tt>PATH</tt>, though they might choose to modify it by
+ prepending or appending package-specific directories. These
+ considerations really apply to all shell scripts.</p>
</sect>
- <sect>
- <heading>How to use <prgn>dpkg-shlibdeps</prgn> and the
- <file>shlibs</file> files</heading>
+ <sect id="idempotency">
+ <heading>Maintainer scripts idempotency</heading>
<p>
- Put a call to <prgn>dpkg-shlibdeps</prgn> into your
- <file>debian/rules</file> file. If your package contains only
- compiled binaries and libraries (but no scripts), you can
- use a command such as:
- <example compact="compact">
-dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* \
- debian/tmp/usr/lib/*
- </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>
+ It is necessary for the error recovery procedures that the
+ scripts be idempotent. This means that if it is run
+ successfully, and then it is called again, it doesn't bomb
+ out or cause any harm, but just ensures that everything is
+ the way it ought to be. If the first call failed, or
+ 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>
+ 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.
</footnote>
</p>
+ </sect>
- <p>
- This command puts the dependency information into the
- <file>debian/substvars</file> file, which is then used by
- <prgn>dpkg-gencontrol</prgn>. You will need to place a
- <tt>${shlib:Depends}</tt> variable in the <tt>Depends</tt>
- field in the control file for this to work.
- </p>
+ <sect id="controllingterminal">
+ <heading>Controlling terminal for maintainer scripts</heading>
<p>
- If <prgn>dpkg-shlibdeps</prgn> doesn't complain, you're
- done. If it does complain you might need to create your own
- <file>debian/shlibs.local</file> file, as explained below (see
- <ref id="shlibslocal">).
+ The maintainer scripts are guaranteed to run with a
+ controlling terminal and can interact with the user.
+ Because these scripts may be executed with standard output
+ redirected into a pipe for logging purposes, Perl scripts
+ should set unbuffered output by setting <tt>$|=1</tt> so
+ that the output is printed immediately rather than being
+ buffered.
</p>
+ </sect>
+ <sect id="exitstatus">
+ <heading>Exit status</heading>
<p>
- If you have multiple binary packages, you will need to call
- <prgn>dpkg-shlibdeps</prgn> on each one which contains
- compiled libraries or binaries. In such a case, you will
- need to use the <tt>-T</tt> option to the <tt>dpkg</tt>
- utilities to specify a different <file>substvars</file> file.
- For more details on this and other options, see <manref
- name="dpkg-shlibdeps" section="1">.
+ Each script must return a zero exit status for
+ success, or a nonzero one for failure, since the package
+ management system looks for the exit status of these scripts
+ and determines what action to take next based on that datum.
</p>
</sect>
- <sect id="shlibs"><heading>The <file>shlibs</file> File Format
+ <sect id="mscriptsinstact"><heading>Summary of ways maintainer
+ scripts are called
</heading>
<p>
- Each <file>shlibs</file> file has the same format. Lines
- beginning with <tt>#</tt> are considered to be comments and
- are ignored. Each line is of the form:
- <example compact="compact">
-<var>library-name</var> <var>soname-version-number</var> <var>dependencies ...</var>
- </example>
- </p>
+ <list compact="compact">
+ <item>
+ <var>new-preinst</var> <tt>install</tt>
+ </item>
+ <item>
+ <var>new-preinst</var> <tt>install</tt> <var>old-version</var>
+ </item>
+ <item>
+ <var>new-preinst</var> <tt>upgrade</tt> <var>old-version</var>
+ </item>
+ <item>
+ <var>old-preinst</var> <tt>abort-upgrade</tt>
+ <var>new-version</var>
+ </item>
+ </list>
<p>
- We will explain this by reference to the example of the
- <tt>zlib1g</tt> package, which (at the time of writing)
- installs the shared library <file>/usr/lib/libz.so.1.1.3</file>.
- </p>
+ <list compact="compact">
+ <item>
+ <var>postinst</var> <tt>configure</tt>
+ <var>most-recently-configured-version</var>
+ </item>
+ <item>
+ <var>old-postinst</var> <tt>abort-upgrade</tt>
+ <var>new-version</var>
+ </item>
+ <item>
+ <var>conflictor's-postinst</var> <tt>abort-remove</tt>
+ <tt>in-favour</tt> <var>package</var>
+ <var>new-version</var>
+ </item>
+ <item>
+ <var>postinst</var> <tt>abort-remove</tt>
+ </item>
+ <item>
+ <var>deconfigured's-postinst</var>
+ <tt>abort-deconfigure</tt> <tt>in-favour</tt>
+ <var>failed-install-package</var> <var>version</var>
+ [<tt>removing</tt> <var>conflicting-package</var>
+ <var>version</var>]
+ </item>
+ </list>
<p>
- <var>library-name</var> is the name of the shared library,
- in this case <tt>libz</tt>. (This must match the name part
- of the soname, see below.)
- </p>
+ <list compact="compact">
+ <item>
+ <var>prerm</var> <tt>remove</tt>
+ </item>
+ <item>
+ <var>old-prerm</var> <tt>upgrade</tt>
+ <var>new-version</var>
+ </item>
+ <item>
+ <var>new-prerm</var> <tt>failed-upgrade</tt>
+ <var>old-version</var>
+ </item>
+ <item>
+ <var>conflictor's-prerm</var> <tt>remove</tt>
+ <tt>in-favour</tt> <var>package</var>
+ <var>new-version</var>
+ </item>
+ <item>
+ <var>deconfigured's-prerm</var> <tt>deconfigure</tt>
+ <tt>in-favour</tt> <var>package-being-installed</var>
+ <var>version</var> [<tt>removing</tt>
+ <var>conflicting-package</var>
+ <var>version</var>]
+ </item>
+ </list>
<p>
- <var>soname-version-number</var> is the version part of the
- soname of the library. The soname is the thing that must
- exactly match for the library to be recognized by the
- dynamic linker, and is usually of the form
- <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>.
+ <list compact="compact">
+ <item>
+ <var>postrm</var> <tt>remove</tt>
+ </item>
+ <item>
+ <var>postrm</var> <tt>purge</tt>
+ </item>
+ <item>
+ <var>old-postrm</var> <tt>upgrade</tt>
+ <var>new-version</var>
+ </item>
+ <item>
+ <var>new-postrm</var> <tt>failed-upgrade</tt>
+ <var>old-version</var>
+ </item>
+ <item>
+ <var>new-postrm</var> <tt>abort-install</tt>
+ </item>
+ <item>
+ <var>new-postrm</var> <tt>abort-install</tt>
+ <var>old-version</var>
+ </item>
+ <item>
+ <var>new-postrm</var> <tt>abort-upgrade</tt>
+ <var>old-version</var>
+ </item>
+ <item>
+ <var>disappearer's-postrm</var> <tt>disappear</tt>
+ <var>overwriter</var>
+ <var>overwriter-version</var>
+ </item>
+ </list>
+ </p>
+
+
+ <sect id="unpackphase">
+ <heading>Details of unpack phase of installation or upgrade</heading>
+
+ <p>
+ The procedure on installation/upgrade/overwrite/disappear
+ (i.e., when running <tt>dpkg --unpack</tt>, or the unpack
+ stage of <tt>dpkg --install</tt>) is as follows. In each
+ 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
+ below.
+
+ <enumlist>
+ <item>
+ <enumlist>
+ <item>
+ If a version of the package is already installed, call
+ <example compact="compact">
+<var>old-prerm</var> upgrade <var>new-version</var>
+ </example>
+ </item>
+ <item>
+ If the script runs but exits with a non-zero
+ exit status, <prgn>dpkg</prgn> will attempt:
+ <example compact="compact">
+<var>new-prerm</var> failed-upgrade <var>old-version</var>
+ </example>
+ If this works, the upgrade continues. If this
+ does not work, the error unwind:
+ <example compact="compact">
+<var>old-postinst</var> abort-upgrade <var>new-version</var>
+ </example>
+ If this works, then the old-version is
+ "Installed", if not, the old version is in a
+ "Failed-Config" state.
+ </item>
+ </enumlist>
+ </item>
+
+ <item>
+ If a "conflicting" package is being removed at the same time,
+ or if any package will be broken (due to <tt>Breaks</tt>):
+ <enumlist>
+ <item>
+ If <tt>--auto-deconfigure</tt> is
+ specified, call, for each package to be deconfigured
+ due to <tt>Breaks</tt>:
+ <example compact="compact">
+<var>deconfigured's-prerm</var> deconfigure \
+ in-favour <var>package-being-installed</var> <var>version</var>
+ </example>
+ Error unwind:
+ <example compact="compact">
+<var>deconfigured's-postinst</var> abort-deconfigure \
+ in-favour <var>package-being-installed-but-failed</var> <var>version</var>
+ </example>
+ The deconfigured packages are marked as
+ requiring configuration, so that if
+ <tt>--install</tt> is used they will be
+ configured again if possible.
+ </item>
+ <item>
+ If any packages depended on a conflicting
+ package being removed and <tt>--auto-deconfigure</tt> is
+ specified, call, for each such package:
+ <example compact="compact">
+<var>deconfigured's-prerm</var> deconfigure \
+ in-favour <var>package-being-installed</var> <var>version</var> \
+ removing <var>conflicting-package</var> <var>version</var>
+ </example>
+ Error unwind:
+ <example compact="compact">
+<var>deconfigured's-postinst</var> abort-deconfigure \
+ in-favour <var>package-being-installed-but-failed</var> <var>version</var> \
+ removing <var>conflicting-package</var> <var>version</var>
+ </example>
+ The deconfigured packages are marked as
+ requiring configuration, so that if
+ <tt>--install</tt> is used they will be
+ configured again if possible.
+ </item>
+ <item>
+ To prepare for removal of each conflicting package, call:
+ <example compact="compact">
+<var>conflictor's-prerm</var> remove \
+ in-favour <var>package</var> <var>new-version</var>
+ </example>
+ Error unwind:
+ <example compact="compact">
+<var>conflictor's-postinst</var> abort-remove \
+ in-favour <var>package</var> <var>new-version</var>
+ </example>
+ </item>
+ </enumlist>
+ </item>
+
+ <item>
+ <enumlist>
+ <item>
+ If the package is being upgraded, call:
+ <example compact="compact">
+<var>new-preinst</var> upgrade <var>old-version</var>
+ </example>
+ If this fails, we call:
+ <example>
+<var>new-postrm</var> abort-upgrade <var>old-version</var>
+ </example>
+ <enumlist>
+ <item>
+ <p>
+ If that works, then
+ <example>
+<var>old-postinst</var> abort-upgrade <var>new-version</var>
+ </example>
+ is called. If this works, then the old version
+ is in an "Installed" state, or else it is left
+ in an "Unpacked" state.
+ </p>
+ </item>
+ <item>
+ <p>
+ If it fails, then the old version is left
+ in an "Half-Installed" state.
+ </p>
+ </item>
+ </enumlist>
+
+ </item>
+ <item>
+ Otherwise, if the package had some configuration
+ files from a previous version installed (i.e., it
+ is in the "configuration files only" state):
+ <example compact="compact">
+<var>new-preinst</var> install <var>old-version</var>
+ </example>
+ Error unwind:
+ <example>
+<var>new-postrm</var> abort-install <var>old-version</var>
+ </example>
+ If this fails, the package is left in a
+ "Half-Installed" state, which requires a
+ reinstall. If it works, the packages is left in
+ a "Config Files" state.
+ </item>
+ <item>
+ Otherwise (i.e., the package was completely purged):
+ <example compact="compact">
+<var>new-preinst</var> install
+ </example>
+ Error unwind:
+ <example compact="compact">
+<var>new-postrm</var> abort-install
+ </example>
+ If the error-unwind fails, the package is in a
+ "Half Installed" phase, and requires a
+ reinstall. If the error unwind works, the
+ package is in a not installed state.
+ </item>
+ </enumlist>
+ </item>
+
+ <item>
+ <p>
+ The new package's files are unpacked, overwriting any
+ that may be on the system already, for example any
+ from the old version of the same package or from
+ another package. Backups of the old files are kept
+ temporarily, and if anything goes wrong the package
+ management system will attempt to put them back as
+ part of the error unwind.
+ </p>
+
+ <p>
+ It is an error for a package to contain files which
+ are on the system in another package, unless
+ <tt>Replaces</tt> is used (see <ref id="replaces">).
+ <!--
+ The following paragraph is not currently the case:
+ Currently the <tt>- - force-overwrite</tt> flag is
+ enabled, downgrading it to a warning, but this may not
+ always be the case.
+ -->
+ </p>
+
+ <p>
+ It is a more serious error for a package to contain a
+ plain file or other kind of non-directory where another
+ package has a directory (again, unless
+ <tt>Replaces</tt> is used). This error can be
+ overridden if desired using
+ <tt>--force-overwrite-dir</tt>, but this is not
+ advisable.
+ </p>
+
+ <p>
+ Packages which overwrite each other's files produce
+ behavior which, though deterministic, is hard for the
+ system administrator to understand. It can easily
+ lead to "missing" programs if, for example, a package
+ is installed which overwrites a file from another
+ package, and is then removed again.<footnote>
+ Part of the problem is due to what is arguably a
+ bug in <prgn>dpkg</prgn>.
+ </footnote>
+ </p>
+
+ <p>
+ A directory will never be replaced by a symbolic link
+ 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>
+ </item>
+
+ <item>
+ <p>
+ <enumlist>
+ <item>
+ If the package is being upgraded, call
+ <example compact="compact">
+<var>old-postrm</var> upgrade <var>new-version</var>
+ </example>
+ </item>
+ <item>
+ If this fails, <prgn>dpkg</prgn> will attempt:
+ <example compact="compact">
+<var>new-postrm</var> failed-upgrade <var>old-version</var>
+ </example>
+ If this works, installation continues. If not,
+ Error unwind:
+ <example compact="compact">
+<var>old-preinst</var> abort-upgrade <var>new-version</var>
+ </example>
+ If this fails, the old version is left in an
+ "Half Installed" state. If it works, dpkg now
+ calls:
+ <example compact="compact">
+<var>new-postrm</var> abort-upgrade <var>old-version</var>
+ </example>
+ If this fails, the old version is left in an
+ "Half Installed" state. If it works, dpkg now
+ calls:
+ <example compact="compact">
+<var>old-postinst</var> abort-upgrade <var>new-version</var>
+ </example>
+ If this fails, the old version is in an
+ "Unpacked" state.
+ </item>
+ </enumlist>
+ </p>
+
+ <p>
+ This is the point of no return - if
+ <prgn>dpkg</prgn> gets this far, it won't back off
+ past this point if an error occurs. This will
+ leave the package in a fairly bad state, which
+ will require a successful re-installation to clear
+ up, but it's when <prgn>dpkg</prgn> starts doing
+ things that are irreversible.
+ </p>
+ </item>
+
+ <item>
+ Any files which were in the old version of the package
+ but not in the new are removed.
+ </item>
+
+ <item>
+ The new file list replaces the old.
+ </item>
+
+ <item>
+ The new maintainer scripts replace the old.
+ </item>
+
+ <item>
+ 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>
+ <prgn>dpkg</prgn> calls:
+ <example compact="compact">
+<var>disappearer's-postrm</var> disappear \
+ <var>overwriter</var> <var>overwriter-version</var>
+ </example>
+ </item>
+ <item>
+ The package's maintainer scripts are removed.
+ </item>
+ <item>
+ 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
+ removed by <prgn>dpkg</prgn>). Note that
+ disappearing packages do not have their prerm
+ called, because <prgn>dpkg</prgn> doesn't know
+ in advance that the package is going to
+ vanish.
+ </item>
+ </enumlist>
+ </item>
+
+ <item>
+ 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.)
+ </item>
+
+ <item>
+ The backup files made during installation, above, are
+ deleted.
+ </item>
+
+ <item>
+ <p>
+ The new package's status is now sane, and recorded as
+ "unpacked".
+ </p>
+
+ <p>
+ Here is another point of no return - if the
+ conflicting package's removal fails we do not unwind
+ the rest of the installation; the conflicting package
+ is left in a half-removed limbo.
+ </p>
+ </item>
+
+ <item>
+ 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).
+ </item>
+ </enumlist>
+ </p>
+ </sect>
+
+ <sect id="configdetails"><heading>Details of configuration</heading>
+
+ <p>
+ When we configure a package (this happens with <tt>dpkg
+ --install</tt> and <tt>dpkg --configure</tt>), we first
+ update any <tt>conffile</tt>s and then call:
+ <example compact="compact">
+<var>postinst</var> configure <var>most-recently-configured-version</var>
+ </example>
+ </p>
+
+ <p>
+ No attempt is made to unwind after errors during
+ configuration. If the configuration fails, the package is in
+ a "Failed Config" state, and an error message is generated.
+ </p>
+
+ <p>
+ If there is no most recently configured version
+ <prgn>dpkg</prgn> will pass a null argument.
+ <footnote>
+ <p>
+ Historical note: Truly ancient (pre-1997) versions of
+ <prgn>dpkg</prgn> passed <tt><unknown></tt>
+ (including the angle brackets) in this case. Even older
+ ones did not pass a second argument at all, under any
+ circumstance. Note that upgrades using such an old dpkg
+ version are unlikely to work for other reasons, even if
+ this old argument behavior is handled by your postinst script.
+ </p>
+ </footnote>
+ </p>
+ </sect>
+
+ <sect id="removedetails"><heading>Details of removal and/or
+ configuration purging</heading>
+
+ <p>
+ <enumlist>
+ <item>
+ <p>
+ <example compact="compact">
+<var>prerm</var> remove
+ </example>
+ </p>
+ <p>
+ If prerm fails during replacement due to conflict
+ <example>
+<var>conflictor's-postinst</var> abort-remove \
+ in-favour <var>package</var> <var>new-version</var>
+ </example>
+ Or else we call:
+ <example>
+<var>postinst</var> abort-remove
+ </example>
+ </p>
+ <p>
+ If this fails, the package is in a "Failed-Config"
+ state, or else it remains "Installed".
+ </p>
+ </item>
+ <item>
+ The package's files are removed (except <tt>conffile</tt>s).
+ </item>
+ <item>
+ <example compact="compact">
+<var>postrm</var> remove
+ </example>
+
+ <p>
+ If it fails, there's no error unwind, and the package is in
+ an "Half-Installed" state.
+ </p>
+ </item>
+ <item>
+ <p>
+ All the maintainer scripts except the <prgn>postrm</prgn>
+ are removed.
+ </p>
+
+ <p>
+ If we aren't purging the package we stop here. Note
+ 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>
+ </item>
+ <item>
+ 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.
+ </item>
+ <item>
+ <p>
+ <example compact="compact">
+<var>postrm</var> purge
+ </example>
+ </p>
+ <p>
+ If this fails, the package remains in a "Config-Files"
+ state.
+ </p>
+ </item>
+ <item>
+ The package's file list is removed.
+ </item>
+ </enumlist>
+
+ </p>
+ </sect>
+ </chapt>
+
+
+ <chapt id="relationships">
+ <heading>Declaring relationships between packages</heading>
+
+ <sect id="depsyntax">
+ <heading>Syntax of relationship fields</heading>
+
+ <p>
+ These fields all have a uniform syntax. They are a list of
+ package names separated by commas.
+ </p>
+
+ <p>
+ In the <tt>Depends</tt>, <tt>Recommends</tt>,
+ <tt>Suggests</tt>, <tt>Pre-Depends</tt>,
+ <tt>Build-Depends</tt> and <tt>Build-Depends-Indep</tt>
+ control file fields of the package, which declare
+ dependencies on other packages, the package names listed may
+ also include lists of alternative package names, separated
+ by vertical bar (pipe) symbols <tt>|</tt>. In such a case,
+ if any one of the alternative packages is installed, that
+ part of the dependency is considered to be satisfied.
+ </p>
+
+ <p>
+ All of the fields except for <tt>Provides</tt> may restrict
+ their applicability to particular versions of each named
+ package. This is done in parentheses after each individual
+ package name; the parentheses should contain a relation from
+ the list below followed by a version number, in the format
+ described in <ref id="f-Version">.
+ </p>
+
+ <p>
+ The relations allowed are <tt><<</tt>, <tt><=</tt>,
+ <tt>=</tt>, <tt>>=</tt> and <tt>>></tt> for
+ strictly earlier, earlier or equal, exactly equal, later or
+ equal and strictly later, respectively. The deprecated
+ forms <tt><</tt> and <tt>></tt> were used to mean
+ earlier/later or equal, rather than strictly earlier/later,
+ so they should not appear in new packages (though
+ <prgn>dpkg</prgn> still supports them).
+ </p>
+
+ <p>
+ Whitespace may appear at any point in the version
+ specification subject to the rules in <ref
+ id="controlsyntax">, and must appear where it's necessary to
+ disambiguate; it is not otherwise significant. All of the
+ relationship fields may span multiple lines. For
+ consistency and in case of future changes to
+ <prgn>dpkg</prgn> it is recommended that a single space be
+ used after a version relationship and before a version
+ number; it is also conventional to put a single space after
+ each comma, on either side of each vertical bar, and before
+ each open parenthesis. When wrapping a relationship field, it
+ is conventional to do so after a comma and before the space
+ following that comma.
+ </p>
+
+ <p>
+ For example, a list of dependencies might appear as:
+ <example compact="compact">
+Package: mutt
+Version: 1.3.17-1
+Depends: libc6 (>= 2.2.1), exim | mail-transport-agent
+ </example>
+ </p>
+
+ <p>
+ All fields that specify build-time relationships
+ (<tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
+ <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>)
+ may be restricted to a certain set of architectures. This
+ is indicated in brackets after each individual package name and
+ the optional version specification. The brackets enclose a
+ list of Debian architecture names separated by whitespace.
+ Exclamation marks may be prepended to each of the names.
+ (It is not permitted for some names to be prepended with
+ exclamation marks while others aren't.) If the current Debian
+ host architecture is not in this list and there are no
+ exclamation marks in the list, or it is in the list with a
+ prepended exclamation mark, the package name and the
+ associated version specification are ignored completely for
+ the purposes of defining the relationships.
+ </p>
+
+ <p>
+ For example:
+ <example compact="compact">
+Source: glibc
+Build-Depends-Indep: texinfo
+Build-Depends: kernel-headers-2.2.10 [!hurd-i386],
+ hurd-dev [hurd-i386], gnumach-dev [hurd-i386]
+ </example>
+ </p>
+
+ <p>
+ Note that the binary package relationship fields such as
+ <tt>Depends</tt> appear in one of the binary package
+ sections of the control file, whereas the build-time
+ relationships such as <tt>Build-Depends</tt> appear in the
+ source package section of the control file (which is the
+ first section).
+ </p>
+ </sect>
+
+ <sect id="binarydeps">
+ <heading>Binary Dependencies - <tt>Depends</tt>,
+ <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
+ <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>,
+ <tt>Breaks</tt> and <tt>Conflicts</tt> control file fields.
+ </p>
+
+ <p>
+ These seven fields are used to declare a dependency
+ relationship by one package on another. Except for
+ <tt>Enhances</tt> and <tt>Breaks</tt>, they appear in the
+ depending (binary) package's control file.
+ (<tt>Enhances</tt> appears in the recommending package's
+ control file, and <tt>Breaks</tt> appears in the version of
+ depended-on package which causes the named package to
+ break).
+ </p>
+
+ <p>
+ A <tt>Depends</tt> field takes effect <em>only</em> when a
+ package is to be configured. It does not prevent a package
+ being on the system in an unconfigured state while its
+ dependencies are unsatisfied, and it is possible to replace
+ a package whose dependencies are satisfied and which is
+ properly installed with a different version whose
+ dependencies are not and cannot be satisfied; when this is
+ done the depending package will be left unconfigured (since
+ attempts to configure it will give errors) and will not
+ function properly. If it is necessary, a
+ <tt>Pre-Depends</tt> field can be used, which has a partial
+ effect even when a package is being unpacked, as explained
+ in detail below. (The other three dependency fields,
+ <tt>Recommends</tt>, <tt>Suggests</tt> and
+ <tt>Enhances</tt>, are only used by the various front-ends
+ to <prgn>dpkg</prgn> such as <prgn>apt-get</prgn>,
+ <prgn>aptitude</prgn>, and <prgn>dselect</prgn>.)
+ </p>
+
+ <p>
+ For this reason packages in an installation run are usually
+ all unpacked first and all configured later; this gives
+ later versions of packages with dependencies on later
+ versions of other packages the opportunity to have their
+ dependencies satisfied.
+ </p>
+
+ <p>
+ In case of circular dependencies, since installation or
+ removal order honoring the dependency order can't be
+ established, dependency loops are broken at some point
+ (based on rules below), and some packages may not be able to
+ rely on their dependencies being present when being
+ installed or removed, depending on which side of the break
+ of the circular dependency loop they happen to be on. If one
+ of the packages in the loop has no postinst script, then the
+ cycle will be broken at that package, so as to ensure that
+ all postinst scripts run with the dependencies properly
+ configured if this is possible. Otherwise the breaking point
+ is arbitrary.
+ </p>
+
+ <p>
+ The <tt>Depends</tt> field thus allows package maintainers
+ to impose an order in which packages should be configured.
+ </p>
+
+ <p>
+ The meaning of the five dependency fields is as follows:
+ <taglist>
+ <tag><tt>Depends</tt></tag>
+ <item>
+ <p>
+ This declares an absolute dependency. A package will
+ not be configured unless all of the packages listed in
+ its <tt>Depends</tt> field have been correctly
+ configured.
+ </p>
+
+ <p>
+ The <tt>Depends</tt> field should be used if the
+ depended-on package is required for the depending
+ 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
+ <prgn>postrm</prgn> scripts require the package to be
+ present in order to run. Note, however, that the
+ <prgn>postrm</prgn> cannot rely on any non-essential
+ packages to be present during the <tt>purge</tt>
+ phase.
+ </item>
+
+ <tag><tt>Recommends</tt></tag>
+ <item>
+ <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>
+ </item>
+
+ <tag><tt>Suggests</tt></tag>
+ <item>
+ 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.
+ </item>
+
+ <tag><tt>Enhances</tt></tag>
+ <item>
+ 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.
+ </item>
+
+ <tag><tt>Pre-Depends</tt></tag>
+ <item>
+ <p>
+ This field is like <tt>Depends</tt>, except that it
+ also forces <prgn>dpkg</prgn> to complete installation
+ of the packages named before even starting the
+ installation of the package which declares the
+ pre-dependency, as follows:
+ </p>
+
+ <p>
+ When a package declaring a pre-dependency is about to
+ be <em>unpacked</em> the pre-dependency can be
+ satisfied if the depended-on package is either fully
+ configured, <em>or even if</em> the depended-on
+ package(s) are only unpacked or half-configured,
+ provided that they have been configured correctly at
+ some point in the past (and not removed or partially
+ removed since). In this case, both the
+ previously-configured and currently unpacked or
+ half-configured versions must satisfy any version
+ clause in the <tt>Pre-Depends</tt> field.
+ </p>
+
+ <p>
+ When the package declaring a pre-dependency is about
+ to be <em>configured</em>, the pre-dependency will be
+ treated as a normal <tt>Depends</tt>, that is, it will
+ be considered satisfied only if the depended-on
+ package has been correctly configured.
+ </p>
+
+ <p>
+ <tt>Pre-Depends</tt> should be used sparingly,
+ preferably only by packages whose premature upgrade or
+ installation would hamper the ability of the system to
+ continue with any upgrade that might be in progress.
+ </p>
+
+ <p>
+ <tt>Pre-Depends</tt> are also required if the
+ <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
+ functionality of the one declaring the dependency. Some
+ packages are composed of components of varying degrees of
+ importance. Such a package should list using
+ <tt>Depends</tt> the package(s) which are required by the
+ more important components. The other components'
+ requirements may be mentioned as Suggestions or
+ Recommendations, as appropriate to the components' relative
+ importance.
+ </p>
+ </sect>
+
+ <sect id="breaks">
+ <heading>Packages which break other packages - <tt>Breaks</tt></heading>
+
+ <p>
+ Using <tt>Breaks</tt> may cause problems for upgrades from older
+ versions of Debian and should not be used until the stable
+ release of Debian supports <tt>Breaks</tt>.
+ </p>
+
+ <p>
+ When one binary package declares that it breaks another,
+ <prgn>dpkg</prgn> will refuse to allow the package which
+ declares <tt>Breaks</tt> be installed unless the broken
+ package is deconfigured first, and it will refuse to
+ allow the broken package to be reconfigured.
+ </p>
+
+ <p>
+ A package will not be regarded as causing breakage merely
+ because its configuration files are still installed; it must
+ be at least half-installed.
+ </p>
+
+ <p>
+ A special exception is made for packages which declare that
+ they break their own package name or a virtual package which
+ they provide (see below): this does not count as a real
+ breakage.
+ </p>
+
+ <p>
+ Normally a <tt>Breaks</tt> entry will have an "earlier than"
+ version clause; such a <tt>Breaks</tt> is introduced in the
+ version of an (implicit or explicit) dependency which
+ violates an assumption or reveals a bug in earlier versions
+ of the broken package. This use of <tt>Breaks</tt> will
+ inform higher-level package management tools that broken
+ package must be upgraded before the new one.
+ </p>
+
+ <p>
+ If the breaking package also overwrites some files from the
+ older package, it should use <tt>Replaces</tt> (not
+ <tt>Conflicts</tt>) to ensure this goes smoothly.
+ </p>
+ </sect>
+
+ <sect id="conflicts">
+ <heading>Conflicting binary packages - <tt>Conflicts</tt></heading>
+
+ <p>
+ When one binary package declares a conflict with another
+ using a <tt>Conflicts</tt> field, <prgn>dpkg</prgn> will
+ refuse to allow them to be installed on the system at the
+ same time.
+ </p>
+
+ <p>
+ If one package is to be installed, the other must be removed
+ first - if the package being installed is marked as
+ replacing (see <ref id="replaces">) the one on the system,
+ or the one on the system is marked as deselected, or both
+ packages are marked <tt>Essential</tt>, then
+ <prgn>dpkg</prgn> will automatically remove the package
+ which is causing the conflict, otherwise it will halt the
+ installation of the new package with an error. This
+ mechanism is specifically designed to produce an error when
+ the installed package is <tt>Essential</tt>, but the new
+ package is not.
+ </p>
+
+ <p>
+ A package will not cause a conflict merely because its
+ configuration files are still installed; it must be at least
+ half-installed.
+ </p>
+
+ <p>
+ A special exception is made for packages which declare a
+ conflict with their own package name, or with a virtual
+ package which they provide (see below): this does not
+ prevent their installation, and allows a package to conflict
+ with others providing a replacement for it. You use this
+ feature when you want the package in question to be the only
+ package providing some feature.
+ </p>
+
+ <p>
+ A <tt>Conflicts</tt> entry should almost never have an
+ "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. Instead,
+ <tt>Breaks</tt> may be used (once <tt>Breaks</tt> is supported
+ by the stable release of Debian).
+ </p>
+ </sect>
+
+ <sect id="virtual"><heading>Virtual packages - <tt>Provides</tt>
+ </heading>
+
+ <p>
+ 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>Breaks</tt>, <tt>Conflicts</tt>,
+ <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
+ <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>
+ may mention "virtual packages".
+ </p>
+
+ <p>
+ A <em>virtual package</em> is one which appears in the
+ <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. (See also <ref
+ id="virtual_pkg">)
+ </p>
+
+ <p>
+ 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
+ </example> and someone else releases an enhanced version of
+ the <tt>bar</tt> package they can say:
+ <example compact="compact">
+Package: bar-plus
+Provides: bar
+ </example>
+ and the <tt>bar-plus</tt> package will now also satisfy the
+ dependency for the <tt>foo</tt> package.
+ </p>
+
+ <p>
+ If a relationship field has a version number attached
+ then only real packages will be considered to see whether
+ the relationship is satisfied (or the prohibition violated,
+ for a conflict or breakage) - it is assumed that a real
+ package which provides the virtual package is not of the
+ "right" version. So, a <tt>Provides</tt> field may not
+ contain version numbers, and the version number of the
+ concrete package which provides a particular virtual package
+ will not be looked at when considering a dependency on or
+ conflict with the virtual package name.
+ </p>
+
+ <p>
+ It is likely that the ability will be added in a future
+ release of <prgn>dpkg</prgn> to specify a version number for
+ each virtual package it provides. This feature is not yet
+ present, however, and is expected to be used only
+ infrequently.
+ </p>
+
+ <p>
+ If you want to specify which of a set of real packages
+ should be the default to satisfy a particular dependency on
+ a virtual package, you should list the real package as an
+ alternative before the virtual one.
+ </p>
+ </sect>
+
+
+ <sect id="replaces"><heading>Overwriting files and replacing
+ packages - <tt>Replaces</tt></heading>
+
+ <p>
+ 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>
+
+ <p>
+ Firstly, as mentioned before, it is usually an error for a
+ package to contain files which are on the system in
+ another package.
+ </p>
+
+ <p>
+ However, if the overwriting package declares that it
+ <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.
+ </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
+ 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
+ will have been taken over by the overwriting package. The
+ package's <prgn>postrm</prgn> script will be run with a
+ special argument to allow the package to do any final
+ cleanup required. See <ref id="mscriptsinstact">.
+ <footnote>
+ <p>
+ Replaces is a one way relationship -- you have to
+ install the replacing package after the replaced
+ package.
+ </p>
+ </footnote>
+ </p>
+
+ <p>
+ For this usage of <tt>Replaces</tt>, virtual packages (see
+ <ref id="virtual">) are not considered when looking at a
+ <tt>Replaces</tt> field - the packages declared as being
+ replaced must be mentioned by their real names.
+ </p>
+
+ <p>
+ Furthermore, this usage of <tt>Replaces</tt> only takes
+ effect when both packages are at least partially on the
+ system at once, so that it can only happen if they do not
+ conflict or if the conflict has been overridden.
+ </p>
+
+ </sect1>
+
+ <sect1><heading>Replacing whole packages, forcing their
+ removal</heading>
+
+ <p>
+ Secondly, <tt>Replaces</tt> allows the packaging system to
+ resolve which package should be removed when there is a
+ conflict - see <ref id="conflicts">. This usage only
+ takes effect when the two packages <em>do</em> conflict,
+ so that the two usages of this field do not interfere with
+ each other.
+ </p>
+
+ <p>
+ In this situation, the package declared as being replaced
+ can be a virtual package, so for example, all mail
+ transport agents (MTAs) would have the following fields in
+ their control files:
+ <example compact="compact">
+Provides: mail-transport-agent
+Conflicts: mail-transport-agent
+Replaces: mail-transport-agent
+ </example>
+ ensuring that only one MTA can be installed at any one
+ time.
+ </sect1>
+ </sect>
+
+ <sect id="sourcebinarydeps">
+ <heading>Relationships between source and binary packages -
+ <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
+ <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>
+ 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:<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; this role is essentially
+ met with Build-Depends. Anyone building the
+ <tt>build-indep</tt> and binary-indep<tt></tt> targets
+ is basically assumed to be building the whole package
+ anyway and so installs all build dependencies. The
+ autobuilders use <tt>dpkg-buildpackage -B</tt>, which
+ calls <tt>build</tt> (not <tt>build-arch</tt>, since it
+ does not yet know how to check for its existence) and
+ <tt>binary-arch</tt>.
+ </p>
+ <p>
+ The purpose of the original split, I recall, was so that
+ 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>
+ 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>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>
+ <item>
+ 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>build</tt>, <tt>build-indep</tt>,
+ <tt>binary</tt> and <tt>binary-indep</tt>.
+ </item>
+ </taglist>
+ </p>
+
+ </sect>
+
+ </chapt>
+
+
+ <chapt id="sharedlibs"><heading>Shared libraries</heading>
+
+ <p>
+ Packages containing shared libraries must be constructed with
+ a little care to make sure that the shared library is always
+ available. This is especially important for packages whose
+ shared libraries are vitally important, such as the C library
+ (currently <tt>libc6</tt>).
+ </p>
+
+ <p>
+ 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
+ whose name changes whenever the shared object version
+ changes.<footnote>
+ <p>
+ Since it is common place to install several versions of a
+ package that just provides shared libraries, it is a
+ good idea that the library package should not
+ contain any extraneous non-versioned files, unless they
+ happen to be in versioned directories.</p>
+ </footnote>
+ The most common mechanism is to place it in a package
+ called
+ <package><var>libraryname</var><var>soversion</var></package>,
+ where <file><var>soversion</var></file> is the version number
+ in the soname of the shared library<footnote>
+ The soname is the shared object name: it's the thing
+ that has to match exactly between building an executable
+ and running it for the dynamic linker to be able run the
+ 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 your package includes run-time support programs that
+ do not need to be invoked manually by users, but are
+ nevertheless required for the package to function, then it
+ is recommended that these programs are placed
+ (if they are binary) in a subdirectory of
+ <file>/usr/lib</file>, preferably under
+ <file>/usr/lib/</file><var>package-name</var>.
+ If the program is architecture independent, the
+ recommendation is for it to be placed in a subdirectory of
+ <file>/usr/share</file> instead, preferably under
+ <file>/usr/share/</file><var>package-name</var>.
+ </p>
+
+
+ <p>
+ If you have several shared libraries built from the same
+ source tree you may lump them all together into a single
+ 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>libgdbm3</package>
+ package should install <file>libgdbm.so.3.0.0</file> as
+ <file>/usr/lib/libgdbm.so.3.0.0</file>. The files should not be
+ renamed or re-linked by any <prgn>prerm</prgn> or
+ <prgn>postrm</prgn> scripts; <prgn>dpkg</prgn> will take care
+ of renaming things safely without affecting running programs,
+ and attempts to interfere with this are likely to lead to
+ problems.
+ </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.
+ </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 <package>libgdbm3</package> package should include
+ a symbolic link from <file>/usr/lib/libgdbm.so.3</file> to
+ <file>libgdbm.so.3.0.0</file>. This is needed so that the dynamic
+ linker (for example <prgn>ld.so</prgn> or
+ <prgn>ld-linux.so.*</prgn>) can find the library between the
+ time that <prgn>dpkg</prgn> installs it and the time that
+ <prgn>ldconfig</prgn> is run in the <prgn>postinst</prgn>
+ script.<footnote>
+ 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
+ <prgn>dpkg</prgn> comes to install the symlink
+ (overwriting the previous symlink pointing at an older
+ version of the library), the new shared library is already
+ in place. In the past, this was achieved by creating the
+ library in the temporary packaging directory before
+ creating the symlink. Unfortunately, this was not always
+ effective, since the building of the tar file in the
+ <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.
+ Since 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.
+ </footnote>
+ </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>
+ These are currently
+ <list compact="compact">
+ <item>/usr/local/lib</item>
+ <item>/usr/lib/libc5-compat</item>
+ <item>/lib/libc5-compat</item>
+ </list>
+ </footnote>
+ must use <prgn>ldconfig</prgn> to update the shared library
+ system.
+ </p>
+
+ <p>
+ The package maintainer scripts must only call
+ <prgn>ldconfig</prgn> under these circumstances:
+ <list compact="compact">
+ <item>When the <prgn>postinst</prgn> script is run with a
+ first argument of <tt>configure</tt>, the script must call
+ <prgn>ldconfig</prgn>, and may optionally invoke
+ <prgn>ldconfig</prgn> at other times.
+ </item>
+ <item>When the <prgn>postrm</prgn> script is run with a
+ first argument of <tt>remove</tt>, the script should call
+ <prgn>ldconfig</prgn>.
+ </item>
+ </list>
+ <footnote>
+ <p>
+ During install or upgrade, the preinst is called before
+ the new files are installed, so calling "ldconfig" is
+ 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 that the shared libraries from the package
+ are removed. The postrm can be called at several other
+ times. At the time of "postrm purge", "postrm
+ abort-install", or "postrm abort-upgrade", calling
+ "ldconfig" is useless because the shared lib files are
+ not on-disk. However, when "postrm" is invoked with
+ arguments "upgrade", "failed-upgrade", or "disappear", a
+ shared lib may exist on-disk under a temporary filename.
+ </p>
+ </footnote>
+ </p>
+ </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>
+ Instead, either create another package for the runtime binaries
+ (this package might typically be named
+ <package><var>libraryname</var>-runtime</package>; note the absence
+ of the <var>soversion</var> in the package name), or if the
+ development package is small, include them in there.
+ </p>
+ </sect>
+
+ <sect id="sharedlibs-static">
+ <heading>Static libraries</heading>
+
+ <p>
+ The static library (<file><var>libraryname.a</var></file>)
+ is usually provided in addition to the shared version.
+ It is placed into the development package (see below).
+ </p>
+
+ <p>
+ In some cases, it is acceptable for a library to be
+ available in static form only; these cases include:
+ <list>
+ <item>libraries for languages whose shared library support
+ is immature or unstable</item>
+ <item>libraries whose interfaces are in flux or under
+ development (commonly the case when the library's
+ major version number is zero, or where the ABI breaks
+ across patchlevels)</item>
+ <item>libraries which are explicitly intended to be
+ available only in static form by their upstream
+ author(s)</item>
+ </list>
+ </p>
+
+ <sect id="sharedlibs-dev">
+ <heading>Development files</heading>
+
+ <p>
+ The development files associated to a shared library need to be
+ placed in a package called
+ <package><var>libraryname</var><var>soversion</var>-dev</package>,
+ or if you prefer only to support one development version at a
+ time, <package><var>libraryname</var>-dev</package>.
+ </p>
+
+ <p>
+ In case several development versions of a library exist, you may
+ need to use <prgn>dpkg</prgn>'s Conflicts mechanism (see
+ <ref id="conflicts">) to ensure that the user only installs one
+ development version at a time (as different development versions are
+ likely to have the same header files in them, which would cause a
+ filename clash if both were installed).
+ </p>
+
+ <p>
+ The development package should contain a symlink for the associated
+ shared library without a version number. For example, the
+ <package>libgdbm-dev</package> package should include a symlink
+ from <file>/usr/lib/libgdbm.so</file> to
+ <file>libgdbm.so.3.0.0</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>${binary:Version}</tt> substitution variable can be
+ useful for this purpose.
+ <footnote>
+ Previously, <tt>${Source-Version}</tt> was used, but its name
+ was confusing and it has been deprecated since dpkg 1.13.19.
+ </footnote>
+ </p>
+ </sect>
+
+ <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
+ shared library, we must ensure that when the package is
+ installed on the system, all of the libraries needed are
+ also installed. This requirement led to the creation of the
+ <tt>shlibs</tt> system, which is very simple in its design:
+ any package which <em>provides</em> a shared library also
+ provides information on the package dependencies required to
+ ensure the presence of this library, and any package which
+ <em>uses</em> a shared library uses this information to
+ determine the dependencies it requires. The files which
+ contain the mapping from shared libraries to the necessary
+ dependency information are called <file>shlibs</file> files.
+ </p>
+
+ <p>
+ Thus, when a package is built which contains any shared
+ libraries, it must provide a <file>shlibs</file> file for other
+ packages to use, and when a package is built which contains
+ any shared libraries or compiled binaries, it must run
+ <qref id="pkg-dpkg-shlibdeps"><prgn>dpkg-shlibdeps</prgn></qref>
+ on these to determine the libraries used and hence the
+ dependencies needed by this package.<footnote>
+ <p>
+ In the past, the shared libraries linked to were
+ determined by calling <prgn>ldd</prgn>, but now
+ <prgn>objdump</prgn> is used to do this. The only
+ change this makes to package building is that
+ <prgn>dpkg-shlibdeps</prgn> must also be run on shared
+ libraries, whereas in the past this was unnecessary.
+ The rest of this footnote explains the advantage that
+ this method gives.
+ </p>
+
+ <p>
+ We say that a binary <tt>foo</tt> <em>directly</em> uses
+ a library <tt>libbar</tt> if it is explicitly linked
+ with that library (that is, it uses the flag
+ <tt>-lbar</tt> during the linking stage). Other
+ libraries that are needed by <tt>libbar</tt> are linked
+ <em>indirectly</em> to <tt>foo</tt>, and the dynamic
+ linker will load them automatically when it loads
+ <tt>libbar</tt>. A package should depend on
+ the libraries it directly uses, and the dependencies for
+ those libraries should automatically pull in the other
+ libraries.
+ </p>
+
+ <p>
+ Unfortunately, the <prgn>ldd</prgn> program shows both
+ the directly and indirectly used libraries, meaning that
+ the dependencies determined included both direct and
+ indirect dependencies. The use of <prgn>objdump</prgn>
+ avoids this problem by determining only the directly
+ used libraries.
+ </p>
+
+ <p>
+ A good example of where this helps is the following. We
+ could update <tt>libimlib</tt> with a new version that
+ supports a new graphics format called dgf (but retaining
+ the same major version number). If we used the old
+ <prgn>ldd</prgn> method, every package that uses
+ <tt>libimlib</tt> would need to be recompiled so it
+ would also depend on <tt>libdgf</tt> or it wouldn't run
+ due to missing symbols. However with the new system,
+ packages using <tt>libimlib</tt> can rely on
+ <tt>libimlib</tt> itself having the dependency on
+ <tt>libdgf</tt> and so they would not need rebuilding.
+ </p>
+ </footnote>
+ </p>
+
+ <p>
+ In the following sections, we will first describe where the
+ various <tt>shlibs</tt> files are to be found, then how to
+ use <prgn>dpkg-shlibdeps</prgn>, and finally the <tt>shlibs</tt>
+ file format and how to create them if your package contains a
+ shared library.
+ </p>
+
+ <sect1>
+ <heading>The <tt>shlibs</tt> files present on the system</heading>
+
+ <p>
+ There are several places where <tt>shlibs</tt> files are
+ found. The following list gives them in the order in which
+ they are read by
+ <qref id="pkg-dpkg-shlibdeps"><prgn>dpkg-shlibdeps</prgn></qref>.
+ (The first one which gives the required information is used.)
+ </p>
+
+ <p>
+ <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">).
+ </p>
+ </item>
+
+ <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
+ administrator.
+ </p>
+ </item>
+
+ <item>
+ <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
+ control file area of the temporary build directory and
+ given the name <file>shlibs</file>. These files give
+ details of any shared libraries included in the
+ package.<footnote>
+ An example may help here. Let us say that the
+ source package <tt>foo</tt> generates two binary
+ packages, <tt>libfoo2</tt> and
+ <tt>foo-runtime</tt>. When building the binary
+ packages, the two packages are created in the
+ directories <file>debian/libfoo2</file> and
+ <file>debian/foo-runtime</file> respectively.
+ (<file>debian/tmp</file> could be used instead of one
+ of these.) Since <tt>libfoo2</tt> provides the
+ <tt>libfoo</tt> shared library, it will require a
+ <tt>shlibs</tt> file, which will be installed in
+ <file>debian/libfoo2/DEBIAN/shlibs</file>, eventually
+ to become
+ <file>/var/lib/dpkg/info/libfoo2.shlibs</file>. Then
+ when <prgn>dpkg-shlibdeps</prgn> is run on the
+ executable
+ <file>debian/foo-runtime/usr/bin/foo-prog</file>, it
+ will examine the
+ <file>debian/libfoo2/DEBIAN/shlibs</file> file to
+ determine whether <tt>foo-prog</tt>'s library
+ dependencies are satisfied by any of the libraries
+ provided by <tt>libfoo2</tt>. For this reason,
+ <prgn>dpkg-shlibdeps</prgn> must only be run once
+ all of the individual binary packages'
+ <tt>shlibs</tt> files have been installed into the
+ build directory.
+ </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
+ maintained by the relevant package maintainers.
+ </p>
+ </item>
+
+ <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.
+ It was used when the <file>shlibs</file> setup was first
+ introduced, but it is now normally empty. It is
+ maintained by the <tt>dpkg</tt> maintainer.
+ </p>
+ </item>
+ </list>
+ </p>
+ </sect1>
+
+ <sect1>
+ <heading>How to use <prgn>dpkg-shlibdeps</prgn> and the
+ <file>shlibs</file> files</heading>
+
+ <p>
+ Put a call to
+ <qref id="pkg-dpkg-shlibdeps"><prgn>dpkg-shlibdeps</prgn></qref>
+ into your <file>debian/rules</file> file. If your package
+ contains only compiled binaries and libraries (but no scripts),
+ you can use a command such as:
+ <example compact="compact">
+dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* \
+ debian/tmp/usr/lib/*
+ </example>
+ Otherwise, you will need to explicitly list the compiled
+ binaries and libraries.<footnote>
+ 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.
+ </footnote>
+ </p>
+
+ <p>
+ This command puts the dependency information into the
+ <file>debian/substvars</file> file, which is then used by
+ <prgn>dpkg-gencontrol</prgn>. You will need to place a
+ <tt>${shlibs:Depends}</tt> variable in the <tt>Depends</tt>
+ field in the control file for this to work.
+ </p>
+
+ <p>
+ If <prgn>dpkg-shlibdeps</prgn> doesn't complain, you're
+ done. If it does complain you might need to create your own
+ <file>debian/shlibs.local</file> file, as explained below (see
+ <ref id="shlibslocal">).
+ </p>
+
+ <p>
+ If you have multiple binary packages, you will need to call
+ <prgn>dpkg-shlibdeps</prgn> on each one which contains
+ compiled libraries or binaries. In such a case, you will
+ need to use the <tt>-T</tt> option to the <tt>dpkg</tt>
+ utilities to specify a different <file>substvars</file> file.
+ </p>
+
+ <p>
+ If you are creating a udeb for use in the Debian Installer, you
+ will need to specify that <prgn>dpkg-shlibdeps</prgn> should use
+ the dependency line of type <tt>udeb</tt> by adding
+ <tt>-tudeb</tt> as option<footnote>
+ <prgn>dh_shlibdeps</prgn> from the <tt>debhelper</tt> suite
+ will automatically add this option if it knows it is
+ processing a udeb.
+ </footnote>. If there is no dependency line of type <tt>udeb</tt>
+ in the <file>shlibs</file> file, <prgn>dpkg-shlibdeps</prgn> will
+ fall back to the regular dependency line.
+ </p>
+
+ <p>
+ For more details on dpkg-shlibdeps, please see
+ <ref id="pkg-dpkg-shlibdeps"> and
+ <manref name="dpkg-shlibdeps" section="1">.
+ </p>
+ </sect1>
+
+ <sect1 id="shlibs">
+ <heading>The <file>shlibs</file> File Format</heading>
+
+ <p>
+ Each <file>shlibs</file> file has the same format. Lines
+ beginning with <tt>#</tt> are considered to be comments and
+ are ignored. Each line is of the form:
+ <example compact="compact">
+[<var>type</var>: ]<var>library-name</var> <var>soname-version</var> <var>dependencies ...</var>
+ </example>
+ </p>
+
+ <p>
+ We will explain this by reference to the example of the
+ <tt>zlib1g</tt> package, which (at the time of writing)
+ installs the shared library <file>/usr/lib/libz.so.1.1.3</file>.
+ </p>
+
+ <p>
+ <var>type</var> is an optional element that indicates the type
+ of package for which the line is valid. The only type currently
+ in use is <tt>udeb</tt>. The colon and space after the type are
+ required.
+ </p>
+
+ <p>
+ <var>library-name</var> is the name of the shared library,
+ in this case <tt>libz</tt>. (This must match the name part
+ of the soname, see below.)
+ </p>
+
+ <p>
+ <var>soname-version</var> is the version part of the soname of
+ the library. The soname is the thing that must exactly match
+ for the library to be recognized by the dynamic linker, and is
+ usually of the form
+ <tt><var>name</var>.so.<var>major-version</var></tt>, in our
+ example, <tt>libz.so.1</tt>.<footnote>
+ This can be determined using the command
+ <example compact="compact">
+objdump -p /usr/lib/libz.so.1.1.3 | grep SONAME
+ </example>
+ </footnote>
+ The version part is the part which comes after
+ <tt>.so.</tt>, so in our case, it is <tt>1</tt>.
</p>
<p>
the dynamic linker about using older shared libraries with
newer binaries.
</p>
- </sect>
- <sect>
+ <p>
+ As zlib1g also provides a udeb containing the shared library,
+ there would also be a second line:
+ <example compact="compact">
+udeb: libz 1 zlib1g-udeb (>= 1:1.1.3)
+ </example>
+ </p>
+ </sect1>
+
+ <sect1>
<heading>Providing a <file>shlibs</file> file</heading>
<p>
- If your package provides a shared library, you should create
+ If your package provides a shared library, you need to create
a <file>shlibs</file> file following the format described above.
It is usual to call this file <file>debian/shlibs</file> (but if
you have multiple binary packages, you might want to call it
<file>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>
+ <tt>debhelper</tt> suite does. If your package also has a udeb
+ that provides a shared library, <prgn>dh_makeshlibs</prgn> can
+ automatically generate the <tt>udeb:</tt> lines if you specify
+ the name of the udeb with the <tt>--add-udeb</tt> option.
</footnote>
since the <file>debian/shlibs</file> file itself is ignored by
<prgn>dpkg-shlibdeps</prgn>.
<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>
<sect>
- <heading>Filesystem hierarchy</heading>
+ <heading>File system hierarchy</heading>
- <sect1>
- <heading>Filesystem Structure</heading>
+ <sect1 id="fhs">
+ <heading>File system Structure</heading>
<p>
The location of all installed files and directories must
- comply with the Filesystem Hierarchy Standard (FHS),
- version 2.1, except where doing so would violate other
- terms of Debian Policy. The version of this document
- referred here can be found in the <tt>debian-policy</tt>
- package or on
- <url id="http://www.debian.org/doc/packaging-manuals/fhs/"
- name="FHS (Debian copy)"> alongside this manual. The
+ comply with the File system Hierarchy Standard (FHS),
+ version 2.3, with the exceptions noted below, and except
+ where doing so would violate other terms of Debian
+ Policy. The following exceptions to the FHS apply:
+
+ <enumlist>
+ <item>
+ <p>
+ Legacy XFree86 servers are permitted to retain the
+ configuration file location
+ <file>/etc/X11/XF86Config-4</file>.
+ </p>
+ </item>
+ <item>
+ <p>
+ The optional rules related to user specific
+ configuration files for applications are stored in
+ the user's home directory are relaxed. It is
+ recommended that such files start with the
+ '<tt>.</tt>' character (a "dot file"), and if an
+ application needs to create more than one dot file
+ then the preferred placement is in a subdirectory
+ with a name starting with a '.' character, (a "dot
+ directory"). In this case it is recommended the
+ configuration files not start with the '.'
+ character.
+ </p>
+ </item>
+ <item>
+ <p>
+ The requirement for amd64 to use <file>/lib64</file>
+ for 64 bit binaries is removed.
+ </p>
+ </item>
+ <item>
+ <p>
+ The requirement that
+ <file>/usr/local/share/man</file> be "synonymous"
+ with <file>/usr/local/man</file> is relaxed to a
+ recommendation</p>
+ </item>
+ <item>
+ <p>
+ The requirement that windowmanagers with a single
+ configuration file call it <file>system.*wmrc</file>
+ is removed, as is the restriction that the window
+ manager subdirectory be named identically to the
+ window manager name itself.
+ </p>
+ </item>
+ <item>
+ <p>
+ The requirement that boot manager configuration
+ files live in <file>/etc</file>, or at least are
+ symlinked there, is relaxed to a recommendation.
+ </p>
+ </item>
+ </enumlist>
+
+ </p>
+ <p>
+ The version of this document referred here can be
+ found in the <tt>debian-policy</tt> package or on <url
+ id="http://www.debian.org/doc/packaging-manuals/fhs/"
+ name="FHS (Debian copy)"> alongside this manual (or, if
+ you have the <package>debian-policy</package> installed,
+ you can try <url
+ 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>
<p>
However, the package may create empty directories below
<file>/usr/local</file> so that the system administrator knows
- where to place site-specific files. These directories
+ where to place site-specific files. These are not
+ directories <em>in</em> <file>/usr/local</file>, but are
+ children of directories in <file>/usr/local</file>. These
+ directories (<file>/usr/local/*/dir/</file>)
should be removed on package removal if they are
empty.
</p>
<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>
of simplicity, this document describes only the symbolic
link method. However, it must not be assumed by maintainer
scripts that this method is being used, and any automated
- manipulation of the various runlevel behaviours by
+ manipulation of the various runlevel behaviors by
maintainer scripts must be performed using
<prgn>update-rc.d</prgn> as described below and not by
manually installing or removing symlinks. For information
</p>
<p>
- Also, if the script name ends <tt>.sh</tt>, the script
- will be sourced in runlevel <tt>S</tt> rather that being
+ Also, if the script name ends in <tt>.sh</tt>, the script
+ will be sourced in runlevel <tt>S</tt> rather than being
run in a forked subprocess, but will be explicitly run by
<prgn>sh</prgn> in all other runlevels.
</p>
<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
+ The <file>init.d</file> scripts must ensure that they will
behave sensibly if invoked with <tt>start</tt> when the
service is already running, or with <tt>stop</tt> when it
isn't, and that they don't kill unfortunately-named user
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
the scripts to the local system, e.g., to disable a
service without de-installing the package, or to specify
some special command line options when starting a service,
- while making sure her changes aren't lost during the next
+ while making sure their changes aren't lost during the next
package upgrade.
</p>
<p>
Often there are some variables in the <file>init.d</file>
- scripts whose values control the behaviour of the scripts,
+ scripts whose values control the behavior of the scripts,
and which a system administrator is likely to want to
change. As the scripts themselves are frequently
<tt>conffile</tt>s, modifying them requires that the
<file>/etc/default</file>, which typically will have the same
base name as the <file>init.d</file> script. This extra file
should be sourced by the script when the script runs. It
- must contain only variable settings and comments in POSIX
+ must contain only variable settings and comments in SUSv3
<prgn>sh</prgn> format. It may either be a
<tt>conffile</tt> or a configuration file maintained by
- the package maintainer scripts. See <ref id="config-files">
- for more details.
+ the package maintainer scripts. See <ref id="config-files">
+ for more details.
</p>
<p>
</sect1>
<sect1>
- <heading>Managing the links</heading>
+ <heading>Interfacing with the initscript system</heading>
<p>
- The program <prgn>update-rc.d</prgn> is provided for
- package maintainers to arrange for the proper creation and
- removal of <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.)
+ 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>sysv-rc</prgn> and
+ <prgn>file-rc</prgn>).
</p>
- <p>
- To get the default behavior for your package, put in your
- <prgn>postinst</prgn> script
- <example compact="compact">
-update-rc.d <var>package</var> defaults >/dev/null
- </example>
- and in your <prgn>postrm</prgn>
- <example compact="compact">
-if [ "$1" = purge ]; then
- update-rc.d <var>package</var> remove >/dev/null
-fi
- </example></p>
+ <sect2>
+ <heading>Managing the links</heading>
- <p>
- This will use a default sequence number of 20. If it does
- not matter when or in which order the <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>
+ The program <prgn>update-rc.d</prgn> is provided for
+ package maintainers to arrange for the proper creation and
+ removal of <file>/etc/rc<var>n</var>.d</file> symbolic links,
+ or their functional equivalent if another method is being
+ used. This may be used by maintainers in their packages'
+ <prgn>postinst</prgn> and <prgn>postrm</prgn> scripts.
+ </p>
- <p>
- For more information about using <tt>update-rc.d</tt>,
- please consult its manpage <manref name="update-rc.d"
- section="8">.
- </p>
- </sect1>
+ <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 man page <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 package maintainer scripts must use
+ <prgn>invoke-rc.d</prgn> to invoke the
+ <file>/etc/init.d/*</file> initscripts, instead of
+ calling them directly.
+ </p>
+ <p>
+ 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 which invoke-rc.d >/dev/null 2>&1; 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 man page
+ <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>
<p>
- The <prgn>bind</prgn> DNS (nameserver) package wants to
- make sure that the nameserver is running in multiuser
- runlevels, and is properly shut down with the system. It
- puts a script in <file>/etc/init.d</file>, naming the script
- appropriately <tt>bind</tt>. As you can see, the script
- interprets the argument <tt>reload</tt> to send the
- nameserver a <tt>HUP</tt> signal (causing it to reload its
- configuration); this way the system administrator can say
- <file>/etc/init.d/bind reload</file> to reload the name
- server. The script has one configurable value, which can
- be used to pass parameters to the named program at
- startup; this value is read from
- <file>/etc/default/bind</file> (see below).
- </p>
-
- <p>
- <example compact="compact">
-#!/bin/sh
-#
-# Original version by Robert Leslie
-# <rob@mars.org>, edited by iwj and cs
-
-test -x /usr/sbin/named || exit 0
-
-# Source defaults file.
-PARAMS=''
-if [ -f /etc/default/bind ]; then
- . /etc/default/bind
-fi
-
-
-case "$1" in
-start)
- echo -n "Starting domain name service: named"
- start-stop-daemon --start --quiet --exec /usr/sbin/named \
- -- $PARAMS
- echo "."
- ;;
-stop)
- echo -n "Stopping domain name service: named"
- start-stop-daemon --stop --quiet \
- --pidfile /var/run/named.pid --exec /usr/sbin/named
- echo "."
- ;;
-restart)
- echo -n "Restarting domain name service: named"
- start-stop-daemon --stop --quiet \
- --pidfile /var/run/named.pid --exec /usr/sbin/named
- start-stop-daemon --start --verbose --exec /usr/sbin/named \
- -- $PARAMS
- echo "."
- ;;
-force-reload|reload)
- echo -n "Reloading configuration of domain name service: named"
- start-stop-daemon --stop --signal 1 --quiet \
- --pidfile /var/run/named.pid --exec /usr/sbin/named
- echo "."
- ;;
-*)
- echo "Usage: /etc/init.d/bind " \
- " {start|stop|restart|reload|force-reload}" >&2
- exit 1
- ;;
-esac
-
-exit 0
- </example>
- </p>
-
- <p>
- Complementing the above init script is a configuration
- file <file>/etc/default/bind</file>, which contains
- configurable parameters used by the script. This would be
- created by the <prgn>postinst</prgn> script if it was not
- already present, and removed on purge by the
- <prgn>postrm</prgn> script.
- <example compact="compact">
-# Specified parameters to pass to named. See named(8).
-# You may uncomment the following line, and edit to taste.
-#PARAMS="-u nobody"
- </example>
- </p>
-
- <p>
- Another example on which you can base your
+ An example on which you can base your
<file>/etc/init.d</file> scripts is found in
<file>/etc/init.d/skeleton</file>.
</p>
- <p>
- If this package is happy with the default setup from
- <prgn>update-rc.d</prgn>, namely an ordering number of 20
- and having named running in all runlevels, it can say in
- its <prgn>postinst</prgn>:
- <example compact="compact">
-update-rc.d bind defaults >/dev/null
- </example>
- And in its <prgn>postrm</prgn>, to remove the links when the
- package is purged:
- <example compact="compact">
-if [ "$1" = purge ]; then
- update-rc.d bind remove >/dev/null
-fi
- </example>
- </p>
</sect1>
</sect>
</p>
<p>
- Here is a list of overall rules that you should use when you
- create output messages. They can be useful if you have a
- non-standard message that is not covered specifically in the
- sections below.
+ Here is a list of overall rules that should be used for
+ messages generated by <file>/etc/init.d</file> scripts.
</p>
<p>
<list>
<item>
- <p>
- Every message should fit in one line (fewer than 80
+ The message should fit in one line (fewer than 80
characters), start with a capital letter and end with
a period (<tt>.</tt>) and line feed (<tt>"\n"</tt>).
- </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>
+ If the script is performing some time consuming task in
+ the background (not merely starting or stopping a
+ program, for instance), an ellipsis (three dots:
+ <tt>...</tt>) should be output to the screen, with no
+ leading or tailing whitespace or line feeds.
</item>
<item>
- <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
- saying
+ The messages should appear as if the computer is telling
+ the user what it is doing (politely :-), but should not
+ mention "it" directly. For example, instead of:
<example compact="compact">
I'm starting network daemons: nfsd mountd.
</example>
- just say
+ the message should say
<example compact="compact">
Starting network daemons: nfsd mountd.
</example>
- </p>
</item>
</list>
</p>
<p>
- There are standard message formats for the following
- situations. They should be used by the <tt>init.d</tt>
- scripts.
+ <tt>init.d</tt> script should use the following standard
+ message formats for the situations enumerated below.
</p>
<p>
<p>When daemons are started</p>
<p>
- If your script starts one or more daemons, the output
+ If the script starts one or more daemons, the output
should look like this (a single line, no leading
spaces):
<example compact="compact">
start-stop-daemon --start --quiet --exec /usr/sbin/lpd
echo "."
</example>
- in the script. If you have more than one daemon to
- start, you should do the following:
+ in the script. If there are more than one daemon to
+ start, the output should look like this:
<example compact="compact">
echo -n "Starting remote file system services:"
echo -n " nfsd"; start-stop-daemon --start --quiet nfsd
echo -n " ugidd"; start-stop-daemon --start --quiet ugidd
echo "."
</example>
- This makes it possible for the user to see what takes
- so long and when the final daemon has been started.
- You should be careful where to put spaces: in the
- example above the system administrator can easily
- comment out a line if he don't wants to start a
- specific daemon, while the displayed message still
+ This makes it possible for the user to see what is
+ happening and when the final daemon has been started.
+ Care should be taken in the placement of white spaces:
+ in the example above the system administrators can
+ easily comment out a line if they don't want to start
+ a specific daemon, while the displayed message still
looks good.
</p>
</item>
If you have to set up different system parameters
during the system boot, you should use this format:
<example compact="compact">
-Setting <var>parameter</var> to `<var>value</var>'.
+Setting <var>parameter</var> to "<var>value</var>".
</example>
</p>
You can use a statement such as the following to get
the quotes right:
<example compact="compact">
-echo "Setting DNS domainname to \`$domainname'."
+echo "Setting DNS domainname to \"$domainname\"."
</example>
</p>
<p>
- Note that the left quotation mark (<tt>`</tt>) is
- different from the right one (<tt>'</tt>).
+ Note that the same symbol (<tt>"</tt>) is used for the left
+ and right quotation marks. A grave accent (<tt>`</tt>) is
+ not a quote character; neither is an apostrophe
+ (<tt>'</tt>).
</p>
</item>
</p>
<p>
- For example, stopping the printer daemon will like
- like this:
+ For example, stopping the printer daemon will look like
+ this:
<example compact="compact">
Stopping printer spooler: lpd.
</example>
</example>
You should print the <tt>done.</tt> immediately after
the job has been completed, so that the user is
- informed why she has to wait. You can get this
+ informed why they have to wait. You can get this
behavior by saying
<example compact="compact">
echo -n "Doing something very useful..."
via cron, it should place a file with the name of the
package in one or more of the following directories:
<example compact="compact">
+/etc/cron.hourly
/etc/cron.daily
/etc/cron.weekly
/etc/cron.monthly
</example>
As these directory names imply, the files within them are
- executed on a daily, weekly, or monthly basis,
+ executed on an hourly, daily, weekly, or monthly basis,
respectively. The exact times are listed in
<file>/etc/crontab</file>.</p>
All files installed in any of these directories must be
scripts (e.g., shell scripts or Perl scripts) so that they
can easily be modified by the local system administrator.
- In addition, they should be treated as configuration
- files.
+ In addition, they must be treated as configuration files.
</p>
<p>
- If a certain job has to be executed more frequently than
- daily, the package should install a file
+ If a certain job has to be executed at some other frequency or
+ at a specific time, the package should install a file
<file>/etc/cron.d/<var>package</var></file>. This file uses the
same syntax as <file>/etc/crontab</file> and is processed by
<prgn>cron</prgn> automatically. The file must also be
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
- documents, and <em>menu programs</em> (either X window
- managers or text-based menu programs such as
- <prgn>pdmenu</prgn>).
+ <em>menu programs</em> (either X window managers or
+ text-based menu programs such as <prgn>pdmenu</prgn>).
</p>
<p>
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>
- Please also refer to the <em>Debian Menu System</em>
- documentation that comes with the <tt>menu</tt> package for
- information about how to register your applications and web
- documents.
+ Menu entries should follow the current menu policy.
</p>
- </sect>
- <sect>
- <heading>Multimedia handlers</heading>
+ <p>
+ The menu policy can be found in the <tt>menu-policy</tt>
+ files in the <tt>debian-policy</tt> package.
+ It is also available from the Debian web mirrors at
+ <tt><url name="/doc/packaging-manuals/menu-policy/"
+ id="http://www.debian.org/doc/packaging-manuals/menu-policy/"></tt>.
+ </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 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.
+ Please also refer to the <em>Debian Menu System</em>
+ documentation that comes with the <package>menu</package>
+ package for information about how to register your
+ applications.
</p>
+ </sect>
+
+ <sect id="mime">
+ <heading>Multimedia handlers</heading>
<p>
MIME (Multipurpose Internet Mail Extensions, RFCs 2045-2049)
<p>
Registration of MIME type handlers allows programs like mail
- user agents and web browsers to to invoke these handlers to
- view, edit or display MIME types they don't support
- directly.
+ user agents and web browsers to invoke these handlers to
+ 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.
+ It is also available from the Debian web mirrors at
+ <tt><url name="/doc/packaging-manuals/mime-policy/"
+ id="http://www.debian.org/doc/packaging-manuals/mime-policy/"></tt>.
</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:
<p>
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 of the <prgn>base-files</prgn> package, other packages must
+ not put any environment variables or other commands into that
+ file.
+ </p>
+ </sect>
+
+ <sect id="doc-base">
+ <heading>Registering Documents using doc-base</heading>
+
+ <p>
+ The <package>doc-base</package> package implements a
+ flexible mechanism for handling and presenting
+ documentation. The recommended practice is for every Debian
+ package that provides online documentation (other than just
+ manual pages) to register these documents with
+ <package>doc-base</package> by installing a
+ <package>doc-base</package> control file via the
+ <prgn/install-docs/ script at installation time and
+ de-register the manuals again when the package is removed.
+ </p>
+ <p>
+ Please refer to the documentation that comes with the
+ <package>doc-base</package> package for information and
+ details.
+ </p>
</sect>
+
</chapt>
+
<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>
+INSTALL = install -s # (or use strip on the files in debian/tmp)
+ </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>
- 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
-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
+ package.
+ </p>
-ifneq (,$(findstring debug,$(DEB_BUILD_OPTIONS)))
-CFLAGS += -g
-endif
-ifeq (,$(findstring nostrip,$(DEB_BUILD_OPTIONS)))
-INSTALL_PROGRAM += -s
-endif
- </example>
+ <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>
+ (see <ref id="debianrules-options">). This variable can contain
+ several flags to change how a package is compiled and built.
</p>
<p>
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>
+ If the package is <strong>architecture: any</strong>, then
+ the shared library compilation and linking flags must have
+ <tt>-fPIC</tt>, or the package shall not build on some of
+ the supported architectures<footnote>
+ <p>
+ If you are using GCC, <tt>-fPIC</tt> produces code with
+ relocatable position independent code, which is required for
+ most architectures to create a shared library, with i386 and
+ perhaps some others where non position independent code is
+ permitted in a shared library.
+ </p>
+ <p>
+ Position independent code may have a performance penalty,
+ especially on <tt>i386</tt>. However, in most cases the
+ speed penalty must be measured against the memory wasted on
+ the few architectures where non position independent code is
+ even possible.
+ </p>
+ </footnote>. Any exception to this rule must be discussed on
+ the mailing list <em>debian-devel@lists.debian.org</em>, and
+ a rough consensus obtained. The reasons for not compiling
+ with <tt>-fPIC</tt> flag must be recorded in the file
+ <tt>README.Debian</tt>, and care must be taken to either
+ restrict the architecture or arrange for <tt>-fPIC</tt> to
+ be used on architectures where it is required.<footnote>
+ <p>
+ Some of the reasons why this might be required is if the
+ library contains hand crafted assembly code that is not
+ relocatable, the speed penalty is excessive for compute
+ intensive libs, and similar reasons.
+ </p>
+ </footnote>
+ </p>
<p>
- 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>
-
+ As to the static libraries, the common case is not to have
+ relocatable code, since there is no benefit, unless in specific
+ cases; therefore the static version must not be compiled
+ with the <tt>-fPIC</tt> flag. Any exception to this rule
+ should be discussed on the mailing list
+ <em>debian-devel@lists.debian.org</em>, and the reasons for
+ compiling with the <tt>-fPIC</tt> flag must be recorded in
+ the file <tt>README.Debian</tt>. <footnote>
+ <p>
+ Some of the reasons for linking static libraries with
+ the <tt>-fPIC</tt> flag are if, for example, one needs a
+ Perl API for a library that is under rapid development,
+ and has an unstable API, so shared libraries are
+ pointless at this phase of the library's development. In
+ that case, since Perl needs a library with relocatable
+ code, it may make sense to create a static library with
+ relocatable code. Another reason cited is if you are
+ distilling various libraries into a common shared
+ library, like <tt>mklibs</tt> does in the Debian
+ installer project.
+ </p>
+ </footnote>
+ </p>
+ <p>
+ In other words, if both a shared and a static library is
+ being built, each source unit (<tt>*.c</tt>, for example,
+ for C files) will need to be compiled twice, for the normal
+ case.
+ </p>
<p>
You must specify the gcc option <tt>-D_REENTRANT</tt>
when building a library (either static or shared) to make
- the library compatible with LinuxThreads.</p>
+ the library compatible with LinuxThreads.
+ </p>
+
+ <p>
+ Although not enforced by the build tools, shared libraries
+ must be linked against all libraries that they use symbols from
+ in the same way that binaries are. This ensures the correct
+ functioning of the <qref id="sharedlibs-shlibdeps">shlibs</qref>
+ system and guarantees that all libraries can be safely opened
+ with <tt>dlopen()</tt>. Packagers may wish to use the gcc
+ option <tt>-Wl,-z,defs</tt> when building a shared library.
+ Since this option enforces symbol resolution at build time,
+ a missing library reference will be caught early as a fatal
+ build error.
+ </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>
+ When scripts are installed into a directory in the system
+ PATH, the script name should not include an extension such
+ as <tt>.sh</tt> or <tt>.pl</tt> that denotes the scripting
+ language currently used to implement it.
+ </p>
<p>
Shell scripts (<prgn>sh</prgn> and <prgn>bash</prgn>)
should almost certainly start with <tt>set -e</tt> so that
errors are detected. Every script should use
<tt>set -e</tt> or check the exit status of <em>every</em>
- 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
- policy, the Linux kernel source, many Debian scripts,
- etc.). This <tt>echo -n</tt> mechanism is valid but not
- required under POSIX, hence this explicit addition.
- Also, rumour has it that this shall be mandated under
- the LSB anyway.
- </p>
+ command.
+ </p>
+
+ <p>
+ Scripts may assume that <file>/bin/sh</file> implements the
+ SUSv3 Shell Command Language<footnote>
+ Single UNIX Specification, version 3, which is also IEEE
+ 1003.1-2004 (POSIX), and is available on the World Wide Web
+ from <url id="http://www.unix.org/version3/online.html"
+ name="The Open Group"> after free
+ registration.</footnote>
+ plus the following additional features not mandated by
+ SUSv3:<footnote>
+ These features are in widespread use in the Linux community
+ and are implemented in all of bash, dash, and ksh, the most
+ common shells users may wish to use as <file>/bin/sh</file>.
</footnote>
- Thus, shell scripts specifying <file>/bin/sh</file> as
- interpreter should only use POSIX features. If a script
- requires non-POSIX features from the shell interpreter, the
- appropriate shell must be specified in the first line of the
- script (e.g., <tt>#!/bin/bash</tt>) and the package must
- depend on the package providing the shell (unless the shell
- package is marked `Essential', as in the case of
- <prgn>bash</prgn>).
+ <list>
+ <item><tt>echo -n</tt>, if implemented as a shell built-in,
+ must not generate a newline.</item>
+ <item><tt>test</tt>, if implemented as a shell built-in, must
+ support <tt>-a</tt> and <tt>-o</tt> as binary logical
+ operators.</item>
+ <item><tt>local</tt> to create a scoped variable must be
+ supported; however, <tt>local</tt> may or may not preserve
+ the variable value from an outer scope and may or may not
+ support arguments more complex than simple variables. Only
+ uses such as:
+<example compact>
+fname () {
+ local a
+ a=''
+ # ... use a ...
+}
+</example>
+ must be supported.
+ </item>
+ </list>
+ If a shell script requires non-SUSv3 features from the shell
+ interpreter other than those listed above, the appropriate shell
+ must be specified in the first line of the script (e.g.,
+ <tt>#!/bin/bash</tt>) and the package must depend on the package
+ providing the shell (unless the shell package is marked
+ "Essential", as in the case of <prgn>bash</prgn>).
</p>
<p>
- You may wish to restrict your script to 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
+ You may wish to restrict your script to SUSv3 features plus the
+ above set when possible so that it may use <file>/bin/sh</file>
+ as its interpreter. If your script works with <prgn>dash</prgn>
+ (originally called <prgn>ash</prgn>), it probably complies with
+ the above requirements, but if you are in doubt, use
<file>/bin/bash</file>.
</p>
<prgn>csh</prgn> and <prgn>tcsh</prgn> should be avoided as
scripting languages. See <em>Csh Programming Considered
Harmful</em>, one of the <tt>comp.unix.*</tt> FAQs, which
- can be found at <url
- id="http://language.perl.com/versus/csh.whynot">.<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>
+ can be found at <url id="http://www.faqs.org/faqs/unix-faq/shell/csh-whynot/">.
If an upstream package comes with <prgn>csh</prgn> scripts
then you must make sure that they start with
<tt>#!/bin/csh</tt> and make your package depend on the
<p>
Any scripts which create files in world-writeable
directories (e.g., in <file>/tmp</file>) must use a
- mechanism which will fail if a file with the same name
- already exists.</p>
+ mechanism which will fail atomically if a file with the same
+ name 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>
</p>
<p>
- Note that a script that embeds configuration information
- (such as most of the files in <file>/etc/default</file> and
- <file>/etc/cron.{daily,weekly,monthly}</file>) is de-facto a
- configuration file and should be treated as such.
+ As noted elsewhere, <file>/etc/init.d</file> scripts,
+ <file>/etc/default</file> files, scripts installed in
+ <file>/etc/cron.{hourly,daily,weekly,monthly}</file>, and cron
+ configuration installed in <file>/etc/cron.d</file> must be
+ treated as configuration files. In general, any script that
+ embeds configuration information is de-facto a configuration
+ file and should be treated as such.
</p>
</sect1>
<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
variety of ways <prgn>dpkg</prgn> can call maintainer
scripts, must not overwrite or otherwise mangle the user's
configuration without asking, must not ask unnecessary
- questions (particularly during upgrades), and otherwise be
- good citizens.
+ questions (particularly during upgrades), and must
+ otherwise be good citizens.
</p>
<p>
<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.
+ default behavior as possible.
</p>
<p>
file (for more information see <manref name="logrotate"
section="8">):
<example compact="compact">
-/var/log/foo/* {
+/var/log/foo/*.log {
rotate 12
weekly
compress
mode 2775. The ownership of the directory should be
consistent with its mode: if a directory is mode 2775, it
should be owned by the group that needs write access to
- it.
+ it.<footnote>
+ <p>
+ When a package is upgraded, and the owner or permissions
+ of a file included in the package has changed, dpkg
+ arranges for the ownership and permissions to be
+ correctly set upon installation. However, this does not
+ extend to directories; the permissions and ownership of
+ directories already on the system does not change on
+ install or upgrade of packages. This makes sense, since
+ otherwise common directories like <tt>/usr</tt> would
+ always be in flux. To correctly change permissions of a
+ directory the package owns, explicit action is required,
+ usually in the <tt>postinst</tt> script. Care must be
+ taken to handle downgrades as well, in that case.
+ </p>
+ </footnote>
</p>
+
<p>
Setuid and setgid executables should be mode 4755 or 2755
respectively, and owned by the appropriate user or group.
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
permissions when the package is reinstalled. However,
the use of <prgn>dpkg-statoverride</prgn> overrides this
- default behaviour. If you use this method, you should
+ default behavior. If you use this method, you should
remember to describe <prgn>dpkg-statoverride</prgn> in
the package documentation; being a relatively new
addition to Debian, it is probably not yet well-known.
- </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
description of the use of <prgn>dpkg-statoverride</prgn>.
</p>
- <p>
- <prgn>dpkg-statoverride</prgn> is a replacement for the
- deprecated <tt>suidmanager</tt> package. Packages which
- previously used <tt>suidmanager</tt> should have a
- <tt>Conflicts: suidmanager (<< 0.50)</tt> entry (or even
- <tt>(<< 0.52)</tt>), and calls to <tt>suidregister</tt>
- and <tt>suidunregister</tt> should now be simply removed
- from the maintainer scripts.
- </p>
-
<p>
If a system administrator wishes to have a file (or
directory or other such thing) installed with owner and
permissions different from those in the distributed Debian
- package,
he can use the <prgn>dpkg-statoverride</prgn>
+ package,
they can use the <prgn>dpkg-statoverride</prgn>
program to instruct <prgn>dpkg</prgn> to use the different
settings every time the file is installed. Thus the
package maintainer should distribute the files with their
maintainer can use <tt>debconf</tt> to find out the
preference, and call <prgn>dpkg-statoverride</prgn> in the
maintainer script if necessary to accommodate the system
- administrator's choice.
+ administrator's choice. Care must be taken during
+ upgrades to not override an existing setting.
</p>
<p>
<example>
for i in /usr/bin/foo /usr/sbin/bar
do
- if ! dpkg-statoverride --list $i >/dev/null
+ # only do something when no setting exists
+ if ! dpkg-statoverride --list $i >/dev/null 2>&1
then
- dpkg-statoverride --update --add sysuser root 4755 $i
+ #include: debconf processing, question about foo and bar
+ if [ "$RET" = "true" ] ; then
+ dpkg-statoverride --update --add sysuser root 4755 $i
+ fi
fi
done
</example>
</sect>
</chapt>
+
<chapt id="customized-programs">
<heading>Customized programs</heading>
<p>
If a program needs to specify an <em>architecture specification
- string</em> in some place, the following format should be
- used: <var>arch</var>-<var>os</var><footnote>
- <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
- the following: <tt>alpha</tt>, <tt>arm</tt>,
- <tt>hppa</tt>, <tt>i386</tt>, <tt>ia64</tt>,
- <tt>m68k</tt>, <tt>mips</tt>, <tt>mipsel</tt>,
- <tt>powerpc</tt>, <tt>s390</tt>, <tt>sh</tt>,
- <tt>sheb</tt>, <tt>sparc</tt> and <tt>sparc64</tt>. The
- operating system, <tt><var>os</var></tt>, is one of:
- <tt>linux</tt>, <tt>gnu</tt>, <tt>freebsd</tt> and
- <tt>openbsd</tt>. Use of <tt>gnu</tt> in this string is
- reserved for the GNU/Hurd operating system.
- </p>
- </footnote>.
+ string</em> in some place, it should select one of the
+ strings provided by <tt>dpkg-architecture -L</tt>. The
+ strings are in the format
+ <tt><var>os</var>-<var>arch</var></tt>, though the OS part
+ is sometimes elided, as when the OS is Linux.<footnote>
+ <p>Currently, the strings are:
+ i386 ia64 alpha amd64 armeb arm hppa m32r m68k mips
+ mipsel powerpc ppc64 s390 s390x sh3 sh3eb sh4 sh4eb
+ sparc darwin-i386 darwin-ia64 darwin-alpha darwin-amd64
+ darwin-armeb darwin-arm darwin-hppa darwin-m32r
+ darwin-m68k darwin-mips darwin-mipsel darwin-powerpc
+ darwin-ppc64 darwin-s390 darwin-s390x darwin-sh3
+ darwin-sh3eb darwin-sh4 darwin-sh4eb darwin-sparc
+ freebsd-i386 freebsd-ia64 freebsd-alpha freebsd-amd64
+ freebsd-armeb freebsd-arm freebsd-hppa freebsd-m32r
+ freebsd-m68k freebsd-mips freebsd-mipsel freebsd-powerpc
+ freebsd-ppc64 freebsd-s390 freebsd-s390x freebsd-sh3
+ freebsd-sh3eb freebsd-sh4 freebsd-sh4eb freebsd-sparc
+ kfreebsd-i386 kfreebsd-ia64 kfreebsd-alpha
+ kfreebsd-amd64 kfreebsd-armeb kfreebsd-arm kfreebsd-hppa
+ kfreebsd-m32r kfreebsd-m68k kfreebsd-mips
+ kfreebsd-mipsel kfreebsd-powerpc kfreebsd-ppc64
+ kfreebsd-s390 kfreebsd-s390x kfreebsd-sh3 kfreebsd-sh3eb
+ kfreebsd-sh4 kfreebsd-sh4eb kfreebsd-sparc knetbsd-i386
+ knetbsd-ia64 knetbsd-alpha knetbsd-amd64 knetbsd-armeb
+ knetbsd-arm knetbsd-hppa knetbsd-m32r knetbsd-m68k
+ knetbsd-mips knetbsd-mipsel knetbsd-powerpc
+ knetbsd-ppc64 knetbsd-s390 knetbsd-s390x knetbsd-sh3
+ knetbsd-sh3eb knetbsd-sh4 knetbsd-sh4eb knetbsd-sparc
+ netbsd-i386 netbsd-ia64 netbsd-alpha netbsd-amd64
+ netbsd-armeb netbsd-arm netbsd-hppa netbsd-m32r
+ netbsd-m68k netbsd-mips netbsd-mipsel netbsd-powerpc
+ netbsd-ppc64 netbsd-s390 netbsd-s390x netbsd-sh3
+ netbsd-sh3eb netbsd-sh4 netbsd-sh4eb netbsd-sparc
+ openbsd-i386 openbsd-ia64 openbsd-alpha openbsd-amd64
+ openbsd-armeb openbsd-arm openbsd-hppa openbsd-m32r
+ openbsd-m68k openbsd-mips openbsd-mipsel openbsd-powerpc
+ openbsd-ppc64 openbsd-s390 openbsd-s390x openbsd-sh3
+ openbsd-sh3eb openbsd-sh4 openbsd-sh4eb openbsd-sparc
+ hurd-i386 hurd-ia64 hurd-alpha hurd-amd64 hurd-armeb
+ hurd-arm hurd-hppa hurd-m32r hurd-m68k hurd-mips
+ hurd-mipsel hurd-powerpc hurd-ppc64 hurd-s390 hurd-s390x
+ hurd-sh3 hurd-sh3eb hurd-sh4 hurd-sh4eb hurd-sparc
+ </p>
+ </footnote>
</p>
<p>
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>
The files <file>/var/run/utmp</file>, <file>/var/log/wtmp</file> and
- <file>/var/log/lastlog</file> must be installed writeable by
+ <file>/var/log/lastlog</file> must be installed writable by
group <tt>utmp</tt>. Programs which need to modify those
files must be installed setgid <tt>utmp</tt>.
</p>
program to edit or display a text document. Since there are
lots of different editors and pagers available in the Debian
distribution, the system administrator and each user should
- have the possibility to choose his/her preferred editor and
+ have the possibility to choose their preferred editor and
pager.
</p>
<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>Access to images</p>
+ <p>
+ It is recommended that images for a package be stored
+ in <tt>/usr/share/images/<var>package</var></tt> and
+ may be referred to through an alias <tt>/images/</tt>
+ as
+ <example>
+ http://localhost/images/<package>/<filename>
+ </example>
+
+ </p>
+ </item>
+
+ <item>
+ <p>Web Document Root</p>
<p>
Web Applications should try to avoid storing files in
the Web Document Root. Instead they should use the
/usr/share/doc/<var>package</var> directory for
documents and register the Web Application via the
- menu package. If access to the web document root is
- unavoidable then use
+ <package>doc-base</package> package. If access to the
+ web document root is unavoidable then use
<example compact="compact">
/var/www
</example>
has put the real document root.
</p>
</item>
-
- </enumlist></p></sect>
-
+ <item><p>Providing httpd and/or httpd-cgi</p>
+ <p>
+ All web servers should provide the virtual package
+ <tt>httpd</tt>. If a web server has CGI support it should
+ provide <tt>httpd-cgi</tt> additionally.
+ </p>
+ <p>
+ All web applications which do not contain CGI scripts should
+ depend on <tt>httpd</tt>, all those web applications which
+ <tt>do</tt> contain CGI scripts, should depend on
+ <tt>httpd-cgi</tt>.
+ </p>
+ </item>
+ </enumlist>
+ </p>
+ </sect>
<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>
- <p>
- You will need to depend on <tt>liblockfile1
- (>>1.01)</tt> to use these functions.
- </p>
+ You will need to depend on <tt>liblockfile1 (>>1.01)</tt>
+ to use these functions.
</footnote> packages is the recommended way to realize this.
</p>
</p>
<p>
- Such package should check for the existence of this file
+ Such a package should check for the existence of this file
when it is being configured. If it exists, it should be
used without comment, although an MTA's configuration script
may wish to prompt the user even if it finds that this file
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 entirety of the rest of the command
+ line as a command to pass straight to exec, in the
+ manner that <tt>xterm</tt> does.
+ </item>
- <item><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
</p>
</item>
+ <item>
+ If the window manager complies with <url
+ id="http://www.freedesktop.org/Standards/wm-spec"
+ name="The Window Manager Specification Project">,
+ written by the <url id="http://www.freedesktop.org/"
+ name="Free Desktop Group">, add 40 points.
+ </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
- renderers, or any other purpose, do not fit this
+ renderer, or any other purpose, do not fit this
definition. Any tool which makes such fonts available
to the X Window System, however, must abide by this
font policy.
- </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 the local file system or over the network
from an X font server; the Debian package system
is empowered to deal only with the local
- filesystem.
- </p>
+ file system.
</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>xfonts-utils</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>
+ <file>/usr/share/fonts/X11/100dpi/</file>.
+ </item>
- <item><p>
+ <item>
75 dpi fonts must be placed in
- <file>/usr/X11R6/lib/X11/fonts/75dpi/</file>.
- </p></item>
+ <file>/usr/share/fonts/X11/75dpi/</file>.
+ </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>
+ <file>/usr/share/fonts/X11/misc/</file>.
+ </item>
</list>
- </p>
</item>
- <item><p>
+ <item>
Speedo fonts must be placed in
- <file>/usr/X11R6/lib/X11/fonts/Speedo/</file>.
- </p></item>
+ <file>/usr/share/fonts/X11/Speedo/</file>.
+ </item>
- <item><p>
+ <item>
Type 1 fonts must be placed in
- <file>/usr/X11R6/lib/X11/fonts/Type1/</file>. If font
+ <file>/usr/share/fonts/X11/Type1/</file>. If font
metric files are available, they must be placed here
as well.
- </p></item>
+ </item>
<item>
- <p>
- Subdirectories of <file>/usr/X11R6/lib/X11/fonts/</file>
+ Subdirectories of <file>/usr/share/fonts/X11/</file>
other than those listed above must be neither
created nor used. (The <file>PEX</file>, <file>CID</file>,
and <file>cyrillic</file> directories are excepted for
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
<file>/etc/X11/fonts/<var>fontdir</var>/<var>package</var>.<var>extension</var></file>,
where <var>fontdir</var> is the name of the
subdirectory of
- <file>/usr/X11R6/lib/X11/fonts/</file> where the
+ <file>/usr/share/fonts/X11/</file> where the
package's corresponding fonts are stored
(e.g., <tt>75dpi</tt> or <tt>misc</tt>),
<var>package</var> is the name of the package
<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
+ <tt>xfonts-utils</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
+ binary on the local file system, 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
<p>
Packages using the X Window System should not be
- configured to install files under the <file>/usr/X11R6/</file>
- directory unless they use <prgn>imake</prgn>. The
+ configured to install files under the
+ <file>/usr/X11R6/</file> directory. The
<file>/usr/X11R6/</file> directory hierarchy should be
- regarded as deprecated for all packages except the X
- Window System itself, and those which use the
- <prgn>imake</prgn> program it provides, in which case the
- packages may transition out of the <file>/usr/X11R6/</file>
- directory at the maintainer's discretion.<footnote>
- <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
- are derived wholly from the X Window System
- configuration. Thus, in the event that the X Window
- System moves to <file>/usr/X11R7/</file>,
- <file>/usr/X12/</file>, or just plain <file>/usr/</file>, all
- that is required for these programs is a recompile
- against the corresponding X Window System library
- development packages.
- </p>
- </footnote>
+ regarded as obsolete.
+ </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;
+ <file>/usr/X11R6/lib/X11/</file> is now prohibited;
package maintainers should determine if subdirectories of
<file>/usr/lib/</file> and <file>/usr/share/</file> can be used
- instead. (The use of symbolic links from the
- <file>X11R6</file> directories to other FHS-compliant
- locations is encouraged if the program is not easily
- configured to look elsewhere for its files.) Packages
- must not provide or install files into the directories
- <file>/usr/bin/X11/</file>, <file>/usr/include/X11/</file> or
- <file>/usr/lib/X11/</file>. Files within a package should,
- however, make reference to these directories, rather than
- their <tt>X11R6</tt>-named counterparts
- <file>/usr/X11R6/bin/</file>, <file>/usr/X11R6/include/X11/</file>
- and <file>/usr/X11R6/lib/X11/</file>, if the resources being
- referred to have not been moved to other FHS-compliant
- locations.
+ instead.
+ </p>
+
+ <p>
+ Packages should install any relevant files into the
+ directories <file>/usr/include/X11/</file> and
+ <file>/usr/lib/X11/</file>, but if they do so, they must
+ pre-depend on <tt>x11-common (>=
+ 1:7.0.0)</tt><footnote>
+ <p>
+ These libraries used to be all symbolic
+ links. However, with <tt>X11R7</tt>,
+ <tt>/usr/include/X11</tt> and <tt>/usr/lib/X11</tt>
+ are now real directories, and packages
+ <strong>should</strong> ship their files here instead
+ of in <tt>/usr/X11R6/{include,lib}/X11</tt>.
+ <tt>x11-common (>= 1:7.0.0) </tt> is the package
+ responsible for converting these symlinks into
+ directories.
+ </p>
+ </footnote>
</p>
</sect1>
<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
binaries linked against the library (whether statically or
dynamically), it is the package maintainer's
responsibility to determine whether this is permitted by
- the license of the copy of Motif in his or her possession.
+ the license of the copy of Motif in their possession.
</p>
</sect1>
</sect>
- <sect>
+ <sect id="perl">
<heading>Perl programs and modules</heading>
+
<p>
- Perl programs and modules should follow the current Perl
- policy as defined in the file found on
- <ftpsite>ftp.debian.org</ftpsite> in
- <ftppath>/debian/doc/package-developer/perl-policy.txt.gz</ftppath>
- or your local mirror. In addition, it is included in the
- <tt>debian-policy</tt> package.
+ Perl programs and modules should follow the current Perl policy.
+ </p>
+
+ <p>
+ The Perl policy can be found in the <tt>perl-policy</tt>
+ files in the <tt>debian-policy</tt> package.
+ It is also available from the Debian web mirrors at
+ <tt><url name="/doc/packaging-manuals/perl-policy/"
+ id="http://www.debian.org/doc/packaging-manuals/perl-policy/"></tt>.
</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>
Games which require protected, privileged access to
- high-score files, savegames, etc., may be made
+ high-score files, saved games, etc., may be made
set-<em>group</em>-id (mode 2755) and owned by
<tt>root.games</tt>, and use files and directories with
appropriate permissions (770 <tt>root.games</tt>, for
</sect>
</chapt>
- <chapt id="docs"><heading>Documentation</heading>
+ <chapt id="docs">
+ <heading>Documentation</heading>
<sect>
<heading>Manual pages</heading>
<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 pre-formatted "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 man page is available.<footnote>
+ It is not very hard to write a man page. See the
+ <url id="http://www.schweikhardt.net/man_page_howto.html"
+ name="Man-Page-HOWTO">,
+ <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
+ You may forward a complaint about a missing man page to the
upstream authors, and mark the bug as forwarded in the
Debian bug tracking system. Even though the GNU Project do
- not in general consider the lack of a manpage to be a bug,
+ not in general consider the lack of a man page to be a bug,
we do; if they tell you that they don't consider it a bug
you should leave the bug in our bug tracking system open
- anyway.</p>
+ 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
+ If one man page needs to be accessible via several names it
is better to use a symbolic link than the <file>.so</file>
feature, but there is no need to fiddle with the relevant
parts of the upstream source to change from <file>.so</file> to
symlinks: don't do it unless it's easy. You should not
create hard links in the manual page directories, nor put
absolute filenames in <file>.so</file> directives. The filename
- in a <file>.so</file> in a manpage should be relative to the
- base of the manpage tree (usually
+ in a <file>.so</file> in a man page should be relative to the
+ base of the man page tree (usually
<file>/usr/share/man</file>). If you do not create any links
(whether symlinks, hard links, or <tt>.so</tt> directives)
- in the filesystem to the alternate names of the manpage,
+ in the file system to the alternate names of the man page,
then you should not rely on <prgn>man</prgn> finding your
- manpage under those names based solely on the information in
- the manpage's header.<footnote>
- <p>
+ man page under those names based solely on the information in
+ the man page's header.<footnote>
Supporting this in <prgn>man</prgn> often requires
unreasonable processing time to find a manual page or to
report that none exists, and moves knowledge into man's
- database that would be better left in the filesystem.
+ database that would be better left in the file system.
This support is therefore deprecated and will cease to
be present in the future.
- </p>
</footnote>
</p>
+
+ <p>
+ Manual pages in locale-specific subdirectories of
+ <file>/usr/share/man</file> should use either UTF-8 or the usual
+ legacy encoding for that language (normally the one corresponding
+ to the shortest relevant locale name in
+ <file>/usr/share/i18n/SUPPORTED</file>). For example, pages under
+ <file>/usr/share/man/fr</file> should use either UTF-8 or
+ ISO-8859-1.<footnote>
+ <prgn>man</prgn> will automatically detect whether UTF-8 is in
+ use. In future, all manual pages will be required to use
+ UTF-8.
+ </footnote>
+ </p>
+
+ <p>
+ A country name (the <tt>DE</tt> in <tt>de_DE</tt>) should not be
+ included in the subdirectory name unless it indicates a
+ significant difference in the language, as this excludes
+ speakers of the language in other countries.<footnote>
+ At the time of writing, Chinese and Portuguese are the main
+ languages with such differences, so <file>pt_BR</file>,
+ <file>zh_CN</file>, and <file>zh_TW</file> are all allowed.
+ </footnote>
+ </p>
+
+ <p>
+ Due to limitations in current implementations, all characters
+ in the manual page source should be representable in the usual
+ legacy encoding for that language, even if the file is
+ actually encoded in UTF-8. Safe alternative ways to write many
+ characters outside that range may be found in
+ <manref name="groff_char" section="7">.
+ </p>
</sect>
<sect>
<p>
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
<p>
Any additional documentation that comes with the package may
be installed at the discretion of the package maintainer.
- Text documentation should be installed in the directory
+ Plain text documentation should be installed in the directory
<file>/usr/share/doc/<var>package</var></file>, where
<var>package</var> is the name of the package, and
- compressed with <tt>gzip -9</tt> unless it is small.</p>
+ compressed with <tt>gzip -9</tt> unless it is small.
+ </p>
<p>
If a package comes with large amounts of documentation which
a separate binary package to contain it, so that it does not
take up disk space on the machines of users who do not need
or want it installed.</p>
-
- <p>
- It is often a good idea to put text information files
- (<file>README</file>s, changelogs, and so forth) that come with
- the source package in <file>/usr/share/doc/<var>package</var></file>
- in the binary package. However, you don't need to install
- the instructions for building and installing the package, of
- course!</p>
-
- <p>
- Files in <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>.
- </p>
-
- </sect>
-
- <sect id="usrdoc">
- <heading>Accessing the documentation</heading>
-
- <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>
- </p>
- </sect>
-
- <sect>
- <heading>Preferred documentation formats</heading>
-
- <p>
- The unification of Debian documentation is being carried out
- via HTML.</p>
-
- <p>
- If your package comes with extensive documentation in a
- markup format that can be converted to various other formats
- you should if possible ship HTML versions in a binary
- 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>
- Other formats such as PostScript may be provided at the
- package maintainer's discretion.
- </p>
- </sect>
-
- <sect id="copyrightfile">
- <heading>Copyright information</heading>
-
- <p>
- Every package must be accompanied by a verbatim copy of its
- copyright and distribution license in the file
- <file>/usr/share/doc/<var>package</var>/copyright</file>. This
- file must neither be compressed nor be a symbolic link.
- </p>
-
- <p>
- In addition, the copyright file must say where the upstream
- sources (if any) were obtained, and should explain briefly what
- modifications were made in the Debian version of the package
- compared to the upstream one. It should name the original
- authors of the package and the Debian maintainer(s) who were
- involved with its creation.</p>
-
- <p>
- A copy of the file which will be installed in
- <file>/usr/share/doc/<var>package</var>/copyright</file> should
- be in <file>debian/copyright</file> in the source package.
- </p>
-
- <p>
- <file>/usr/share/doc/<var>package</var></file> may be a symbolic
- link to another directory in <file>/usr/share/doc</file> only if
- the two packages both come from the same source and the
- first package Depends on the second. These rules are
- important because copyrights must be extractable by
- mechanical means.
- </p>
-
- <p>
- Packages distributed under the UCB BSD license, the Artistic
- license, the GNU GPL, and the GNU LGPL should refer to the
- files <file>/usr/share/common-licenses/BSD</file>,
- <file>/usr/share/common-licenses/Artistic</file>,
- <file>/usr/share/common-licenses/GPL</file>, and
- <file>/usr/share/common-licenses/LGPL</file> respectively,
- rather than quoting them in the copyright file.
- </p>
-
- <p>
- You should not use the copyright file as a general <file>README</file>
- file. If your package has such a file it should be
- installed in <file>/usr/share/doc/<var>package</var>/README</file> or
- <file>README.Debian</file> or some other appropriate place.</p>
- </sect>
-
- <sect>
- <heading>Examples</heading>
-
- <p>
- Any examples (configurations, source files, whatever),
- should be installed in a directory
- <file>/usr/share/doc/<var>package</var>/examples</file>. These
- files should not be referenced by any program: they're there
- for the benefit of the system administrator and users as
- documentation only. Architecture-specific example files
- should be installed in a directory
- <file>/usr/lib/<var>package</var>/examples</file> with symbolic
- links to them from
- <file>/usr/share/doc/<var>package</var>/examples</file>, or the
- latter directory itself may be a symbolic link to the
- former.
- </p>
- </sect>
-
- <sect id="instchangelog">
- <heading>Changelog files</heading>
-
- <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>/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
- <file>/usr/share/doc/<var>package</var>/changelog.html.gz</file>
- and a plain text <file>changelog.gz</file> should be generated
- from it using, for example, <tt>lynx -dump -nolist</tt>. If
- the upstream changelog files do not already conform to this
- naming convention, then this may be achieved either by
- renaming the files, or by adding a symbolic link, at the
- maintainer's discretion.<footnote>
- <p>
- Rationale: People should not have to look in places for
- upstream changelogs merely because they are given
- different names or are distributed in HTML format.
- </p>
- </footnote>
- </p>
-
- <p>
- All of these files should be installed compressed using
- <tt>gzip -9</tt>, as they will become large with time even
- if they start out small.
- </p>
-
- <p>
- If the package has only one changelog which is used both as
- the Debian changelog and the upstream one because there is
- no separate upstream maintainer then that changelog should
- usually be installed as
- <file>/usr/share/doc/<var>package</var>/changelog.gz</file>; if
- there is a separate upstream maintainer, but no upstream
- changelog, then the Debian changelog should still be called
- <file>changelog.Debian.gz</file>.</p>
- </sect>
- </chapt>
-
- <appendix id="pkg-scope">
- <heading>Introduction and scope of these appendices</heading>
-
- <p>
- These appendices are taken essentially verbatim from the
- now-deprecated Packaging Manual, version 3.2.1.0. They are
- the chapters which are likely to be of use to package
- maintainers and which have not already been included in the
- policy document itself. Most of these sections are very likely
- not relevant to policy; they should be treated as
- documentation for the packaging system. Please note that these
- appendices are included for convenience, and for historical
- reasons: they used to be part of policy package, and they have
- not yet been incorporated into dpkg documentation. However,
- they still have value, and hence they are presented here.
- </p>
- <p>
- They have not yet been checked to ensure that they are
- compatible with the contents of policy, and if there are any
- contradictions, the version in the main policy document takes
- precedence. The remaining chapters of the old Packaging
- Manual have also not been read in detail to ensure that there
- are not parts which have been left out. Both of these will be
- done in due course.
- </p>
-
- <p>
- <prgn>dpkg</prgn> is a suite of programs for creating binary
- package files and installing and removing them on Unix
- systems.<footnote>
- <p>
- <prgn>dpkg</prgn> is targetted primarily at Debian
- GNU/Linux, but may work on or be ported to other
- systems.
- </p>
- </footnote>
- </p>
-
- <p>
- The binary packages are designed for the management of
- installed executable programs (usually compiled binaries) and
- their associated data, though source code examples and
- documentation are provided as part of some packages.</p>
-
- <p>
- This manual describes the technical aspects of creating Debian
- binary packages (<file>.deb</file> files). It documents the
- behaviour of the package management programs
- <prgn>dpkg</prgn>, <prgn>dselect</prgn> et al. and the way
- they interact with packages.</p>
-
- <p>
- It also documents the interaction between
- <prgn>dselect</prgn>'s core and the access method scripts it
- uses to actually install the selected packages, and describes
- how to create a new access method.</p>
-
- <p>
- This manual does not go into detail about the options and
- usage of the package building and installation tools. It
- should therefore be read in conjuction with those programs'
- manpages.
- </p>
-
- <p>
- The utility programs which are provided with <prgn>dpkg</prgn>
- for managing various system configuration and similar issues,
- such as <prgn>update-rc.d</prgn> and
- <prgn>install-info</prgn>, are not described in detail here -
- please see their manpages.
- </p>
-
- <p>
- It 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
- packages. The Debian <prgn>debmake</prgn> package is
- recommended as a very helpful tool in creating and maintaining
- Debian packages. However, while the tools and examples are
- helpful, they do not replace the need to read and follow the
- Policy and Programmer's Manual.</p>
- </appendix>
-
- <appendix id="pkg-binarypkg"><heading>Binary packages (from old
- Packaging Manual)
- </heading>
-
- <p>
- The binary package has two main sections. The first part
- consists of various control information files and scripts used
- by <prgn>dpkg</prgn> when installing and removing. See <ref
- id="pkg-controlarea">.
- </p>
-
- <p>
- The second part is an archive containing the files and
- directories to be installed.
- </p>
-
- <p>
- In the future binary packages may also contain other
- components, such as checksums and digital signatures. The
- format for the archive is described in full in the
- <file>deb(5)</file> manpage.
- </p>
-
-
- <sect id="pkg-bincreating"><heading>Creating package files -
- <prgn>dpkg-deb</prgn>
- </heading>
-
+
<p>
- All manipulation of binary package files is done by
- <prgn>dpkg-deb</prgn>; it's the only program that has
- knowledge of the format. (<prgn>dpkg-deb</prgn> may be
- invoked by calling <prgn>dpkg</prgn>, as <prgn>dpkg</prgn>
- will spot that the options requested are appropriate to
- <prgn>dpkg-deb</prgn> and invoke that instead with the same
- arguments.)
- </p>
-
+ It is often a good idea to put text information files
+ (<file>README</file>s, changelogs, and so forth) that come with
+ the source package in <file>/usr/share/doc/<var>package</var></file>
+ in the binary package. However, you don't need to install
+ the instructions for building and installing the package, of
+ course!</p>
+
<p>
- In order to create a binary package you must make a
- directory tree which contains all the files and directories
- you want to have in the filesystem data part of the package.
- In Debian-format source packages this directory is usually
- <file>debian/tmp</file>, relative to the top of the package's
- source tree.
+ Packages must not require the existence 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 stand alone documentation should be installed under
+ <file>/usr/share/<var>package</var>/</file> with symbolic links from
+ <file>/usr/share/doc/<var>package</var></file>.
</p>
-
+
<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.
+ <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.<footnote>
+ <p>
+ Please note that this does not override the section on
+ changelog files below, so the file
+ <file>/usr/share/<var>package</var>/changelog.Debian.gz</file>
+ must refer to the changelog for the current version of
+ <var>package</var> in question. In practice, this means
+ that the sources of the target and the destination of the
+ symlink must be the same (same source package and
+ version).
+ </p>
+ </footnote>
</p>
-
+
<p>
- 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.
+ Former Debian releases placed all additional documentation
+ 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>
+
+ <sect>
+ <heading>Preferred documentation formats</heading>
+
<p>
- You need to add one special directory to the root of the
- miniature filesystem tree you're creating:
- <prgn>DEBIAN</prgn>. It should contain the control
- information files, notably the binary package control file
- (see <ref id="pkg-controlfile">).
- </p>
-
+ The unification of Debian documentation is being carried out
+ via HTML.</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.
+ If your package comes with extensive documentation in a
+ markup format that can be converted to various other formats
+ you should if possible ship HTML versions in a binary
+ package, in the directory
+ <file>/usr/share/doc/<var>appropriate-package</var></file> or
+ its subdirectories.<footnote>
+ 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.
+ </footnote>
</p>
-
+
<p>
- When you've prepared the package, you should invoke:
- <example>
- dpkg --build <var>directory</var>
- </example>
+ Other formats such as PostScript may be provided at the
+ package maintainer's discretion.
</p>
-
+ </sect>
+
+ <sect id="copyrightfile">
+ <heading>Copyright information</heading>
+
<p>
- This will build the package in
- <file><var>directory</var>.deb</file>. (<prgn>dpkg</prgn> knows
- that <tt>--build</tt> is a <prgn>dpkg-deb</prgn> option, so
- it invokes <prgn>dpkg-deb</prgn> with the same arguments to
- build the package.)
+ Every package must be accompanied by a verbatim copy of its
+ copyright and distribution license in the file
+ <file>/usr/share/doc/<var>package</var>/copyright</file>. This
+ file must neither be compressed nor be a symbolic link.
</p>
-
+
<p>
- See the manpage <manref name="dpkg-deb" section="8"> for details of how
- to examine the contents of this newly-created file. You may find the
- output of following commands enlightening:
- <example>
- dpkg-deb --info <var>filename</var>.deb
- dpkg-deb --contents <var>filename</var>.deb
- dpkg --contents <var>filename</var>.deb
- </example>
- To view the copyright file for a package you could use this command:
- <example>
- dpkg --fsys-tarfile <var>filename</var>.deb | tar xof usr/share/doc/<var>\*</var>copyright | less
- </example>
+ In addition, the copyright file must say where the upstream
+ sources (if any) were obtained. It should name the original
+ authors of the package and the Debian maintainer(s) who were
+ involved with its creation.
</p>
- </sect>
- <sect id="pkg-controlarea">
- <heading>
- Package control information files
- </heading>
-
<p>
- The control information portion of a binary package is a
- collection of files with names known to <prgn>dpkg</prgn>.
- It will treat the contents of these files specially - some
- of them contain information used by <prgn>dpkg</prgn> when
- installing or removing the package; others are scripts which
- the package maintainer wants <prgn>dpkg</prgn> to run.
+ Packages in the <em>contrib</em> or <em>non-free</em> categories
+ should state in the copyright file that the package is not part
+ of the Debian GNU/Linux distribution and briefly explain why.
</p>
-
+
<p>
- 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).
+ A copy of the file which will be installed in
+ <file>/usr/share/doc/<var>package</var>/copyright</file> should
+ be in <file>debian/copyright</file> in the source package.
</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.
+ <file>/usr/share/doc/<var>package</var></file> may be a symbolic
+ link to another directory in <file>/usr/share/doc</file> only if
+ the two packages both come from the same source and the
+ first package Depends on the second. These rules are
+ important because copyrights must be extractable by
+ mechanical means.
</p>
-
+
<p>
- <taglist>
- <tag><tt>control</tt>
- <item>
-
- <p>
- This is the key description file used by
- <prgn>dpkg</prgn>. It specifies the package's name
- and version, gives its description for the user,
- states its relationships with other packages, and so
- forth. See <ref id="pkg-controlfile">.
- </p>
-
- <p>
- It is usually generated automatically from information
- in the source package by the
- <prgn>dpkg-gencontrol</prgn> program, and with
- assistance from <prgn>dpkg-shlibdeps</prgn>. See <ref
- id="pkg-sourcetools">.</p>
- </item>
-
- <tag><tt>postinst</tt>, <tt>preinst</tt>, <tt>postrm</tt>,
- <tt>prerm</tt>
- </tag>
- <item>
-
- <p>
- These are exectuable files (usually scripts) which
- <prgn>dpkg</prgn> runs during installation, upgrade
- and removal of packages. They allow the package to
- deal with matters which are particular to that package
- or require more complicated processing than that
- provided by <prgn>dpkg</prgn>. Details of when and
- how they are called are in <ref
- id="maintainerscripts">.
- </p>
-
- <p>
- It is very important to make these scripts
- idempotent.
- <footnote>
- <p>
- That means that if it runs successfully or fails
- and then you call it again it doesn't bomb out,
- but just ensures that everything is the way it
- ought to be.
- </p>
- </footnote> This is so that if an error occurs, the
- user interrupts <prgn>dpkg</prgn> or some other
- unforeseen circumstance happens you don't leave the
- user with a badly-broken package.
- </p>
-
- <p>
- The maintainer scripts are guaranteed to run with a
- controlling terminal and can interact with the user.
- If they need to prompt for passwords, do full-screen
- interaction or something similar you should do these
- things to and from <file>/dev/tty</file>, since
- <prgn>dpkg</prgn> will at some point redirect scripts'
- standard input and output so that it can log the
- installation process. Likewise, because these scripts
- may be executed with standard output redirected into a
- pipe for logging purposes, Perl scripts should set
- unbuffered output by setting <tt>$|=1</tt> so that the
- output is printed immediately rather than being
- buffered.
- </p>
-
- <p>
- Each script should return a zero exit status for
- success, or a nonzero one for failure.</p>
- </item>
-
- <tag><tt>conffiles</tt>
- </tag>
- <item>
-
- <p>
- This file contains a list of configuration files which
- are to be handled automatically by <prgn>dpkg</prgn>
- (see <ref id="pkg-conffiles">). Note that not necessarily
- every configuration file should be listed here.</p>
- </item>
-
- <tag><tt>shlibs</tt>
- </tag>
- <item>
-
- <p>
- This file contains a list of the shared libraries
- supplied by the package, with dependency details for
- each. This is used by <prgn>dpkg-shlibdeps</prgn>
- when it determines what dependencies are required in a
- package control file. The <tt>shlibs</tt> file format
- is described on <ref id="shlibs">.
- </p>
- </item>
- </taglist>
+ Packages distributed under the UCB BSD license, the Apache
+ license (version 2.0), the Artistic license, the GNU GPL
+ (version 2 or 3), the GNU LGPL (versions 2, 2.1, or 3), and
+ the GNU FDL (version 1.2) should refer to the corresponding
+ files under <file>/usr/share/common-licenses</file>,<footnote>
+ <p>
+ In particular,
+ <file>/usr/share/common-licenses/BSD</file>,
+ <file>/usr/share/common-licenses/Apache-2.0</file>,
+ <file>/usr/share/common-licenses/Artistic</file>,
+ <file>/usr/share/common-licenses/GPL-2</file>,
+ <file>/usr/share/common-licenses/GPL-3</file>,
+ <file>/usr/share/common-licenses/LGPL-2</file>,
+ <file>/usr/share/common-licenses/LGPL-2.1</file>,
+ <file>/usr/share/common-licenses/LGPL-3</file>, and
+ <file>/usr/share/common-licenses/GFDL-1.2</file>
+ respectively.
+ </p>
+ </footnote> rather than quoting them in the copyright
+ file.
</p>
-
- <sect id="pkg-controlfile">
- <heading>
- The main control information file: <tt>control</tt>
- </heading>
+
<p>
- The most important control information file used by
- <prgn>dpkg</prgn> when it installs a package is
- <tt>control</tt>. It contains all the package's `vital
- statistics'.
+ You should not use the copyright file as a general <file>README</file>
+ file. If your package has such a file it should be
+ installed in <file>/usr/share/doc/<var>package</var>/README</file> or
+ <file>README.Debian</file> or some other appropriate place.</p>
+ </sect>
+
+ <sect>
+ <heading>Examples</heading>
+
+ <p>
+ Any examples (configurations, source files, whatever),
+ should be installed in a directory
+ <file>/usr/share/doc/<var>package</var>/examples</file>. These
+ files should not be referenced by any program: they're there
+ for the benefit of the system administrator and users as
+ documentation only. Architecture-specific example files
+ should be installed in a directory
+ <file>/usr/lib/<var>package</var>/examples</file> with symbolic
+ links to them from
+ <file>/usr/share/doc/<var>package</var>/examples</file>, or the
+ latter directory itself may be a symbolic link to the
+ former.
</p>
- <p>
- The binary package control files of packages built from
- Debian sources are made by a special tool,
- <prgn>dpkg-gencontrol</prgn>, which reads
- <file>debian/control</file> and <file>debian/changelog</file> to
- find the information it needs. See <ref id="pkg-sourcepkg"> for
- more details.
+ <p>
+ 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="changelogs">
+ <heading>Changelog files</heading>
+
+ <p>
+ Packages that are not Debian-native must contain a
+ compressed copy of the <file>debian/changelog</file> file from
+ the Debian source tree in
+ <file>/usr/share/doc/<var>package</var></file> with the name
+ <file>changelog.Debian.gz</file>.
+ </p>
+
+ <p>
+ If an upstream changelog is available, it should be accessible as
+ <file>/usr/share/doc/<var>package</var>/changelog.gz</file> in
+ plain text. If the upstream changelog is distributed in
+ HTML, it should be made available in that form as
+ <file>/usr/share/doc/<var>package</var>/changelog.html.gz</file>
+ and a plain text <file>changelog.gz</file> should be generated
+ from it using, for example, <tt>lynx -dump -nolist</tt>. If
+ the upstream changelog files do not already conform to this
+ naming convention, then this may be achieved either by
+ renaming the files, or by adding a symbolic link, at the
+ maintainer's discretion.<footnote>
+ 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.
+ </footnote>
</p>
- <p>
- The fields in binary package control files are:
- <list compact="compact">
- <item>
- <p><qref id="pkg-f-Package"><tt>Package</tt></qref> (mandatory)</p>
- </item>
- <item>
- <p><qref id="versions"><tt>Version</tt></qref> (mandatory)</p>
- </item>
- <item><p><qref id="pkg-f-Architecture"><tt>Architecture</tt></qref>
- (mandatory)
- <footnote>
- <p>
- This field should appear in all packages, though
- <prgn>dpkg</prgn> doesn't require it yet so that
- old packages can still be installed.
- </p>
- </footnote>
- </p>
- </item>
- <item>
- <p><qref id="relationships"><tt>Depends</tt>,
- <tt>Provides</tt> et al.</qref></p>
- </item>
- <item>
- <p><qref id="pkg-f-Essential"><tt>Essential</tt></qref></p>
- </item>
- <item>
- <p><qref id="pkg-f-Maintainer"><tt>Maintainer</tt></qref></p>
- </item>
- <item>
- <p><qref id="pkg-f-classification"><tt>Section</tt>,
- <tt>Priority</tt></qref></p>
- </item>
- <item>
- <p><qref id="pkg-f-Source"><tt>Source</tt></qref></p>
- </item>
- <item>
- <p><qref id="descriptions"><tt>Description</tt></qref></p>
- </item>
- <item>
- <p>
- <qref id="pkg-f-Installed-Size"><tt>Installed-Size</tt></qref>
- </p>
- </item>
- </list>
-
<p>
- A description of the syntax of control files and the purpose
- of these fields is available in <ref id="pkg-controlfields">.
+ All of these files should be installed compressed using
+ <tt>gzip -9</tt>, as they will become large with time even
+ if they start out small.
</p>
- </sect>
- <sect>
- <heading>Time Stamps</heading>
<p>
- Maintainers are encouraged to preserve the modification
- times of the upstream source files in a package, as far as
- is reasonably possible.
- <footnote>
- <p>
- The rationale is that there is some information conveyed
- by knowing the age of the file, for example, you could
- recognize that some documentation is very old by looking
- at the modification time, so it would be nice if the
- modification time of the upstream source would be
- preserved.
- </p>
- </footnote>
+ If the package has only one changelog which is used both as
+ the Debian changelog and the upstream one because there is
+ no separate upstream maintainer then that changelog should
+ usually be installed as
+ <file>/usr/share/doc/<var>package</var>/changelog.gz</file>; if
+ there is a separate upstream maintainer, but no upstream
+ changelog, then the Debian changelog should still be called
+ <file>changelog.Debian.gz</file>.
+ </p>
+
+ <p>
+ For details about the format and contents of the Debian
+ changelog file, please see <ref id="dpkgchangelog">.
</p>
</sect>
- </appendix>
+ </chapt>
- <appendix id="pkg-sourcepkg">
- <heading>Source packages (from old Packaging Manual) </heading>
+ <appendix id="pkg-scope">
+ <heading>Introduction and scope of these appendices</heading>
- <p>
- The Debian binary packages in the distribution are generated
- from Debian sources, which are in a special format to assist
- the easy and automatic building of binaries.
+ <p>
+ These appendices are taken essentially verbatim from the
+ now-deprecated Packaging Manual, version 3.2.1.0. They are
+ the chapters which are likely to be of use to package
+ maintainers and which have not already been included in the
+ policy document itself. Most of these sections are very likely
+ not relevant to policy; they should be treated as
+ documentation for the packaging system. Please note that these
+ appendices are included for convenience, and for historical
+ reasons: they used to be part of policy package, and they have
+ not yet been incorporated into dpkg documentation. However,
+ they still have value, and hence they are presented here.
</p>
- <p>
- 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>
+ They have not yet been checked to ensure that they are
+ compatible with the contents of policy, and if there are any
+ contradictions, the version in the main policy document takes
+ precedence. The remaining chapters of the old Packaging
+ Manual have also not been read in detail to ensure that there
+ are not parts which have been left out. Both of these will be
+ done in due course.
</p>
-
- <sect id="pkg-sourcetools">
- <heading>Tools for processing source packages</heading>
- <p>
- Various tools are provided for manipulating source packages;
- they pack and unpack sources and help build of binary
- packages and help manage the distribution of new versions.
- </p>
+ <p>
+ Certain parts of the Packaging manual were integrated into the
+ Policy Manual proper, and removed from the appendices. Links
+ have been placed from the old locations to the new ones.
+ </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>
+ <prgn>dpkg</prgn> is a suite of programs for creating binary
+ package files and installing and removing them on Unix
+ systems.<footnote>
+ <prgn>dpkg</prgn> is targeted primarily at Debian
+ GNU/Linux, but may work on or be ported to other
+ systems.
+ </footnote>
+ </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>
+ The binary packages are designed for the management of
+ installed executable programs (usually compiled binaries) and
+ their associated data, though source code examples and
+ documentation are provided as part of some packages.</p>
- <p>
- This program is frequently used by hand, and is also
- called from package-independent automated building scripts
- such as <prgn>dpkg-buildpackage</prgn>.
- </p>
+ <p>
+ This manual describes the technical aspects of creating Debian
+ binary packages (<file>.deb</file> files). It documents the
+ behavior of the package management programs
+ <prgn>dpkg</prgn>, <prgn>dselect</prgn> et al. and the way
+ they interact with packages.</p>
- <p>
- To unpack a package it is typically invoked with
- <example>
- dpkg-source -x <var>.../path/to/filename</var>.dsc
- </example>
- </p>
+ <p>
+ It also documents the interaction between
+ <prgn>dselect</prgn>'s core and the access method scripts it
+ uses to actually install the selected packages, and describes
+ how to create a new access method.</p>
- <p>
- with the <file><var>filename</var>.tar.gz</file> and
- <file><var>filename</var>.diff.gz</file> (if applicable) in
- the same directory. It unpacks into
- <file><var>package</var>-<var>version</var></file>, and if
- applicable
- <file><var>package</var>-<var>version</var>.orig</file>, in
- the current directory.
- </p>
+ <p>
+ 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 conjunction with those programs'
+ man pages.
+ </p>
- <p>
- To create a packed source archive it is typically invoked:
- <example>
- dpkg-source -b <var>package</var>-<var>version</var>
- </example>
- </p>
+ <p>
+ The utility programs which are provided with <prgn>dpkg</prgn>
+ for managing various system configuration and similar issues,
+ such as <prgn>update-rc.d</prgn> and
+ <prgn>install-info</prgn>, are not described in detail here -
+ please see their man pages.
+ </p>
- <p>
- This will create the <file>.dsc</file>, <file>.tar.gz</file> and
- <file>.diff.gz</file> (if appropriate) in the current
- directory. <prgn>dpkg-source</prgn> does not clean the
- source tree first - this must be done separately if it is
- required.
- </p>
+ <p>
+ 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>
- See also <ref id="pkg-sourcearchives">.</p>
- </sect1>
-
-
- <sect1>
- <heading>
- <prgn>dpkg-buildpackage</prgn> - overall package-building
- control script
- </heading>
+ <p>
+ The Debian version of the FSF's GNU hello program is provided
+ as an example for people wishing to create Debian
+ packages. The Debian <prgn>debmake</prgn> package is
+ recommended as a very helpful tool in creating and maintaining
+ Debian packages. However, while the tools and examples are
+ helpful, they do not replace the need to read and follow the
+ Policy and Programmer's Manual.</p>
+ </appendix>
- <p>
- <prgn>dpkg-buildpackage</prgn> is a script which invokes
- <prgn>dpkg-source</prgn>, the <file>debian/rules</file>
- targets <tt>clean</tt>, <tt>build</tt> and
- <tt>binary</tt>, <prgn>dpkg-genchanges</prgn> and
- <prgn>pgp</prgn> to build a signed source and binary
- package upload.
- </p>
+ <appendix id="pkg-binarypkg">
+ <heading>Binary packages (from old Packaging Manual)</heading>
- <p>
- It is usually invoked by hand from the top level of the
- built or unbuilt source directory. It may be invoked with
- no arguments; useful arguments include:
- <taglist compact="compact">
- <tag><tt>-uc</tt>, <tt>-us</tt></tag>
- <item>
- <p>
- Do not PGP-sign the <tt>.changes</tt> file or the
- source package <tt>.dsc</tt> file, respectively.</p>
- </item>
- <tag><tt>-p<var>pgp-command</var></tt></tag>
- <item>
- <p>
- Invoke <var>pgp-command</var> instead of finding
- <tt>pgp</tt> on the <prgn>PATH</prgn>.
- <var>pgp-command</var> must behave just like
- <prgn>pgp</prgn>.</p>
- </item>
- <tag><tt>-r<var>root-command</var></tt></tag>
- <item>
- <p>
- When root privilege is required, invoke the command
- <var>root-command</var>. <var>root-command</var>
- should invoke its first argument as a command, from
- the <prgn>PATH</prgn> if necessary, and pass its
- second and subsequent arguments to the command it
- calls. If no <var>root-command</var> is supplied
- then <var>dpkg-buildpackage</var> will take no
- special action to gain root privilege, so that for
- most packages it will have to be invoked as root to
- start with.</p>
- </item>
- <tag><tt>-b</tt>, <tt>-B</tt></tag>
- <item>
- <p>
- Two types of binary-only build and upload - see
- <manref name="dpkg-source" section="1">.
- </p>
- </item>
- </taglist>
- </p>
- </sect1>
-
- <sect1>
- <heading>
- <prgn>dpkg-gencontrol</prgn> - generates binary package
- control files
- </heading>
+ <p>
+ 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>
- 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>
+ The second part is an archive containing the files and
+ directories to be installed.
+ </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>
+ 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> man page.
+ </p>
- <p>
- <prgn>dpkg-gencontrol</prgn> must be called after all the
- files which are to go into the package have been placed in
- the temporary build directory, so that its calculation of
- the installed size of a package is correct.
- </p>
- <p>
- It is also necessary for <prgn>dpkg-gencontrol</prgn> to
- be run after <prgn>dpkg-shlibdeps</prgn> so that the
- variable substitutions created by
- <prgn>dpkg-shlibdeps</prgn> in <file>debian/substvars</file>
- are available.
- </p>
+ <sect id="pkg-bincreating"><heading>Creating package files -
+ <prgn>dpkg-deb</prgn>
+ </heading>
+
+ <p>
+ All manipulation of binary package files is done by
+ <prgn>dpkg-deb</prgn>; it's the only program that has
+ knowledge of the format. (<prgn>dpkg-deb</prgn> may be
+ invoked by calling <prgn>dpkg</prgn>, as <prgn>dpkg</prgn>
+ will spot that the options requested are appropriate to
+ <prgn>dpkg-deb</prgn> and invoke that instead with the same
+ arguments.)
+ </p>
+
+ <p>
+ In order to create a binary package you must make a
+ directory tree which contains all the files and directories
+ you want to have in the file system data part of the package.
+ In Debian-format source packages this directory is usually
+ <file>debian/tmp</file>, relative to the top of the package's
+ source tree.
+ </p>
- <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>
+ 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>
- Sources which build several binaries will typically need
- something like:
- <example>
- dpkg-gencontrol -Pdebian/tmp-<var>pkg</var> -p<var>package</var>
- </example> The <tt>-P</tt> tells
- <prgn>dpkg-gencontrol</prgn> that the package is being
- built in a non-default directory, and the <tt>-p</tt>
- tells it which package's control file should be generated.
- </p>
+ <p>
+ 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>
- <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>
+ You need to add one special directory to the root of the
+ miniature file system tree you're creating:
+ <prgn>DEBIAN</prgn>. It should contain the control
+ information files, notably the binary package control file
+ (see <ref id="pkg-controlfile">).
+ </p>
- <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>
+ The <prgn>DEBIAN</prgn> directory will not appear in the
+ file system archive of the package, and so won't be installed
+ by <prgn>dpkg</prgn> when the package is installed.
+ </p>
- <p>
- Its arguments are executables.
- <footnote>
- <p>
- In a forthcoming dpkg version,
- <prgn>dpkg-shlibdeps</prgn> would be required to be
- called on shared libraries as well.
- </p>
- <p>
- They may be specified either in the locations in the
- source tree where they are created or in the locations
- in the temporary build tree where they are installed
- prior to binary package creation.
- </p>
- </footnote> for which shared library dependencies should
- be included in the binary package's control file.
- </p>
+ <p>
+ When you've prepared the package, you should invoke:
+ <example>
+ dpkg --build <var>directory</var>
+ </example>
+ </p>
- <p>
- If some of the found shared libraries should only
- warrant a <tt>Recommends</tt> or <tt>Suggests</tt>, or if
- some warrant a <tt>Pre-Depends</tt>, this can be achieved
- by using the <tt>-d<var>dependency-field</var></tt> option
- before those executable(s). (Each <tt>-d</tt> option
- takes effect until the next <tt>-d</tt>.)
- </p>
+ <p>
+ This will build the package in
+ <file><var>directory</var>.deb</file>. (<prgn>dpkg</prgn> knows
+ that <tt>--build</tt> is a <prgn>dpkg-deb</prgn> option, so
+ it invokes <prgn>dpkg-deb</prgn> with the same arguments to
+ build the package.)
+ </p>
- <p>
- <prgn>dpkg-shlibdeps</prgn> does not directly cause the
- output control file to be modified. Instead by default it
- adds to the <file>debian/substvars</file> file variable
- settings like <tt>shlibs:Depends</tt>. These variable
- settings must be referenced in dependency fields in the
- appropriate per-binary-package sections of the source
- control file.
- </p>
+ <p>
+ See the man page <manref name="dpkg-deb" section="8"> for details of how
+ to examine the contents of this newly-created file. You may find the
+ output of following commands enlightening:
+ <example>
+ dpkg-deb --info <var>filename</var>.deb
+ dpkg-deb --contents <var>filename</var>.deb
+ dpkg --contents <var>filename</var>.deb
+ </example>
+ To view the copyright file for a package you could use this command:
+ <example>
+ dpkg --fsys-tarfile <var>filename</var>.deb | tar xOf - \*/copyright | pager
+ </example>
+ </p>
+ </sect>
- <p>
- For example, the <prgn>procps</prgn> package generates two
- kinds of binaries, simple C binaries like <prgn>ps</prgn>
- which require a predependency and full-screen ncurses
- binaries like <prgn>top</prgn> which require only a
- recommendation. It can say in its <file>debian/rules</file>:
- <example>
- dpkg-shlibdeps -dPre-Depends ps -dRecommends top
- </example>
- and then in its main control file <file>debian/control</file>:
- <example>
- <var>...</var>
- Package: procps
- Pre-Depends: ${shlibs:Pre-Depends}
- Recommends: ${shlibs:Recommends}
- <var>...</var>
- </example>
- </p>
+ <sect id="pkg-controlarea">
+ <heading>Package control information files</heading>
- <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
- <prgn>dpkg-shlibdeps</prgn> per setting of this option).
- They can thus produce several sets of dependency
- variables, each of the form
- <tt><var>varnameprefix</var>:<var>dependencyfield</var></tt>,
- which can be referred to in the appropriate parts of the
- binary package control files.
- </p>
- </sect1>
-
-
- <sect1>
- <heading>
- <prgn>dpkg-distaddfile</prgn> - adds a file to
- <file>debian/files</file>
- </heading>
+ <p>
+ The control information portion of a binary package is a
+ collection of files with names known to <prgn>dpkg</prgn>.
+ It will treat the contents of these files specially - some
+ of them contain information used by <prgn>dpkg</prgn> when
+ installing or removing the package; others are scripts which
+ the package maintainer wants <prgn>dpkg</prgn> to run.
+ </p>
- <p>
- Some packages' uploads need to include files other than
- the source and binary package files.
- </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>
- <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>
+ 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>
- It is usually invoked from the <tt>binary</tt> target of
- <file>debian/rules</file>:
- <example>
- dpkg-distaddfile <var>filename</var> <var>section</var> <var>priority</var>
- </example>
- The <var>filename</var> is relative to the directory where
- <prgn>dpkg-genchanges</prgn> will expect to find it - this
- is usually the directory above the top level of the source
- tree. The <file>debian/rules</file> target should put the
- file there just before or just after calling
- <prgn>dpkg-distaddfile</prgn>.
- </p>
+ <p>
+ <taglist>
+ <tag><tt>control</tt>
+ <item>
+ <p>
+ This is the key description file used by
+ <prgn>dpkg</prgn>. It specifies the package's name
+ and version, gives its description for the user,
+ states its relationships with other packages, and so
+ forth. See <ref id="sourcecontrolfiles"> and
+ <ref id="binarycontrolfiles">.
+ </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>
+ It is usually generated automatically from information
+ in the source package by the
+ <prgn>dpkg-gencontrol</prgn> program, and with
+ assistance from <prgn>dpkg-shlibdeps</prgn>.
+ See <ref id="pkg-sourcetools">.
+ </p>
+ </item>
- <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>
+ <tag><tt>postinst</tt>, <tt>preinst</tt>, <tt>postrm</tt>,
+ <tt>prerm</tt>
+ </tag>
+ <item>
+ <p>
+ These are executable files (usually scripts) which
+ <prgn>dpkg</prgn> runs during installation, upgrade
+ and removal of packages. They allow the package to
+ deal with matters which are particular to that package
+ or require more complicated processing than that
+ provided by <prgn>dpkg</prgn>. Details of when and
+ how they are called are in <ref id="maintainerscripts">.
+ </p>
- <p>
- It is usually called in the top level of a built source
- tree, and when invoked with no arguments will print out a
- straightforward <file>.changes</file> file based on the
- information in the source package's changelog and control
- file and the binary and source packages which should have
- been built.
- </p>
- </sect1>
-
-
- <sect1><heading><prgn>dpkg-parsechangelog</prgn> - produces parsed representation of
- a changelog
- </heading>
+ <p>
+ It is very important to make these scripts idempotent.
+ See <ref id="idempotency">.
+ </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
- parses a changelog, <file>debian/changelog</file> by default,
- and prints a control-file format representation of the
- information in it to standard output.
- </p>
- </sect1>
-
- <sect1 id="pkg-dpkgarch"><heading><prgn>dpkg-architecture</prgn> -
- information about the build and host system
- </heading>
-
- <p>
- This program can be used manually, but is also invoked by
- <tt>dpkg-buildpackage</tt> or <file>debian/rules</file> to set
- to set environment or make variables which specify the build and
- host architecture for the package building process.
- </p>
- </sect1>
- </sect>
-
- <sect id="pkg-sourcetree"><heading>The Debianised source tree
- </heading>
+ <p>
+ The maintainer scripts are guaranteed to run with a
+ controlling terminal and can interact with the user.
+ See <ref id="controllingterminal">.
+ </p>
+ </item>
+
+ <tag><tt>conffiles</tt>
+ </tag>
+ <item>
+ 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.
+ </item>
- <p>
- The source archive scheme described later is intended to
- allow a Debianised source tree with some associated control
- information to be reproduced and transported easily. The
- Debianised source tree is a version of the original program
- with certain files added for the benefit of the
- Debianisation process, and with any other changes required
- made to the rest of the source code and installation
- scripts.
+ <tag><tt>shlibs</tt>
+ </tag>
+ <item>
+ This file contains a list of the shared libraries
+ supplied by the package, with dependency details for
+ each. This is used by <prgn>dpkg-shlibdeps</prgn>
+ when it determines what dependencies are required in a
+ package control file. The <tt>shlibs</tt> file format
+ is described on <ref id="shlibs">.
+ </item>
+ </taglist>
</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.
+ <sect id="pkg-controlfile">
+ <heading>The main control information file: <tt>control</tt></heading>
+
+ <p>
+ The most important control information file used by
+ <prgn>dpkg</prgn> when it installs a package is
+ <tt>control</tt>. It contains all the package's "vital
+ statistics".
</p>
-
- <sect1 id="pkg-debianrules"><heading><file>debian/rules</file> - the main building
- script
- </heading>
- <p>
- This file is an executable makefile, and contains the
- package-specific recipies for compiling the package and
- building binary package(s) out of the source.
- </p>
+ <p>
+ The binary package control files of packages built from
+ Debian sources are made by a special tool,
+ <prgn>dpkg-gencontrol</prgn>, which reads
+ <file>debian/control</file> and <file>debian/changelog</file> to
+ find the information it needs. See <ref id="pkg-sourcepkg"> for
+ more details.
+ </p>
- <p>
- It must start with the line <tt>#!/usr/bin/make -f</tt>,
- so that it can be invoked by saying its name rather than
- invoking <prgn>make</prgn> explicitly.
- </p>
+ <p>
+ The fields in binary package control files are listed in
+ <ref id="binarycontrolfiles">.
+ </p>
- <p>
- Since an interactive <file>debian/rules</file> script makes it
- impossible to autocompile that package and also makes it
- hard for other people to reproduce the same binary
- package, all <strong>required targets</strong> have to be
- non-interactive. At a minimul, required targets are the
- ones called by <prgn>dpkg-buildpackage</prgn>, namely,
- <em>clean</em>, <em>binary</em>, <em>binary-arch</em>, and
- <em>build</em>. It also follows that any target that these
- targets depend on must also be non-interactive.
- </p>
+ <p>
+ A description of the syntax of control files and the purpose
+ of the fields is available in <ref id="controlfields">.
+ </p>
+ </sect>
- <p>
- The targets which are required to be present are:
- <taglist>
- <tag><tt>build</tt></tag>
- <item>
- <p>
- This should perform all non-interactive
- configuration and compilation of the package. If a
- package has an interactive pre-build configuration
- routine, the Debianised source package should be
- built after this has taken place, so that it can be
- built without rerunning the configuration.
- </p>
-
- <p>
- A package may also provide both of the targets
- <tt>build-arch</tt> and <tt>build-indep</tt>. The
- <tt>build-arch</tt> target, if provided, should
- perform all non-interactive configuration and
- compilation required for producing all
- architecture-dependant binary packages (those packages
- for which the body of the <tt>Architecture</tt> field
- in <tt>debian/control</tt> is not <tt>all</tt>).
- Similarly, the <tt>build-indep</tt> target, if
- provided, should perform all non-interactive
- configuration and compilation required for producing
- all architecture-independent binary packages (those
- packages for which the body of the
- <tt>Architecture</tt> field in <tt>debian/control</tt>
- is <tt>all</tt>). The <tt>build</tt> target should
- depend on those of the targets <tt>build-arch</tt> and
- <tt>build-indep</tt> that are provided in the rules
- file.
- </p>
-
- <p>
- If one or both of the targets <tt>build-arch</tt> and
- <tt>build-indep</tt> are not provided, then invoking
- <file>debian/rules</file> with one of the not-provided
- targets as arguments should produce a exit status code
- of 2. Usually this is provided automatically by make
- if the target is missing.
- </p>
-
- <p>
- For some packages, notably ones where the same
- source tree is compiled in different ways to produce
- two binary packages, the <tt>build</tt> target does
- not make much sense. For these packages it is good
- enough to provide two (or more) targets
- (<tt>build-a</tt> and <tt>build-b</tt> or whatever)
- for each of the ways of building the package, and a
- <tt>build</tt> target that does nothing. The
- <tt>binary</tt> target will have to build the
- package in each of the possible ways and make the
- binary package out of each.
- </p>
+ <sect>
+ <heading>Time Stamps</heading>
- <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>
+ See <ref id="timestamps">.
+ </p>
+ </sect>
+ </appendix>
- <p>
- The <tt>build</tt> target may need to run
- <tt>clean</tt> first - see below.
- </p>
+ <appendix id="pkg-sourcepkg">
+ <heading>Source packages (from old Packaging Manual) </heading>
- <p>
- When a package has a configuration routine that takes
- a long time, or when the makefiles are poorly
- designed, or when <tt>build</tt> needs to run
- <tt>clean</tt> first, it is a good idea to <tt>touch
- build</tt> when the build process is complete. This
- will ensure that if <tt>debian/rules build</tt> is run
- again it will not rebuild the whole program.
- </p>
- </item>
-
- <tag><tt>binary</tt>, <tt>binary-arch</tt>,
- <tt>binary-indep</tt>
- </tag>
- <item>
- <p>
- The <tt>binary</tt> target should be all that is
- necessary for the user to build the binary
- package. All these targets are required to be
- non-interactive. It is split into two parts:
- <tt>binary-arch</tt> builds the packages' output
- files which are specific to a particular
- architecture, and <tt>binary-indep</tt> builds
- those which are not.
- </p>
+ <p>
+ 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>
- <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>
+ <sect id="pkg-sourcetools">
+ <heading>Tools for processing source packages</heading>
- <p>
- Both <prgn>binary-*</prgn> targets should depend on
- the <tt>build</tt> target, above, so that the
- package is built if it has not been already. It
- should then create the relevant binary package(s),
- using <prgn>dpkg-gencontrol</prgn> to make their
- control files and <prgn>dpkg-deb</prgn> to build
- them and place them in the parent of the top level
- directory.
- </p>
+ <p>
+ 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>
- If one of the <prgn>binary-*</prgn> targets has
- nothing to do (this will be always be the case if
- the source generates only a single binary package,
- whether architecture-dependent or not) it
- <em>must</em> still exist, but should always
- succeed.
- </p>
+ <p>
+ 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>
- <ref id="pkg-binarypkg"> describes how to construct
- binary packages.
- </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>
- <p>
- The <tt>binary</tt> targets must be invoked as
- root.
- </p>
- </item>
-
- <tag><tt>clean</tt></tag>
- <item>
-
- <p>
- This should undo any effects that the
- <tt>build</tt> and <tt>binary</tt> targets
- may have had, except that it should leave alone any
- output files created in the parent directory by a
- run of <tt>binary</tt>. This target is required
- to be non-interactive.
- </p>
+ <sect1 id="pkg-dpkg-source">
+ <heading>
+ <prgn>dpkg-source</prgn> - packs and unpacks Debian source
+ packages
+ </heading>
- <p>
- If a <tt>build</tt> file is touched at the end
- of the <tt>build</tt> target, as suggested
- above, it must be removed as the first thing that
- <tt>clean</tt> does, so that running
- <tt>build</tt> again after an interrupted
- <tt>clean</tt> doesn't think that everything is
- already done.
- </p>
+ <p>
+ 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>
- The <tt>clean</tt> target must be invoked as
- root if <tt>binary</tt> has been invoked since
- the last <tt>clean</tt>, or if
- <tt>build</tt> has been invoked as root (since
- <tt>build</tt> may create directories, for
- example).
- </p>
- </item>
-
- <tag><tt>get-orig-source</tt> (optional)</tag>
- <item>
-
- <p>
- This target fetches the most recent version of the
- original source package from a canonical archive
- site (via FTP or WWW, for example), does any
- necessary rearrangement to turn it into the original
- source tarfile format described below, and leaves it
- in the current directory.
- </p>
+ <p>
+ To unpack a package it is typically invoked with
+ <example>
+ dpkg-source -x <var>.../path/to/filename</var>.dsc
+ </example>
+ </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>
+ with the <file><var>filename</var>.tar.gz</file> and
+ <file><var>filename</var>.diff.gz</file> (if applicable) in
+ the same directory. It unpacks into
+ <file><var>package</var>-<var>version</var></file>, and if
+ applicable
+ <file><var>package</var>-<var>version</var>.orig</file>, in
+ the current directory.
+ </p>
- <p>
- 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.
+ To create a packed source archive it is typically invoked:
+ <example>
+ dpkg-source -b <var>package</var>-<var>version</var>
+ </example>
</p>
-
- <p>
- Additional targets may exist in <file>debian/rules</file>,
- either as published or undocumented interfaces or for the
- package's internal use.
- </p>
-
- <p>
- The architecture we build on and build for is determined by make
- variables via dpkg-architecture (see <ref id="pkg-dpkgarch">). You can
- get the Debian architecture and the GNU style architecture
- specification string for the build machine as well as the host
- machine. Here is a list of supported make variables:
- <list compact="compact">
- <item>
- <p><tt>DEB_*_ARCH</tt> (the Debian architecture)</p>
- </item>
- <item>
- <p><tt>DEB_*_GNU_TYPE</tt> (the GNU style architecture
- specification string)</p>
- </item>
- <item>
- <p><tt>DEB_*_GNU_CPU</tt> (the CPU part of DEB_*_GNU_TYPE)</p>
- </item>
- <item>
- <p><tt>DEB_*_GNU_SYSTEM</tt> (the System part of
- DEB_*_GNU_TYPE)</p>
- </list>
+ <p>
+ This will create the <file>.dsc</file>, <file>.tar.gz</file> and
+ <file>.diff.gz</file> (if appropriate) in the current
+ directory. <prgn>dpkg-source</prgn> does not clean the
+ source tree first - this must be done separately if it is
+ required.
</p>
-
- <p>
- where <tt>*</tt> is either <tt>BUILD</tt> for specification of
- the build machine or <tt>HOST</tt> for specification of the machine
- we build for.
- </p>
-
- <p>
- Backward compatibility can be provided in the rules file
- by setting the needed variables to suitable default
- values, please refer to the documentation of
- dpkg-architecture for details.
- </p>
-
- <p>
- It is important to understand that the <tt>DEB_*_ARCH</tt>
- string does only determine which Debian architecture we
- build on resp. for. It should not be used to get the CPU
- or System information, the GNU style variables should be
- used for that.
- </p>
+
+ <p>
+ See also <ref id="pkg-sourcearchives">.</p>
</sect1>
-
-
- <sect1><heading><file>debian/control</file>
- </heading>
- <p>
- This file contains version-independent details about the
- source package and about the binary packages it creates.
- </p>
- <p>
- It is a series of sets of control fields, each
- syntactically similar to a binary package control file.
- The sets are separated by one or more blank lines. The
- first set is information about the source package in
- general; each subsequent set describes one binary package
- that the source tree builds.
- </p>
+ <sect1 id="pkg-dpkg-buildpackage">
+ <heading>
+ <prgn>dpkg-buildpackage</prgn> - overall package-building
+ control script
+ </heading>
- <p>
- The syntax and semantics of the fields are described below
- in <ref id="pkg-controlfields">.
+ <p>
+ <prgn>dpkg-buildpackage</prgn> is a script which invokes
+ <prgn>dpkg-source</prgn>, the <file>debian/rules</file>
+ targets <tt>clean</tt>, <tt>build</tt> and
+ <tt>binary</tt>, <prgn>dpkg-genchanges</prgn> and
+ <prgn>gpg</prgn> (or <prgn>pgp</prgn>) to build a signed
+ source and binary package upload.
</p>
- <p>
- The general (binary-package-independent) fields are:
- <list compact="compact">
- <item>
- <p><qref id="pkg-f-Source"><tt>Source</tt></qref> (mandatory)</p>
- </item>
- <item>
- <p><qref id="pkg-f-Maintainer"><tt>Maintainer</tt></qref></p>
- </item>
- <item>
- <p>
- <qref id="pkg-f-classification"><tt>Section</tt> and
- <tt>Priority</tt></qref>
- (classification, mandatory)
- </p>
- </item>
- <item>
- <p>
- <qref id="relationships"><tt>Build-Depends</tt> et
- al.</qref> (source package interrelationships)
- </p>
- </item>
+ <p>
+ It is usually invoked by hand from the top level of the
+ built or unbuilt source directory. It may be invoked with
+ no arguments; useful arguments include:
+ <taglist compact="compact">
+ <tag><tt>-uc</tt>, <tt>-us</tt></tag>
<item>
<p>
- <qref id="pkg-f-Standards-Version"><tt>Standards-Version</tt></qref>
- </p>
- </item>
- </list>
-
- <p>
- The per-binary-package fields are:
- <list compact="compact">
- <item>
- <p><qref id="pkg-f-Package"><tt>Package</tt></qref> (mandatory)</p>
+ Do not sign the <tt>.changes</tt> file or the
+ source package <tt>.dsc</tt> file, respectively.</p>
</item>
+ <tag><tt>-p<var>sign-command</var></tt></tag>
<item>
<p>
- <qref id="pkg-f-Architecture"><tt>Architecture</tt></qref>
- (mandatory)</p>
- </item>
- <item>
- <p><qref id="descriptions"><tt>Description</tt></qref></p>
+ Invoke <var>sign-command</var> instead of finding
+ <tt>gpg</tt> or <tt>pgp</tt> on the <prgn>PATH</prgn>.
+ <var>sign-command</var> must behave just like
+ <prgn>gpg</prgn> or <tt>pgp</tt>.</p>
</item>
+ <tag><tt>-r<var>root-command</var></tt></tag>
<item>
<p>
- <qref id="pkg-f-classification"><tt>Section</tt> and
- <tt>Priority</tt></qref> (classification)</p>
- </item>
- <item>
- <p><qref id="pkg-f-Essential"><tt>Essential</tt></qref></p>
+ When root privilege is required, invoke the command
+ <var>root-command</var>. <var>root-command</var>
+ should invoke its first argument as a command, from
+ the <prgn>PATH</prgn> if necessary, and pass its
+ second and subsequent arguments to the command it
+ calls. If no <var>root-command</var> is supplied
+ then <var>dpkg-buildpackage</var> will take no
+ special action to gain root privilege, so that for
+ most packages it will have to be invoked as root to
+ start with.</p>
</item>
+ <tag><tt>-b</tt>, <tt>-B</tt></tag>
<item>
<p>
- <qref id="relationships"><tt>Depends</tt> et
- al.</qref> (binary package interrelationships)
+ Two types of binary-only build and upload - see
+ <manref name="dpkg-source" section="1">.
</p>
</item>
- </list>
-
- <p>
- These fields are used by <prgn>dpkg-gencontrol</prgn> to
- generate control files for binary packages (see below), by
- <prgn>dpkg-genchanges</prgn> to generate the
- <tt>.changes</tt> file to accompany the upload, and by
- <prgn>dpkg-source</prgn> when it creates the <file>.dsc</file>
- source control file as part of a source archive.
- </p>
-
- <p>
- The fields here may contain variable references - their
- values will be substituted by
- <prgn>dpkg-gencontrol</prgn>, <prgn>dpkg-genchanges</prgn>
- or <prgn>dpkg-source</prgn> when they generate output
- control files. See <ref id="pkg-srcsubstvars"> for details.
+ </taglist>
</p>
-
- <p> <sect2><heading>User-defined fields
- </heading>
-
- <p>
- Additional user-defined fields may be added to the
- source package control file. Such fields will be
- ignored, and not copied to (for example) binary or
- source package control files or upload control files.
- </p>
-
- <p>
- If you wish to add additional unsupported fields to
- these output files you should use the mechanism
- described here.
- </p>
-
- <p>
- Fields in the main source control information file with
- names starting <tt>X</tt>, followed by one or more of
- the letters <tt>BCS</tt> and a hyphen <tt>-</tt>, will
- be copied to the output files. Only the part of the
- field name after the hyphen will be used in the output
- file. Where the letter <tt>B</tt> is used the field
- will appear in binary package control files, where the
- letter <tt>S</tt> is used in source package control
- files and where <tt>C</tt> is used in upload control
- (<tt>.changes</tt>) files.
- </p>
-
- <p>
- For example, if the main source information control file
- contains the field
- <example>
- XBS-Comment: I stand between the candle and the star.
- </example>
- then the binary and source package control files will contain the
- field
- <example>
- Comment: I stand between the candle and the star.
- </example>
- </p>
- </sect2>
-
</sect1>
- <sect1 id="pkg-dpkgchangelog"><heading><file>debian/changelog</file>
+ <sect1 id="pkg-dpkg-gencontrol">
+ <heading>
+ <prgn>dpkg-gencontrol</prgn> - generates binary package
+ control files
</heading>
- <p>
- This file records the changes to the Debian-specific parts of the
- package
- <footnote>
- <p>
- Though there is nothing stopping an author who is also
- the Debian maintainer from using it for all their
- changes, it will have to be renamed if the Debian and
- upstream maintainers become different
- people.
- </p>
+ <p>
+ This program is usually called from <file>debian/rules</file>
+ (see <ref id="pkg-sourcetree">) in the top level of the source
+ tree.
+ </p>
+
+ <p>
+ This is usually done just before the files and directories in the
+ temporary directory tree where the package is being built have their
+ permissions and ownerships set and the package is constructed using
+ <prgn>dpkg-deb/</prgn>
+ <footnote>
+ This is so that the control file which is produced has
+ the right permissions
</footnote>.
</p>
- <p>
- It has a special format which allows the package building
- tools to discover which version of the package is being
- built and find out other release-specific information.
+ <p>
+ <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>
- 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>
+ It is also necessary for <prgn>dpkg-gencontrol</prgn> to
+ be run after <prgn>dpkg-shlibdeps</prgn> so that the
+ variable substitutions created by
+ <prgn>dpkg-shlibdeps</prgn> in <file>debian/substvars</file>
+ are available.
</p>
- <p>
- <var>package</var> and <var>version</var> are the source
- package name and version number.
- </p>
-
- <p>
- <var>distribution(s)</var> lists the distributions where
- this version should be installed when it is uploaded - it
- is copied to the <tt>Distribution</tt> field in the
- <tt>.changes</tt> file. See <ref id="pkg-f-Distribution">.
+ <p>
+ 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>
- <var>urgency</var> is the value for the <tt>Urgency</tt>
- field in the <file>.changes</file> file for the upload. See
- <ref id="pkg-f-Urgency">. It is not possible to specify an
- urgency containing commas; commas are used to separate
- <tt><var>keyword</var>=<var>value</var></tt> settings in
- the <prgn>dpkg</prgn> changelog format (though there is
- currently only one useful <var>keyword</var>,
- <tt>urgency</tt>).
+ <p>
+ Sources which build several binaries will typically need
+ something like:
+ <example>
+ dpkg-gencontrol -Pdebian/tmp-<var>pkg</var> -p<var>package</var>
+ </example> The <tt>-P</tt> tells
+ <prgn>dpkg-gencontrol</prgn> that the package is being
+ built in a non-default directory, and the <tt>-p</tt>
+ tells it which package's control file should be generated.
</p>
- <p>
- The change details may in fact be any series of lines
- starting with at least two spaces, but conventionally each
- change starts with an asterisk and a separating space and
- continuation lines are indented so as to bring them in
- line with the start of the text above. Blank lines may be
- used here to separate groups of changes, if desired.
- </p>
+ <p>
+ <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 id="pkg-dpkg-shlibdeps">
+ <heading>
+ <prgn>dpkg-shlibdeps</prgn> - calculates shared library
+ dependencies
+ </heading>
- <p>
- The maintainer name and email address should <em>not</em>
- necessarily be those of the usual package maintainer.
- They should be the details of the person doing
- <em>this</em> version. The information here will be
- copied to the <file>.changes</file> file, and then later used
- to send an acknowledgement when the upload has been
- installed.
+ <p>
+ 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>
- The <var>date</var> should be in RFC822 format
+ <p>
+ Its arguments are executables.
<footnote>
<p>
- This is generated by the <prgn>822-date</prgn>
- program.
+ In a forthcoming dpkg version,
+ <prgn>dpkg-shlibdeps</prgn> would be required to be
+ called on shared libraries as well.
+ </p>
+ <p>
+ They may be specified either in the locations in the
+ source tree where they are created or in the locations
+ in the temporary build tree where they are installed
+ prior to binary package creation.
</p>
- </footnote>; it should include the timezone specified
- numerically, with the timezone name or abbreviation
- optionally present as a comment.
+ </footnote> for which shared library dependencies should
+ be included in the binary package's control file.
</p>
- <p>
- The first `title' line with the package name should start
- at the left hand margin; the `trailer' line with the
- maintainer and date details should be preceded by exactly
- one space. The maintainer details and the date must be
- separated by exactly two spaces.
+ <p>
+ If some of the found shared libraries should only
+ warrant a <tt>Recommends</tt> or <tt>Suggests</tt>, or if
+ some warrant a <tt>Pre-Depends</tt>, this can be achieved
+ by using the <tt>-d<var>dependency-field</var></tt> option
+ before those executable(s). (Each <tt>-d</tt> option
+ takes effect until the next <tt>-d</tt>.)
</p>
- <p>
- 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>
+ <prgn>dpkg-shlibdeps</prgn> does not directly cause the
+ output control file to be modified. Instead by default it
+ adds to the <file>debian/substvars</file> file variable
+ settings like <tt>shlibs:Depends</tt>. These variable
+ settings must be referenced in dependency fields in the
+ appropriate per-binary-package sections of the source
+ control file.
</p>
-
- <sect2><heading>Defining alternative changelog formats
- </heading>
-
- <p>
- It is possible to use a different format to the standard
- one, by providing a parser for the format you wish to
- use.
- </p>
- <p>
- In order to have <tt>dpkg-parsechangelog</tt> run your
- parser, you must include a line within the last 40 lines
- of your file matching the Perl regular expression:
- <tt>\schangelog-format:\s+([0-9a-z]+)\W</tt> The part in
- parentheses should be the name of the format. For
- example, you might say:
- <example>
- @@@ changelog-format: joebloggs @@@
- </example>
- Changelog format names are non-empty strings of alphanumerics.
- </p>
+ <p>
+ For example, a package that generates an essential part
+ which requires dependencies, and optional parts that
+ which only require a recommendation, would separate those
+ two sets of dependencies into two different fields.<footnote>
+ At the time of writing, an example for this was the
+ <package/xmms/ package, with Depends used for the xmms
+ executable, Recommends for the plug-ins and Suggests for
+ even more optional features provided by unzip.
+ </footnote>
+ It can say in its <file>debian/rules</file>:
+ <example>
+ dpkg-shlibdeps -dDepends <var>program anotherprogram ...</var> \
+ -dRecommends <var>optionalpart anotheroptionalpart</var>
+ </example>
+ and then in its main control file <file>debian/control</file>:
+ <example>
+ <var>...</var>
+ Depends: ${shlibs:Pre-Depends}
+ Recommends: ${shlibs:Recommends}
+ <var>...</var>
+ </example>
+ </p>
- <p>
- If such a line exists then <tt>dpkg-parsechangelog</tt>
- will look for the parser as
- <file>/usr/lib/dpkg/parsechangelog/<var>format-name</var></file>
- or
- <file>/usr/local/lib/dpkg/parsechangelog/<var>format-name</var></file>;
- it is an error for it not to find it, or for it not to
- be an executable program. The default changelog format
- is <tt>dpkg</tt>, and a parser for it is provided with
- the <tt>dpkg</tt> package.
- </p>
+ <p>
+ Sources which produce several binary packages with
+ different shared library dependency requirements can use
+ the <tt>-p<var>varnameprefix</var></tt> option to override
+ the default <tt>shlibs:</tt> prefix (one invocation of
+ <prgn>dpkg-shlibdeps</prgn> per setting of this option).
+ They can thus produce several sets of dependency
+ variables, each of the form
+ <tt><var>varnameprefix</var>:<var>dependencyfield</var></tt>,
+ which can be referred to in the appropriate parts of the
+ binary package control files.
+ </p>
+ </sect1>
- <p>
- The parser will be invoked with the changelog open on
- standard input at the start of the file. It should read
- the file (it may seek if it wishes) to determine the
- information required and return the parsed information
- to standard output in the form of a series of control
- fields in the standard format. By default it should
- return information about only the most recent version in
- the changelog; it should accept a
- <tt>-v<var>version</var></tt> option to return changes
- information from all versions present <em>strictly
- after</em> <var>version</var>, and it should then be an
- error for <var>version</var> not to be present in the
- changelog.
- </p>
- <p>
- The fields are:
- <list compact="compact">
- <item>
- <p><qref id="pkg-f-Source"><tt>Source</tt></qref></p>
- </item>
- <item>
- <p><qref id="versions"><tt>Version</tt></qref> (mandatory)</p>
- </item>
- <item>
- <p>
- <qref id="pkg-f-Distribution"><tt>Distribution</tt></qref>
- (mandatory)
- </p>
- </item>
- <item>
- <p><qref id="pkg-f-Urgency"><tt>Urgency</tt></qref> (mandatory)</p>
- </item>
- <item>
- <p>
- <qref id="pkg-f-Maintainer"><tt>Maintainer</tt></qref>
- (mandatory)
- </p>
- </item>
- <item>
- <p><qref id="pkg-f-Date"><tt>Date</tt></qref></p>
- </item>
- <item>
- <p>
- <qref id="pkg-f-Changes"><tt>Changes</tt></qref>
- (mandatory)
- </p>
- </item>
- </list>
+ <sect1 id="pkg-dpkg-distaddfile">
+ <heading>
+ <prgn>dpkg-distaddfile</prgn> - adds a file to
+ <file>debian/files</file>
+ </heading>
- <p>
- If several versions are being returned (due to the use
- of <tt>-v</tt>), the urgency value should be of the
- highest urgency code listed at the start of any of the
- versions requested followed by the concatenated
- (space-separated) comments from all the versions
- requested; the maintainer, version, distribution and
- date should always be from the most recent version.
- </p>
+ <p>
+ Some packages' uploads need to include files other than
+ the source and binary package files.
+ </p>
- <p>
- For the format of the <tt>Changes</tt> field see <ref
- id="pkg-f-Changes">.
- </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>
- 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>
+ It is usually invoked from the <tt>binary</tt> target of
+ <file>debian/rules</file>:
+ <example>
+ dpkg-distaddfile <var>filename</var> <var>section</var> <var>priority</var>
+ </example>
+ The <var>filename</var> is relative to the directory where
+ <prgn>dpkg-genchanges</prgn> will expect to find it - this
+ is usually the directory above the top level of the source
+ tree. The <file>debian/rules</file> target should put the
+ file there just before or just after calling
+ <prgn>dpkg-distaddfile</prgn>.
+ </p>
- <p>
- 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>
+ The <var>section</var> and <var>priority</var> are passed
+ unchanged into the resulting <file>.changes</file> file.
+ </p>
+ </sect1>
- <p>
- If the changelog does not have the expected format the
- parser should exit with a nonzero exit status, rather
- than trying to muddle through and possibly generating
- incorrect output.
- </p>
- <p>
- A changelog parser may not interact with the user at
- all.</p></sect2>
- </sect1>
-
- <sect1 id="pkg-srcsubstvars"><heading><file>debian/substvars</file>
- and variable substitutions
+ <sect1 id="pkg-dpkg-genchanges">
+ <heading>
+ <prgn>dpkg-genchanges</prgn> - generates a <file>.changes</file>
+ upload control file
</heading>
- <p>
- When <prgn>dpkg-gencontrol</prgn>,
- <prgn>dpkg-genchanges</prgn> and <prgn>dpkg-source</prgn>
- generate control files they do variable substitutions on
- their output just before writing it. Variable
- substitutions have the form
- <tt>${<var>variable-name</var>}</tt>. The optional file
- <file>debian/substvars</file> contains variable substitutions
- to be used; variables can also be set directly from
- <file>debian/rules</file> using the <tt>-V</tt> option to the
- source packaging commands, and certain predefined
- variables are available.
- </p>
-
- <p>
- The 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.
+ <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>
- See <manref name="dpkg-source" section="1"> for full
- details about source variable substitutions, including the
- format of <file>debian/substvars</file>.</p>
+ It is usually called in the top level of a built source
+ tree, and when invoked with no arguments will print out a
+ straightforward <file>.changes</file> file based on the
+ information in the source package's changelog and control
+ file and the binary and source packages which should have
+ been built.
+ </p>
</sect1>
-
- <sect1><heading><file>debian/files</file>
- </heading>
- <p>
- This file is not a permanent part of the source tree; it
- is used while building packages to record which files are
- being generated. <prgn>dpkg-genchanges</prgn> uses it
- when it generates a <file>.changes</file> file.
- </p>
- <p>
- It should not exist in a shipped source package, and so it
- (and any backup files or temporary files such as
- <file>files.new</file>
- <footnote>
- <p>
- <file>files.new</file> is used as a temporary file by
- <prgn>dpkg-gencontrol</prgn> and
- <prgn>dpkg-distaddfile</prgn> - they write a new
- version of <file>files</file> here before renaming it,
- to avoid leaving a corrupted copy if an error
- occurs
- </p>
- </footnote>) should be removed by the
- <tt>clean</tt> target. It may also be wise to
- ensure a fresh start by emptying or removing it at the
- start of the <tt>binary</tt> target.
- </p>
-
- <p>
- <prgn>dpkg-gencontrol</prgn> adds an entry to this file
- for the <file>.deb</file> file that will be created by
- <prgn>dpkg-deb</prgn> from the control file that it
- generates, so for most packages all that needs to be done
- with this file is to delete it in <tt>clean</tt>.
- </p>
-
- <p>
- If a package upload includes files besides the source
- package and any binary packages whose control files were
- made with <prgn>dpkg-gencontrol</prgn> then they should be
- placed in the parent of the package's top-level directory
- and <prgn>dpkg-distaddfile</prgn> should be called to add
- the file to the list in <file>debian/files</file>.</p>
- </sect1>
-
- <sect1><heading><file>debian/tmp</file>
+ <sect1 id="pkg-dpkg-parsechangelog">
+ <heading>
+ <prgn>dpkg-parsechangelog</prgn> - produces parsed
+ representation of a changelog
</heading>
- <p>
- This is the canonical temporary location for the
- construction of binary packages by the <tt>binary</tt>
- target. The directory <file>tmp</file> serves as the root of
- the filesystem tree as it is being constructed (for
- example, by using the package's upstream makefiles install
- targets and redirecting the output there), and it also
- contains the <tt>DEBIAN</tt> subdirectory. See <ref
- id="pkg-bincreating">.
- </p>
-
- <p>
- If several binary packages are generated from the same
- source tree it is usual to use several
- <file>debian/tmp<var>something</var></file> directories, for
- example <file>tmp-a</file> or <file>tmp-doc</file>.
+ <p>
+ This program is used internally by
+ <prgn>dpkg-source</prgn> et al. It may also occasionally
+ be useful in <file>debian/rules</file> and elsewhere. It
+ parses a changelog, <file>debian/changelog</file> by default,
+ and prints a control-file format representation of the
+ information in it to standard output.
</p>
+ </sect1>
- <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>
+ <sect1 id="pkg-dpkg-architecture">
+ <heading>
+ <prgn>dpkg-architecture</prgn> - information about the build and
+ host system
+ </heading>
+
+ <p>
+ This program can be used manually, but is also invoked by
+ <tt>dpkg-buildpackage</tt> or <file>debian/rules</file> to set
+ to set environment or make variables which specify the build and
+ host architecture for the package building process.
+ </p>
+ </sect1>
</sect>
-
-
- <sect id="pkg-sourcearchives"><heading>Source packages as archives
- </heading>
- <p>
- As it exists on the FTP site, a Debian source package
- consists of three related files. You must have the right
- versions of all three to be able to use them.
- </p>
+ <sect id="pkg-sourcetree">
+ <heading>The Debianised source tree</heading>
- <p>
- <taglist>
- <tag>Debian source control file - <tt>.dsc</tt></tag>
- <item>
-
- <p>
- This file contains a series of fields, identified and
- separated just like the fields in the control file of
- a binary package. The fields are listed below; their
- syntax is described above, in <ref id="pkg-controlfields">.
- <list compact="compact">
- <item>
- <p><qref id="pkg-f-Source"><tt>Source</tt></qref></p>
- </item>
- <item>
- <p><qref id="versions"><tt>Version</tt></qref></p>
- </item>
- <item>
- <p><qref id="pkg-f-Maintainer"><tt>Maintainer</tt></qref></p>
- </item>
- <item>
- <p><qref id="pkg-f-Binary"><tt>Binary</tt></qref></p>
- </item>
- <item>
- <p><qref id="pkg-f-Architecture"><tt>Architecture</tt></qref></p>
- </item>
- <item>
- <p>
- <qref id="relationships"><tt>Build-Depends</tt> et
- al.</qref> (source package interrelationships)
- </p>
- </item>
- <item>
- <p>
- <qref id="pkg-f-Standards-Version"><tt>Standards-Version</tt></qref></p>
- </item>
- <item>
- <p><qref id="pkg-f-Files"><tt>Files</tt></qref></p>
- </item>
- </list>
+ <p>
+ The source archive scheme described later is intended to
+ allow a Debianised source tree with some associated control
+ information to be reproduced and transported easily. The
+ Debianised source tree is a version of the original program
+ with certain files added for the benefit of the
+ Debianisation process, and with any other changes required
+ made to the rest of the source code and installation
+ scripts.
+ </p>
- <p>
- The source package control file is generated by
- <prgn>dpkg-source</prgn> when it builds the source
- archive, from other files in the source package,
- described above. When unpacking it is checked against
- the files and directories in the other parts of the
- source package, as described below.</p>
- </item>
-
- <tag>
- Original source archive -
- <file>
- <var>package</var>_<var>upstream-version</var>.orig.tar.gz
- </file>
- </tag>
+ <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>
- <item>
-
- <p>
- This is a compressed (with <tt>gzip -9</tt>)
- <prgn>tar</prgn> file containing the source code from
- the upstream authors of the program. The tarfile
- unpacks into a directory
- <file><var>package</var>-<var>upstream-version</var>.orig</file>,
- and does not contain files anywhere other than in
- there or in its subdirectories.</p>
- </item>
-
- <tag>
- Debianisation diff -
- <file>
- <var>package</var>_<var>upstream_version-revision</var>.diff.gz
- </file>
- </tag>
- <item>
-
- <p>
- This is a unified context diff (<tt>diff -u</tt>)
- giving the changes which are required to turn the
- original source into the Debian source. These changes
- may only include editing and creating plain files.
- The permissions of files, the targets of symbolic
- links and the characteristics of special files or
- pipes may not be changed and no files may be removed
- or renamed.
- </p>
+ <sect1 id="pkg-debianrules">
+ <heading><file>debian/rules</file> - the main building script</heading>
- <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>
+ See <ref id="debianrules">.
+ </p>
+ </sect1>
- <p>
- The <prgn>dpkg-source</prgn> program will
- automatically make the <file>debian/rules</file> file
- executable (see below).</p></item>
- </taglist>
-
- <p>
- If there is no original source code - for example, if the
- package is specially prepared for Debian or the Debian
- maintainer is the same as the upstream maintainer - the
- format is slightly different: then there is no diff, and the
- tarfile is named
- <file><var>package</var>_<var>version</var>.tar.gz</file> and
- contains a directory
- <file><var>package</var>-<var>version</var></file>.
- </p>
- </sect>
-
- <sect><heading>Unpacking a Debian source package without
- <prgn>dpkg-source</prgn>
- </heading>
+ <sect1 id="pkg-dpkgchangelog">
+ <heading><file>debian/changelog</file></heading>
- <p>
- <tt>dpkg-source -x</tt> is the recommended way to unpack a
- Debian source package. However, if it is not available it
- is possible to unpack a Debian source archive as follows:
- <enumlist compact="compact">
- <item>
- <p>
- Untar the tarfile, which will create a <file>.orig</file>
- directory.</p>
- </item>
- <item>
- <p>Rename the <file>.orig</file> directory to
- <file><var>package</var>-<var>version</var></file>.</p>
- </item>
- <item>
- <p>
- Create the subdirectory <file>debian</file> at the top of
- the source tree.</p>
- </item>
- <item><p>Apply the diff using <tt>patch -p0</tt>.</p>
- </item>
- <item><p>Untar the tarfile again if you want a copy of the original
- source code alongside the Debianised version.</p>
- </item>
- </enumlist>
-
- <p>
- It is not possible to generate a valid Debian source archive
- without using <prgn>dpkg-source</prgn>. In particular,
- attempting to use <prgn>diff</prgn> directly to generate the
- <file>.diff.gz</file> file will not work.
- </p>
-
- <sect1><heading>Restrictions on objects in source packages
- </heading>
+ <p>
+ See <ref id="dpkgchangelog">.
+ </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>
+ It is recommended that the entire changelog be encoded in the
+ <url id="http://www.cis.ohio-state.edu/cgi-bin/rfc/rfc2279.html" name="UTF-8">
+ encoding of
+ <url id="http://www.unicode.org/"
+ name="Unicode">.<footnote>
<p>
- Hard links may be permitted at some point in the
- future, but would require a fair amount of
- work.
+ I think it is fairly obvious that we need to
+ eventually transition to UTF-8 for our package
+ infrastructure; it is really the only sane char-set in
+ an international environment. Now, we can't switch to
+ using UTF-8 for package control fields and the like
+ until dpkg has better support, but one thing we can
+ start doing today is requesting that Debian changelogs
+ are UTF-8 encoded. At some point in time, we can start
+ requiring them to do so.
</p>
- </footnote>, device special files, sockets or setuid or
- setgid files.
- <footnote>
<p>
- Setgid directories are allowed.
+ Checking for non-UTF8 characters in a changelog is
+ trivial. Dump the file through
+ <example>iconv -f utf-8 -t ucs-4</example>
+ discard the output, and check the return
+ value. If there are any characters in the stream
+ which are invalid UTF-8 sequences, iconv will exit
+ with an error code; and this will be the case for the
+ vast majority of other character sets.
</p>
</footnote>
</p>
- <p>
- The source packaging tools manage the changes between the
- original and Debianised source using <prgn>diff</prgn> and
- <prgn>patch</prgn>. Turning the original source tree as
- included in the <file>.orig.tar.gz</file> into the debianised
- source must not involve any changes which cannot be
- handled by these tools. Problematic changes which cause
- <prgn>dpkg-source</prgn> to halt with an error when
- building the source package are:
- <list compact="compact">
- <item><p>Adding or removing symbolic links, sockets or pipes.</p>
- </item>
- <item><p>Changing the targets of symbolic links.</p>
- </item>
- <item><p>Creating directories, other than <file>debian</file>.</p>
- </item>
- <item><p>Changes to the contents of binary files.</p></item>
- </list> Changes which cause <prgn>dpkg-source</prgn> to
- print a warning but continue anyway are:
- <list compact="compact">
- <item>
- <p>
- Removing files, directories or symlinks.
- <footnote>
- <p>
- Renaming a file is not treated specially - it is
- seen as the removal of the old file (which
- generates a warning, but is otherwise ignored),
- and the creation of the new
- one.</p>
- </footnote>
- </p>
- </item>
- <item>
- <p>
- Changed text files which are missing the usual final
- newline (either in the original or the modified
- source tree).
- </p>
- </item>
- </list>
- Changes which are not represented, but which are not detected by
- <prgn>dpkg-source</prgn>, are:
- <list compact="compact">
- <item><p>Changing the permissions of files (other than
- <file>debian/rules</file>) and directories.</p></item>
- </list>
- </p>
-
- <p>
- The <file>debian</file> directory and <file>debian/rules</file>
- are handled specially by <prgn>dpkg-source</prgn> - before
- applying the changes it will create the <file>debian</file>
- directory, and afterwards it will make
- <file>debian/rules</file> world-exectuable.
- </p>
- </sect1>
- </sect>
- </appendix>
-
- <appendix id="pkg-controlfields"><heading>Control files and their
- fields (from old Packaging Manual)
- </heading>
-
- <p>
- Many of the tools in the <prgn>dpkg</prgn> suite manipulate
- data in a common format, known as control files. Binary and
- source packages have control data as do the <file>.changes</file>
- files which control the installation of uploaded files, and
- <prgn>dpkg</prgn>'s internal databases are in a similar
- format.
- </p>
-
- <sect><heading>Syntax of control files
- </heading>
+ <sect2><heading>Defining alternative changelog formats
+ </heading>
- <p>
- A file consists of one or more paragraphs of fields. The
- paragraphs are separated by blank lines. Some control files
- only allow one paragraph; others allow several, in which
- case each paragraph often refers to a different package.
- </p>
+ <p>
+ 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>
- Each paragraph is a series of fields and values; each field
- consists of a name, followed by a colon and the value. It
- ends at the end of the line. Horizontal whitespace (spaces
- and tabs) may occur before or after the value and is ignored
- there; it is conventional to put a single space after the
- colon.
- </p>
+ <p>
+ In order to have <tt>dpkg-parsechangelog</tt> run your
+ parser, you must include a line within the last 40 lines
+ of your file matching the Perl regular expression:
+ <tt>\schangelog-format:\s+([0-9a-z]+)\W</tt> The part in
+ parentheses should be the name of the format. For
+ example, you might say:
+ <example>
+ @@@ changelog-format: joebloggs @@@
+ </example>
+ Changelog format names are non-empty strings of alphanumerics.
+ </p>
- <p>
- 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>
+ If such a line exists then <tt>dpkg-parsechangelog</tt>
+ will look for the parser as
+ <file>/usr/lib/dpkg/parsechangelog/<var>format-name</var></file>
+ or
+ <file>/usr/local/lib/dpkg/parsechangelog/<var>format-name</var></file>;
+ it is an error for it not to find it, or for it not to
+ be an executable program. The default changelog format
+ is <tt>dpkg</tt>, and a parser for it is provided with
+ the <tt>dpkg</tt> package.
+ </p>
- <p>
- Except where otherwise stated only a single line of data is
- allowed and whitespace is not significant in a field body.
- Whitespace may never appear inside names (of packages,
- architectures, files or anything else), version numbers or
- in between the characters of multi-character version
- relationships.
- </p>
+ <p>
+ The parser will be invoked with the changelog open on
+ standard input at the start of the file. It should read
+ the file (it may seek if it wishes) to determine the
+ information required and return the parsed information
+ to standard output in the form of a series of control
+ fields in the standard format. By default it should
+ return information about only the most recent version in
+ the changelog; it should accept a
+ <tt>-v<var>version</var></tt> option to return changes
+ information from all versions present <em>strictly
+ after</em> <var>version</var>, and it should then be an
+ error for <var>version</var> not to be present in the
+ changelog.
+ </p>
- <p>
- Field names are not case-sensitive, but it is usual to
- capitalise the field names using mixed case as shown below.
- </p>
+ <p>
+ The fields are:
+ <list compact="compact">
+ <item><qref id="f-Source"><tt>Source</tt></qref></item>
+ <item><qref id="f-Version"><tt>Version</tt></qref> (mandatory)</item>
+ <item><qref id="f-Distribution"><tt>Distribution</tt></qref> (mandatory)</item>
+ <item><qref id="f-Urgency"><tt>Urgency</tt></qref> (mandatory)</item>
+ <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
+ <item><qref id="f-Date"><tt>Date</tt></qref></item>
+ <item><qref id="f-Changes"><tt>Changes</tt></qref> (mandatory)</item>
+ </list>
+ </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>
+ If several versions are being returned (due to the use
+ of <tt>-v</tt>), the urgency value should be of the
+ highest urgency code listed at the start of any of the
+ versions requested followed by the concatenated
+ (space-separated) comments from all the versions
+ requested; the maintainer, version, distribution and
+ date should always be from the most recent version.
+ </p>
- <p>
- 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>
- </sect>
-
- <sect><heading>List of fields
- </heading>
-
- <sect1 id="pkg-f-Package"><heading><tt>Package</tt>
- </heading>
+ <p>
+ For the format of the <tt>Changes</tt> field see
+ <ref id="f-Changes">.
+ </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>
- </footnote>
- </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>
- They must be at least two characters and must start with
- an alphanumeric. In current versions of dpkg they are
- sort of case-sensitive<footnote><p>This is a
- bug.</p></footnote>; use lowercase package names unless
- the package you're building (or referring to, in other
- fields) is already using uppercase.</p>
- </sect1>
-
- <sect1 id="pkg-f-Version"><heading><tt>Version</tt>
- </heading>
+ <p>
+ 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 synthesize
+ it or find it from other sources.
+ </p>
- <p>
- This lists the source or binary package's version number -
- see <ref id="versions">.
- </p>
+ <p>
+ If the changelog does not have the expected format the
+ parser should exit with a nonzero exit status, rather
+ than trying to muddle through and possibly generating
+ incorrect output.
+ </p>
+ <p>
+ A changelog parser may not interact with the user at
+ all.
+ </p>
+ </sect2>
</sect1>
-
- <sect1 id="pkg-f-Architecture"><heading><tt>Architecture</tt>
- </heading>
-
- <p>
- This is the architecture string; it is a single word for
- the Debian architecture.
- </p>
- <p>
- <prgn>dpkg</prgn> will check the declared architecture of
- a binary package against its own compiled-in value before
- it installs it.
- </p>
-
- <p>
- The special value <tt>all</tt> indicates that the package
- is architecture-independent.
- </p>
+ <sect1 id="pkg-srcsubstvars">
+ <heading><file>debian/substvars</file> and variable substitutions</heading>
- <p>
- In the main <file>debian/control</file> file in the source
- package, or in the source package control file
- <file>.dsc</file>, a list of architectures (separated by
- spaces) is also allowed, as is the special value
- <tt>any</tt>. A list indicates that the source will build
- an architecture-dependent package, and will only work
- correctly on the listed architectures. <tt>any</tt>
- indicates that though the source package isn't dependent
- on any particular architecture and should compile fine on
- any one, the binary package(s) produced are not
- architecture-independent but will instead be specific to
- whatever the current build architecture is.
- </p>
-
- <p>
- In a <file>.changes</file> file the <tt>Architecture</tt>
- field lists the architecture(s) of the package(s)
- currently being uploaded. This will be a list; if the
- source for the package is being uploaded too the special
- entry <tt>source</tt> is also present.
+ <p>
+ See <ref id="substvars">.
</p>
- <p>
- See <ref id="pkg-debianrules"> for information how to get the
- architecture for the build process.
- </p>
</sect1>
-
- <sect1 id="pkg-f-Maintainer"><heading><tt>Maintainer</tt>
- </heading>
-
- <p>
- The package maintainer's name and email address. The name
- should come first, then the email address inside angle
- brackets <tt><></tt> (in RFC822 format).
- </p>
- <p>
- If the maintainer's name contains a full stop then the
- whole field will not work directly as an email address due
- to a misfeature in the syntax specified in RFC822; a
- program using this field as an address must check for this
- and correct the problem if necessary (for example by
- putting the name in round brackets and moving it to the
- end, and bringing the email address forward).
- </p>
+ <sect1>
+ <heading><file>debian/files</file></heading>
- <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>
+ See <ref id="debianfiles">.
</p>
-
- <p>
- This field is usually optional in as far as the
- <prgn>dpkg</prgn> are concerned, but its absence when
- building packages usually generates a warning.</p>
</sect1>
-
- <sect1 id="pkg-f-Source"><heading><tt>Source</tt>
- </heading>
- <p>
- This field identifies the source package name.
- </p>
+ <sect1><heading><file>debian/tmp</file>
+ </heading>
- <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>
+ This is the canonical temporary location for the
+ construction of binary packages by the <tt>binary</tt>
+ target. The directory <file>tmp</file> serves as the root of
+ the file system tree as it is being constructed (for
+ example, by using the package's upstream makefiles install
+ targets and redirecting the output there), and it also
+ contains the <tt>DEBIAN</tt> subdirectory. See <ref
+ id="pkg-bincreating">.
</p>
- <p>
- In the control file of a binary package (or in a
- <file>Packages</file> file) it may be followed by a version
- number in parentheses.
- <footnote>
- <p>
- It is usual to leave a space after the package name if
- a version number is specified.
- </p>
- </footnote> This version number may be omitted (and is, by
- <prgn>dpkg-gencontrol</prgn>) if it has the same value as
- the <tt>Version</tt> field of the binary package in
- question. The field itself may be omitted from a binary
- package control file when the source package has the same
- name and version as the binary package.
+ <p>
+ 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>
- </sect1>
-
- <sect1><heading>Package interrelationship fields:
- <tt>Depends</tt>, <tt>Pre-Depends</tt>,
- <tt>Recommends</tt> <tt>Suggests</tt>, <tt>Conflicts</tt>,
- <tt>Provides</tt>, <tt>Replaces</tt>
- </heading>
- <p>
- These fields describe the package's relationships with
- other packages. Their syntax and semantics are described
- in <ref id="relationships">.</p>
- </sect1>
-
- <sect1 id="pkg-f-Description"><heading><tt>Description</tt>
- </heading>
+ <p>
+ 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>
- <p>
- In a binary package <tt>Packages</tt> file or main source
- control file this field contains a description of the
- binary package, in a special format. See <ref
- id="descriptions"> for details.
- </p>
- <p>
- In a <file>.changes</file> file it contains a summary of the
- descriptions for the packages being uploaded. The part of
- the field before the first newline is empty; thereafter
- each line has the name of a binary package and the summary
- description line from that binary package. Each line is
- indented by one space.</p>
- </sect1>
-
- <sect1 id="pkg-f-Essential"><heading><tt>Essential</tt>
- </heading>
+ <sect id="pkg-sourcearchives"><heading>Source packages as archives
+ </heading>
- <p>
- This is a boolean field which may occur only in the
- control file of a binary package (or in the
- <file>Packages</file> file) or in a per-package fields
- paragraph of a main source control data file.
- </p>
+ <p>
+ 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>
- 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>
+ <taglist>
+ <tag>Debian source control file - <tt>.dsc</tt></tag>
+ <item>
+ This file is a control file used by <prgn>dpkg-source</prgn>
+ to extract a source package.
+ See <ref id="debiansourcecontrolfiles">.
+ </item>
- <p>
- These two fields classify the package. The
- <tt>Priority</tt> represents how important that it is that
- the user have it installed; the <tt>Section</tt>
- represents an application area into which the package has
- been classified.
- </p>
-
- <p>
- When they appear in the <file>debian/control</file> file these
- fields give values for the section and priority subfields
- of the <tt>Files</tt> field of the <file>.changes</file> file,
- and give defaults for the section and priority of the
- binary packages.
- </p>
-
- <p>
- The section and priority are represented, though not as
- separate fields, in the information for each file in the
- <qref id="pkg-f-Files"><tt>-File</tt></qref>field of a
- <file>.changes</file> file. The section value in a
- <file>.changes</file> file is used to decide where to install
- a package in the FTP archive.
- </p>
-
- <p>
- These fields are not used by by <prgn>dpkg</prgn> proper,
- but by <prgn>dselect</prgn> when it sorts packages and
- selects defaults. 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.
- </p>
-
- <p>
- These fields may appear in binary package control files,
- in which case they provide a default value in case the
- <file>Packages</file> files are missing the information.
- <prgn>dpkg</prgn> and <prgn>dselect</prgn> will only use
- the value from a <file>.deb</file> file if they have no other
- information; a value listed in a <file>Packages</file> file
- will always take precedence. By default
- <prgn>dpkg-gencontrol</prgn> does not include the section
- and priority in the control file of a binary package - use
- the <tt>-isp</tt>, <tt>-is</tt> or <tt>-ip</tt> options to
- achieve this effect.</p>
- </sect1>
-
- <sect1 id="pkg-f-Binary"><heading><tt>Binary</tt>
- </heading>
+ <tag>
+ Original source archive -
+ <file>
+ <var>package</var>_<var>upstream-version</var>.orig.tar.gz
+ </file>
+ </tag>
- <p>
- This field is a list of binary packages.
- </p>
+ <item>
+ <p>
+ This is a compressed (with <tt>gzip -9</tt>)
+ <prgn>tar</prgn> file containing the source code from
+ the upstream authors of the program.
+ </p>
+ </item>
- <p>
- When it appears in the <file>.dsc</file> file it is the list
- of binary packages which a source package can produce. It
- does not necessarily produce all of these binary packages
- for every architecture. The source control file doesn't
- contain details of which architectures are appropriate for
- which of the binary packages.
- </p>
+ <tag>
+ Debianisation diff -
+ <file>
+ <var>package</var>_<var>upstream_version-revision</var>.diff.gz
+ </file>
+ </tag>
+ <item>
- <p>
- When it appears in a <file>.changes</file> file it lists the
- names of the binary packages actually being uploaded.
- </p>
+ <p>
+ This is a unified context diff (<tt>diff -u</tt>)
+ giving the changes which are required to turn the
+ original source into the Debian source. These changes
+ may only include editing and creating plain files.
+ The permissions of files, the targets of symbolic
+ links and the characteristics of special files or
+ pipes may not be changed and no files may be removed
+ or renamed.
+ </p>
- <p>
- The syntax is a list of binary packages separated by
- commas.
- <footnote>
<p>
- A space after each comma is conventional.
+ 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>
- </footnote> Currently the packages must be separated using
- only spaces in the <file>.changes</file> file.</p>
- </sect1>
-
- <sect1 id="pkg-f-Installed-Size"><heading><tt>Installed-Size</tt>
- </heading>
- <p>
- This field appears in the control files of binary
- packages, and in the <file>Packages</file> files. It gives
- the total amount of disk space required to install the
- named package.
- </p>
+ <p>
+ The <prgn>dpkg-source</prgn> program will
+ automatically make the <file>debian/rules</file> file
+ executable (see below).</p></item>
+ </taglist>
+ </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>
+ If there is no original source code - for example, if the
+ package is specially prepared for Debian or the Debian
+ maintainer is the same as the upstream maintainer - the
+ format is slightly different: then there is no diff, and the
+ tarfile is named
+ <file><var>package</var>_<var>version</var>.tar.gz</file>,
+ and preferably contains a directory named
+ <file><var>package</var>-<var>version</var></file>.
+ </p>
+ </sect>
- <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
- 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>
+ <sect>
+ <heading>Unpacking a Debian source package without <prgn>dpkg-source</prgn></heading>
+
+ <p>
+ <tt>dpkg-source -x</tt> is the recommended way to unpack a
+ Debian source package. However, if it is not available it
+ is possible to unpack a Debian source archive as follows:
+ <enumlist compact="compact">
+ <item>
+ <p>
+ Untar the tarfile, which will create a <file>.orig</file>
+ directory.</p>
+ </item>
+ <item>
+ <p>Rename the <file>.orig</file> directory to
+ <file><var>package</var>-<var>version</var></file>.</p>
+ </item>
+ <item>
+ <p>
+ Create the subdirectory <file>debian</file> at the top of
+ the source tree.</p>
+ </item>
+ <item><p>Apply the diff using <tt>patch -p0</tt>.</p>
+ </item>
+ <item><p>Untar the tarfile again if you want a copy of the original
+ source code alongside the Debianised version.</p>
+ </item>
+ </enumlist>
- <p>
- In the <file>.dsc</file> (Debian source control) file each
- line contains the MD5 checksum, size and filename of the
- tarfile and (if applicable) diff file which make up the
- remainder of the source package.
- <footnote>
- <p>
- That is, the parts which are not the
- <tt>.dsc</tt>.
- </p>
- </footnote> The exact forms of the filenames are described
- in <ref id="pkg-sourcearchives">.
- </p>
+ <p>
+ 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>
- <p>
- In the <file>.changes</file> file this contains one line per
- file being uploaded. Each line contains the MD5 checksum,
- size, section and priority and the filename. The section
- and priority are the values of the corresponding fields in
- the main source control file - see <ref
- id="pkg-f-classification">. If no section or priority is
- specified then <tt>-</tt> should be used, though section
- and priority values must be specified for new packages to
- be installed properly.
- </p>
+ <sect1>
+ <heading>Restrictions on objects in source packages</heading>
- <p>
- The special value <tt>byhand</tt> for the section in a
- <tt>.changes</tt> file indicates that the file in question
- is not an ordinary package file and must by installed by
- hand by the distribution maintainers. If the section is
- <tt>byhand</tt> the priority should be <tt>-</tt>.
+ <p>
+ The source package may not contain any hard links
+ <footnote>
+ This is not currently detected when building source
+ packages, but only when extracting
+ them.
+ </footnote>
+ <footnote>
+ Hard links may be permitted at some point in the
+ future, but would require a fair amount of
+ work.
+ </footnote>, device special files, sockets or setuid or
+ setgid files.
+ <footnote>
+ Setgid directories are allowed.
+ </footnote>
</p>
- <p>
- If a new Debian revision of a package is being shipped and
- no new original source archive is being distributed the
- <tt>.dsc</tt> must still contain the <tt>Files</tt> field
- entry for the original source archive
- <file><var>package</var>-<var>upstream-version</var>.orig.tar.gz</file>,
- but the <file>.changes</file> file should leave it out. In
- this case the original source archive on the distribution
- site must match exactly, byte-for-byte, the original
- source archive which was used to generate the
- <file>.dsc</file> file and diff which are being uploaded.</p>
- </sect1>
-
-
- <sect1
- id="pkg-f-Standards-Version"><heading><tt>Standards-Version</tt>
- </heading>
-
- <p>
- The most recent version of the standards (the
- <prgn>dpkg</prgn> programmers' and policy manuals 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>
+ The source packaging tools manage the changes between the
+ original and Debianised source using <prgn>diff</prgn> and
+ <prgn>patch</prgn>. Turning the original source tree as
+ included in the <file>.orig.tar.gz</file> into the debianised
+ source must not involve any changes which cannot be
+ handled by these tools. Problematic changes which cause
+ <prgn>dpkg-source</prgn> to halt with an error when
+ building the source package are:
+ <list compact="compact">
+ <item><p>Adding or removing symbolic links, sockets or pipes.</p>
+ </item>
+ <item><p>Changing the targets of symbolic links.</p>
+ </item>
+ <item><p>Creating directories, other than <file>debian</file>.</p>
+ </item>
+ <item><p>Changes to the contents of binary files.</p></item>
+ </list> Changes which cause <prgn>dpkg-source</prgn> to
+ print a warning but continue anyway are:
+ <list compact="compact">
+ <item>
+ <p>
+ Removing files, directories or symlinks.
+ <footnote>
+ 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.
+ </footnote>
+ </p>
+ </item>
+ <item>
+ <p>
+ Changed text files which are missing the usual final
+ newline (either in the original or the modified
+ source tree).
+ </p>
+ </item>
+ </list>
+ Changes which are not represented, but which are not detected by
+ <prgn>dpkg-source</prgn>, are:
+ <list compact="compact">
+ <item><p>Changing the permissions of files (other than
+ <file>debian/rules</file>) and directories.</p></item>
+ </list>
</p>
- <p>
- Its format is the same as that of a version number except
- that no epoch or Debian revision is allowed - see <ref
- id="versions">.</p>
- </sect1>
-
-
- <sect1 id="pkg-f-Distribution"><heading><tt>Distribution</tt>
- </heading>
-
- <p>
- In a <file>.changes</file> file or parsed changelog output
- this contains the (space-separated) name(s) of the
- distribution(s) where this version of the package should
- be or was installed. Distribution names follow the rules
- for package names. (See <ref id="pkg-f-Package">).
+ <p>
+ The <file>debian</file> directory and <file>debian/rules</file>
+ are handled specially by <prgn>dpkg-source</prgn> - before
+ applying the changes it will create the <file>debian</file>
+ directory, and afterwards it will make
+ <file>debian/rules</file> world-executable.
</p>
-
- <p>
- Current distribution values are:
- <taglist>
- <tag><em>stable</em></tag>
- <item>
- <p>
- This is the current `released' version of Debian
- GNU/Linux. A new version is released approximately
- every 3 months after the <em>development</em> code has
- been <em>frozen</em> for a month of testing. Once the
- distribution is <em>stable</em> only major bug fixes
- are allowed. When changes are made to this
- distribution, the release number is increased
- (for example: 1.2r1 becomes 1.2r2 then 1.2r3, etc).
- </p>
- </item>
-
- <tag><em>unstable</em></tag>
- <item>
- <p>
- This distribution value refers to the
- <em>developmental</em> part of the Debian distribution
- tree. New packages, new upstream versions of packages
- and bug fixes go into the <em>unstable</em> directory
- tree. Download from this distribution at your own
- risk.</p>
- </item>
-
- <tag><em>contrib</em></tag>
- <item>
- <p>
- The packages with this distribution value do not meet
- the criteria for inclusion in the main Debian
- distribution as defined by the Policy Manual, but meet
- the criteria for the <em>contrib</em>
- Distribution. There is currently no distinction
- between stable and unstable packages in the
- <em>contrib</em> or <em>non-free</em>
- distributions. Use your best judgement in downloading
- from this Distribution.</p>
- </item>
-
- <tag><em>non-free</em></tag>
- <item>
- <p>
- Like the packages in the <em>contrib</em> seciton,
- the packages in <em>non-free</em> do not meet the
- criteria for inclusion in the main Debian distribution
- as defined by the Policy Manual. Again, use your best
- judgement in downloading from this Distribution.</p>
-
- <tag><em>experimental</em></tag>
- <item>
- <p>
- The packages with this distribution value are deemed
- by their maintainers to be high risk. Oftentimes they
- represent early beta or developmental packages from
- various sources that the maintainers want people to
- try, but are not ready to be a part of the other parts
- of the Debian distribution tree. Download at your own
- risk.</p>
- </item>
-
- <tag><em>frozen</em></tag>
- <item>
- <p>
- From time to time, (currently, every 3 months) the
- <em>unstable</em> distribution enters a state of
- `code-freeze' in anticipation of release as a
- <em>stable</em> version. During this period of testing
- (usually 4 weeks) only fixes for existing or
- newly-discovered bugs will be allowed.
- </p>
- </item>
- </taglist> You should list <em>all</em> distributions that
- the package should be installed into. Except in unusual
- circumstances, installations to <em>stable</em> should also
- go into <em>frozen</em> (if it exists) and
- <em>unstable</em>. Likewise, installations into
- <em>frozen</em> should also go into <em>unstable</em>.</p>
</sect1>
-
- <sect1 id="pkg-f-Urgency"><heading><tt>Urgency</tt>
- </heading>
+ </sect>
+ </appendix>
- <p>
- This is a description of how important it is to upgrade to
- this version from previous ones. It consists of a single
- keyword usually taking one of the values <tt>LOW</tt>,
- <tt>MEDIUM</tt> or <tt>HIGH</tt>) followed by an optional
- commentary (separated by a space) which is usually in
- parentheses. For example:
- <example>
- Urgency: LOW (HIGH for diversions users)
- </example>
- </p>
+ <appendix id="pkg-controlfields">
+ <heading>Control files and their fields (from old Packaging Manual)</heading>
- <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>
+ Many of the tools in the <prgn>dpkg</prgn> suite manipulate
+ data in a common format, known as control files. Binary and
+ source packages have control data as do the <file>.changes</file>
+ files which control the installation of uploaded files, and
+ <prgn>dpkg</prgn>'s internal databases are in a similar
+ format.
+ </p>
- <p>
- Urgency keywords are not case-sensitive.</p>
- </sect1>
-
- <sect1 id="pkg-f-Date"><heading><tt>Date</tt>
- </heading>
+ <sect>
+ <heading>Syntax of control files</heading>
- <p>
- In <tt>.changes</tt> files and parsed changelogs, this
- gives the date the package was built or last edited.</p>
- </sect1>
-
- <sect1 id="pkg-f-Format"><heading><tt>Format</tt>
- </heading>
+ <p>
+ See <ref id="controlsyntax">.
+ </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
- format value is the same as that of a package version
- number except that no epoch or Debian revision is allowed
- - see <ref id="versions">.</p>
- </sect1>
-
- <sect1 id="pkg-f-Changes"><heading><tt>Changes</tt>
- </heading>
+ <p>
+ It is important to note that there are several fields which
+ are optional as far as <prgn>dpkg</prgn> and the related
+ tools are concerned, but which must appear in every Debian
+ package, or whose omission may cause problems.
+ </p>
+ </sect>
- <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>
+ <sect>
+ <heading>List of fields</heading>
- <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>
+ See <ref id="controlfieldslist">.
+ </p>
- <p>
- Each version's change information should be preceded by a
- `title' line giving at least the version, distribution(s)
- and urgency, in a human-readable way.
- </p>
+ <p>
+ This section now contains only the fields that didn't belong
+ to the Policy manual.
+ </p>
- <p>
- If data from several versions is being returned the entry
- for the most recent version should be returned first, and
- entries should be separated by the representation of a
- blank line (the `title' line may also be followed by the
- representation of blank line).</p>
- </sect1>
-
- <sect1 id="pkg-f-Filename"><heading><tt>Filename</tt> and
- <tt>MSDOS-Filename</tt>
- </heading>
+ <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
+ re-installation) 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>
- These are still recognised by <prgn>dpkg</prgn> but should
+ <sect1>
+ <heading>Obsolete fields</heading>
+
+ <p>
+ These are still recognized 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.
+ file system.
</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>
- See the manpage <manref name="update-alternatives"
+ <p>
+ See the man page <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>
+<!-- Local variables: -->
+<!-- indent-tabs-mode: t -->
+<!-- End: -->
+<!-- vim:set ai et sts=2 sw=2 tw=76: -->
projects / debian / debian-policy.git / blobdiff