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
+ 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
contents of this document since September 1998, with the package
maintainers responsible for packaging administrivia only.
-->
-
+
<book>
<titlepag>
<title>Debian Policy Manual</title>
<email>ijackson@gnu.ai.mit.edu</email>
</author>
<author>
- <name>Christian Schwarz</name>
+ <name>Christian Schwarz</name>
<email>schwarz@debian.org</email>
</author>
<author>
- <name>revised: David A. Morris</name>
+ <name>revised: David A. Morris</name>
<email>bweaver@debian.org</email>
</author>
<author>
<abstract>
This manual describes the policy requirements for the Debian
- GNU/Linux distribution. This includes the structure and
- contents of the Debian archive, several design issues of the
- operating system, as well as technical requirements that each
- package must satisfy to be included in the distribution. The
- policy package itself is maintained by a group of maintainers
- that have no editorial powers. At the moment, the list of
- maintainers is:
+ GNU/Linux distribution. This includes the structure and
+ contents of the Debian archive and several design issues of
+ the operating system, as well as technical requirements that
+ each package must satisfy to be included in the distribution.
+ The policy package itself is maintained by a group of
+ maintainers that have no editorial powers. The current list
+ of maintainers is:
<enumlist>
<item>
- <p>Michael Alan Dorman <email>mdorman@debian.org</email></p>
- </item>
- <item>
- <p>Philip Hands <email>phil@hands.com</email></p>
- </item>
- <item>
- <p>Julian Gilbey <email>J.D.Gilbey@qmw.ac.uk</email></p>
+ <p>Julian Gilbey <email>jdg@debian.org</email></p>
</item>
<item>
<p>Manoj Srivastava <email>srivasta@debian.org</email></p>
<p>
A copy of the GNU General Public License is available as
- <tt>/usr/share/common-licences/GPL</tt> 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 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.
+ <tt>/usr/share/common-licenses/GPL</tt> 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
+ obtain it by writing to the Free Software Foundation, Inc.,
+ 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
</p>
</copyright>
</titlepag>
<toc detail="sect">
-
+
<chapt id="scope">
<heading>About this manual</heading>
<sect>
<p>
This manual describes the policy requirements for the Debian
GNU/Linux distribution. This includes the structure and
- contents of the Debian archive, several design issues of the
+ 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.
</p>
-
-
+
+
<p>
This manual also describes Debian policy as it relates to
creating Debian packages. It is not a tutorial on how to build
packages, nor is it exhaustive where it comes to describing
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>
+ 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>
+ <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
- should not be changed without peer review. Package
- maintainers can then rely on this interfaces not
- changing, and the package management software
- authors need to ensure compatibility with these
- interface definitions. (control file and and
- changelog file formats are one example)
+ therefore should not be changed without peer
+ review. Package maintainers can then rely on this
+ interfaces not changing, and the package
+ management software authors need to ensure
+ compatibility with these interface
+ definitions. (Control file and changelog file
+ formats are examples.)
</p>
</item>
<tag>Chosen Convention</tag>
</taglist>
Please note that these are not mutually exclusive;
selected conventions often become parts of standard
- interfaces.
+ interfaces.
</p>
</footnote>
</p>
-
+
<p>
- Please note that the footnotes present in this manual are
+ The footnotes present in this manual are
merely informative, and are not part of Debian policy itself.
</p>
-
-
+
+
<p>
In 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
- this policy document. Packages that do not conform the the
+ this policy document. Packages that do not conform to the
guidelines denoted by <em>must</em> (or <em>required</em>)
will generally not be considered acceptable for the Debian
distribution. Non-conformance with guidelines denoted by
</p>
<p>
These classifications are roughly equivalent to the bug
- severities <em>important</em> (for <em>must</em> or
- <em>required</em> directive violations), <em>normal</em>
+ severities <em>serious</em> (for <em>must</em> or
+ <em>required</em> directive violations), <em>minor</em>,
+ <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>Also see RFC 2119.</p>
+ items).<footnote>
+ <p>Compare RFC 2119. Note, however, that these words are
+ used in a different way in this document.</p>
</footnote>
</p>
<p>
Much of the information presented in this manual will be
useful even when building a package which is to be
- distributed in some other way or is for local use.
+ distributed in some other way or is intended for local use
+ 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> at
- <ftppath>/debian/doc/package-developer/debian-policy.html.tar.gz</ftppath>
- or from the Debian WWW server at
- <url id="http://www.debian.org/doc/debian-policy/"
- name="The Debian Policy Manual">.</p>
+ The current version of this document is always accessible
+ from the Debian FTP server <ftpsite>ftp.debian.org</ftpsite>
+ as
+ <ftppath>/debian/doc/package-developer/policy.txt.gz</ftppath>
+ (also available from the same directory are several other
+ formats: <tt>policy.html.tar.gz</tt>, <tt>policy.pdf.gz</tt>
+ and <tt>policy.ps.gz</tt>) or from the <url
+ id="http://www.debian.org/doc/debian-policy/" name="Debian
+ Policy Manual"> webpage.</p>
<p>
In addition, this manual is distributed via the Debian package
<tt>debian-policy</tt>.
</p>
+
+ <p>
+ The <tt>debian-policy</tt> package also includes the file
+ <tt>upgrading-checklist.txt</tt> which indicates policy
+ changes between versions of this document.
+ </p>
</sect>
<sect>
<heading>Feedback</heading>
<p>
As the Debian GNU/Linux system is continuously evolving this
- manual is changed from time to time.
+ manual does so too.
</p>
<p>
- While the authors of this document tried hard not to include
- any typos or other errors these still occur. If you discover
- an error in this manual or if you want to tell us any
- comments, suggestions, or critics please send an email to
+ While the authors of this document have tried hard to avoid
+ typos and other errors, these do still occur. If you discover
+ an error in this manual or if you want to give any
+ comments, suggestions, or criticisms please send an email to
the Debian Policy List,
<email>debian-policy@lists.debian.org</email>, or submit a
bug report against the <tt>debian-policy</tt> package.
</p>
</sect>
</chapt>
- <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 (over
- 5000) they are split into <em>sections</em> and <em>priorities</em> to
- simplify handling of them.
+ collection of <em>packages</em>. Since there are so many of
+ them (currently well over 6000), 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 Debian Free Software
+ <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>.</p>
+ <em>non-US/contrib</em>. The sections are explained in detail
+ below.
+ </p>
<p>
- The <em>main</em> and the <em>non-US/main</em> sections form
- the <em>Debian GNU/Linux distribution</em>.
+ The <em>main</em> and the <em>non-US/main</em> sections
+ together form the <em>Debian GNU/Linux distribution</em>.
</p>
<p>
- Packages in the other sections are not considered as part of
- the Debian distribution, though we support their use, and we
+ 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>
<sect id="pkgcopyright">
<heading>Package copyright and sections</heading>
<p>
- The aims of this policy are:
+ The aims of this section are:
<list compact="compact">
<item>
- <p>We want to make as much software available as we
- can.</p>
+ <p>to allow us to make as much software available as we
+ can,</p>
</item>
<item>
- <p>We want to encourage everyone to write free software.</p>
+ <p>to allow us to encourage everyone to write free
+ software, and</p>
</item>
<item>
- <p> We want to make it easy for people to produce
+ <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>
<sect1>
<heading>The Debian Free Software Guidelines</heading>
<p>
- The Debian Free Software Guidelines (DFSG) is our
- definition of `free' software.
+ The Debian Free Software Guidelines (DFSG) form our
+ definition of `free software'. These are:
<taglist>
<tag>Free Redistribution
</tag>
source code. The license may require derived works to
carry a different name or version number from the
original software. (This is a compromise. The Debian
- group encourages all authors to not restrict any
+ Project encourages all authors to not restrict any
files, source or binary, from being modified.)
</p>
</item>
<sect1>
<heading>The main section</heading>
<p>
- Every package in "main" and "non-US/main" must comply with
- the DFSG (Debian Free Software Guidelines).</p>
-
+ Every package in <em>main</em> and <em>non-US/main</em>
+ must comply with the DFSG (Debian Free Software
+ Guidelines).</p>
+
<p>
- In addition, the packages in "main"
+ In addition, the packages in <em>main</em>
<list compact="compact">
<item>
<p>
- must not require a package outside of "main" for
- compilation or execution (thus, the package must not
- declare a "Depends", "Recommends", or
- "Build-Depends" relationship on a non-main package),
+ 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>
</list>
</p>
<p>
- Similarly, the packages in "non-US/main"
+ Similarly, the packages in <em>non-US/main</em>
<list compact="compact">
<item>
<p>
- must not require a package outside of "main" or
- "non-US/main" for compilation or execution,
+ must not require a package outside of <em>main</em>
+ or <em>non-US/main</em> for compilation or
+ execution,
</p>
</item>
<item>
<sect1>
<heading>The contrib section</heading>
<p>
- Every package in "contrib" and "non-US/contrib" must
- comply with the DFSG.
+ Every package in <em>contrib</em> and
+ <em>non-US/contrib</em> must comply with the DFSG.
+ </p>
+
+ <p>
+ In addition, the packages in <em>contrib</em> and
+ <em>non-US/contrib</em>
+ <list compact="compact">
+ <item>
+ <p>
+ must not be so buggy that we refuse to support them,
+ and
+ </p>
+ </item>
+ <item>
+ <p>
+ must meet all policy requirements presented in this
+ manual.
+ </p>
+ </item>
+ </list>
+ </p>
+
+ <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 "contrib"
- or "non-US/contrib" are
+ Examples of packages which would be included in
+ <em>contrib</em> or <em>non-US/contrib</em> are:
<list compact="compact">
<item>
<p>
- free packages which require "contrib", "non-free"
- packages or packages which are not in our
- archive at all for compilation or execution,
+ 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,
+ non-free programs.
</p>
</item>
</list>
</p>
</sect1>
<sect1>
- <heading>The non-free section and non-US/non-free </heading>
+ <heading>The non-free section</heading>
+ <p>
+ Packages must be placed in <em>non-free</em> or
+ <em>non-US/non-free</em> if they are not compliant with
+ the DFSG or are encumbered by patents or other legal
+ issues that make their distribution problematic.
+ </p>
<p>
- Packages must be placed in "non-free" or "non-US/non-free"
- if they are not compliant with the DFSG or are encumbered
- by patents or other legal issues that make their
- distribution problematic.
+ In addition, the packages in <em>non-free</em> and
+ <em>non-US/non-free</em>
+ <list compact="compact">
+ <item>
+ <p>
+ must not be so buggy that we refuse to support them,
+ and
+ </p>
+ </item>
+ <item>
+ <p>
+ must meet all policy requirements presented in this
+ manual that it is possible for them to meet.<footnote>
+ <p>
+ 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 "non-US" server because of export restrictions of the
- U.S. Such programs must be distributed in the appropriate
- non-US section, either non-US/main, non-US/contrib or
- non-US/non-free. </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 non-us server if it is capable of running without the
- cryptography library or program.
+ 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
- /usr/share/doc/<package-name>/copyright (see
- <ref id="copyrightfile"> for details).</p>
+ Every package must be accompanied by a verbatim copy of
+ its copyright and distribution license in the file
+ <tt>/usr/share/doc/<var>package</var>/copyright</tt>
+ (see <ref id="copyrightfile"> for further details).
+ </p>
<p>
We reserve the right to restrict files from being included
anywhere in our archives if
</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; otherwise they must
- go in non-free.</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 allow redistribution even of only binaries,
- and where no special permission has been obtained, must not be
- placed on the Debian FTP site and its mirrors at all.</p>
+ 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>
+ 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>
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
+ 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 is a
+ them to modify their license terms. However, this can be a
politically difficult thing to do and you should ask for
- advice on <tt>debian-legal</tt> first.</p>
+ advice on the <tt>debian-legal</tt> mailing list first, as
+ explained below.
+ </p>
<p>
- When in doubt, send mail to
+ 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>
+ copyrights are safe; be wary of the phrases `commercial
+ use prohibited' and `distribution restricted'.
+ </p>
</sect1>
<sect1>
<heading>Subsections</heading>
<p>
- The packages in all the sections (<em>main</em>,
- <em>contrib</em>, <em>non-US/main</em>, <em>non-free</em>,
- <em>non-US/contrib</em>, and <em>non-US/non-free</em>) are
- grouped further into <em>subsections</em> to simplify
- handling.</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>
<p>
- The section for each package should be specified in the
- package's <em>control record</em>. However, the maintainer of
- the Debian archive may override this selection to assure the
- consistency of the Debian distribution. </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>
- Please check the current Debian distribution to see which
- sections are available.</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>
<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 in the Debian package
- management tool to separate high-priority packages from
- less-important packages.</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>
+
<p>
- The following <em>priority levels</em> are supported by the
- Debian package management system, <prgn>dpkg</prgn>.
+ The following <em>priority levels</em> are recognised by the
+ Debian package management tools.
<taglist>
<tag><tt>required</tt></tag>
<item>
<p>
- <tt>required</tt> packages 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>
+ 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>
</item>
<tag><tt>important</tt></tag>
<item>
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 the F*!@<+ is
- going on, where is <prgn>foo</prgn>', it must be in
- <tt>important</tt>. This is an important criterion
- because we are trying to produce, amongst other
- things, a free Unix. Other packages without which the
- system will not run well or be usable must also be
- here. This does <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>
+ 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
+ <tt>important</tt>. This does
+ <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>
</item>
<tag><tt>standard</tt></tag>
<item>
- <p>
+ <p>
These packages provide a reasonably small but not too
- limited character-mode system. This is what will
- install by default if the user doesn't select anything
- else. It doesn't include many large applications, but
- it does include Emacs (this is more of a piece of
- infrastructure than an application) and a reasonable
- subset of TeX and LaTeX (if this is possible without
- X).</p>
+ 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>
</item>
<tag><tt>optional</tt></tag>
<item>
- <p>
- (In a sense everything is optional that isn't
- required, but that's not what is meant here.) This is
+ <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
- install if you didn't know what it was or don't have
+ install if you didn't know what it was and don't have
specialized requirements. This is a much larger system
- and includes the X Window System, a full TeX distribution,
- and many applications. Note that optional packages should
- not conflict with each other.
+ 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>
</p>
</item>
</taglist></p>
-
+
<p>
Packages must not depend on packages with lower priority
values (excluding build-time dependencies). In order to
- ensure this, the priorities of one or more packages must
- be adjusted.
+ ensure this, the priorities of one or more packages may need
+ to be adjusted.
</p>
</sect>
-
+
<sect>
<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>
-
-
+
+
<sect1>
<heading>The package name</heading>
-
+
<p>
Every package must have a name that's unique within the Debian
archive.</p>
-
+
<p>
- Package names must only consist of lower case letters, digits (0-9),
- plus (+) or minus (-) signs, and periods (.).</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.
+ </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.
</p>
</sect1>
-
+
<sect1>
<heading>The maintainer of a package</heading>
<p>
- Every package must have a 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 distribution
+ 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 the correct name
- and a working email address for the Debian maintainer of
- the package. If one person maintains several packages
- he/she should try to avoid having different forms of their
- name and email address in different <tt>Maintainer</tt>
- fields.</p>
-
+ <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.
+ </p>
+
<p>
If the maintainer of a package quits from the Debian
- project the Debian QA Group
- <email>debian-qa@lists.debian.org</email> takes over the
+ 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>.
+ <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>
</p>
</sect1>
-
-
+
+
<sect1>
<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.</p>
-
+
<p>
- The description should be written so that it tells the user
- what they need to know to decide whether to install the
- package. This description should not just be copied from
- the blurb for the program. 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 -- that is what the copyright file is
- for.</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).
+ </p>
</sect1>
-
-
+
+
<sect1>
<heading>Dependencies</heading>
-
+
<p>
Every package must specify the dependency information
about other packages that are required for the first to
work correctly.</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>
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>
-
+
<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>
-
-
+
+
<sect1>
<heading>Virtual packages</heading>
-
+
<p>
- Sometimes, there are several packages doing more-or-less
- the same job. In this case, it's useful to define a
- <em>virtual package</em> whose name describes the function
- the packages have. (The virtual packages just 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
+ 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>
All packages should use virtual package names where
appropriate, and arrange to create new ones if necessary.
amongst a cooperating group of packages) unless they have
been agreed upon and appear in the list of virtual package
names.</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.text</ftppath>
+ <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>
-
-
+
+
<sect1>
<heading>Base packages</heading>
-
+
<p>
The packages included in the <tt>base</tt> section have a
special function. They form a minimum subset of the Debian
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>
-
+
<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>
You must not place any packages into the <tt>base</tt>
section before this has been discussed on the
<tt>debian-devel</tt> mailing list and a consensus about
doing that has been reached.</p></sect1>
-
-
+
+
<sect1>
<heading>Essential packages</heading>
-
+
<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>
-
+
<p>
- Since these packages can not easily be removed (you'll
- have to specify an extra <em>force option</em> to
- <prgn>dpkg</prgn>) this flag must not be used unless
- absolutely necessary. A shared library package must not
- be tagged <tt>essential</tt>--the dependencies will
+ 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
+ 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
<p>
You must not tag any packages <tt>essential</tt> before
this has been discussed on the <tt>debian-devel</tt>
- mailing and a consensus about doing that has been
- reached.</p></sect1>
-
-
- <sect1>
+ mailing list and a consensus about doing that has been
+ reached.
+ </p>
+ </sect1>
+
+ <sect1 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
</p>
<p>
- Note, that <ref id="scripts">, in general applies to package
+ Note that in general <ref id="scripts"> applies to package
maintainer scripts, too.
</p>
<p>
- You should not use <tt>dpkg-divert</tt>' on a file
+ You should not use <tt>dpkg-divert</tt> 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
- <var>Conflicts</var> to ensure that other packages are
+ <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 this not allowed).
+ <prgn>update-alternatives</prgn>; this is an exception to
+ the usual rule that versioned conflicts should be
+ avoided.)
</p>
communicating with a program, such as
<prgn>debconf</prgn>, which conforms to the Debian
Configuration management specification, version 2 or
- higher. (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
+ higher. These are included in the
+ <tt>debconf_specification</tt> 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 your local mirror.
- <footnote>
+ or on your local mirror.<footnote>
<p>
- 2.5% of Debian packages
- [<url id="http://kitenet.net/programs/debconf/stats/">]
- use debconf 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">;
- they include preconfiguration, (mostly)
- noninteractive installation, elimination of
- redundant prompting, consistency of user interface,
- etc.
+ 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
- debconf, plus the existance of a nascent second
- implementation of the Debian configuration
- management system (<package>cdebconf</package>), and
- the stabalization of the protocol these things use,
- the time has finally come to reflect the use of
- these things in policy.
-
+ <package>debconf</package>, plus the existance of a
+ nascent second implementation of the Debian
+ configuration management system
+ (<package>cdebconf</package>), and the stabalization
+ 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
- <file>config</file> script and a <file>templates</file>
+ <prgn>config</prgn> script and a <tt>templates</tt>
file in their control archive. The <prgn>config</prgn>
- script can be run before the preinst, and before the
- package is unpacked or any of its dependancies or
- pre-dependancies are satisfied, so it must work using
- only the tools present in the <em>Essential</em>
- packages.
- <footnote>
+ 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>
- Debconf or another tool that implements the Debian
- Configuration management specification will also be
- installed, and any versioned dependancies on it will
- be satisfied before preconfiguration begins.
+ <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>
will only ever be asked each question once. This means
that packages should try to use appropriate shared
configuration files (such as <tt>/etc/papersize</tt> and
- <tt>/etc/news/server</tt>), and shared debconf variables
- rather than each prompting for their own list of
- required pieces of information.
+ <tt>/etc/news/server</tt>), 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 <tt>/etc</tt> so that the user can
+ modify them, and how this has been done should be
+ documented.</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 <tt>/etc</tt> 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
important (they belong in
<tt>/usr/share/doc/<var>package</var>/copyright</tt>);
neither do instructions on how to use a program (these
- should be in on line documentation, where all the users
+ 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>
-
+
+ <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>
+
+ <sect1 id="standardsversion">
<heading>Standards conformance</heading>
-
- <p>
- You should specify the most recent version of the
- packaging standards with which your package complies in
- the source package's <tt>Standards-Version</tt> field.</p>
-
+
<p>
- This value will be used to file bug reports automatically
- if your package becomes too much out of date.</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;.
+ </p>
+
<p>
- The value corresponds to a version of the Debian manuals,
- as can be found on the title page or page headers and
- footers (depending on the format).</p>
-
+ This information may be used to file bug reports
+ automatically if your package becomes too much out of
+ date.
+ </p>
+
<p>
- The version number has four components--major and minor
- number and major and minor patch level. When the
+ 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
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
- which do not change the meaning are made, or changes which
- do not affect the contents of packages.</p>
+ are made which neither change the meaning of the document
+ nor affect the contents of packages.</p>
<p>
- For package maintainers, only the first 3 digits of the
- manual version are significant in representing the
- <em>Standards-Version</em>, and either these 3 digits or
- the complete 4 digits may be specified.
- <footnote>
+ 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 4 digits in the
- Standards-Version field, like `2.3.0.0'. Since any
- `patch-level changes' don't introduce new policy, it
- was thought it would be better to relax policy and
- only require that the first 3 digits are specified. (4
- digits may still be used if someone wants to do so.)
+ 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>
</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.</p></sect1>
-
-
+ release it.<footnote>
+ <p>
+ See the file <tt>upgrading-checklist</tt> for
+ information about policy which has changed between
+ different versions of this document.
+ </p>
+ </footnote>
+ </p>
+ </sect1>
+
+
<sect1>
<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
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
an informational list can be found in
<tt>/usr/share/doc/build-essential/list</tt> (which is
contained in the <tt>build-essential</tt>
- package).
- <footnote>
+ package).<footnote>
<p>Rationale:
- <list>
+ <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)
+ documents do).
</p>
</item>
<item>
<p>
- Having a separate package allows one to nistall
- the build essential packages on a machine, as
- well as allowing other packages (think task
- packages) to bring in the build-essential
- packages using the depends relation
+ 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>
</item>
<item>
<p>
The separate package allows bug reports against
- the package to be categorized separately from
- the policy management process that uses the BTS
+ the list to be categorized separately from
+ the policy management process in the BTS.
</p>
</item>
</list>
</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. The reason is
- that dependencies change, and you should list only those
- <em>you</em> need. What others need is their business.
+ build-time dependencies depends on them.<footnote>
+ <p>
+ The reason for this is that dependencies change, and
+ you should list all those packages, and <em>only</em>
+ those packages that <em>you</em> need directly. What
+ others need is their business. For example, if you
+ only link against <tt>libimlib</tt>, you will need to
+ build-depend on <package>libimlib2-dev</package> but
+ not against any <tt>libjpeg*</tt> packages, even
+ though <tt>libimlib2-dev</tt> currently depends on
+ 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 the build-essential packages installed
- and satisfying the build-time relationships (including any
- implied relationships). This
- means in particular 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.
+ 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 generally
- applicable, 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>
-
+ 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 configure it the way you need to, 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 <tt>debian/rules</tt> or
- wherever is appropriate.</p>
-
+ 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
+ <tt>debian/rules</tt> 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
<em>not</em> configure the package and edit the generated
<prgn>Makefile</prgn>! This makes it impossible for
someone else to later reconfigure the package.</p></sect1>
-
-
+
+
<sect1>
<heading>Documenting your changes</heading>
-
+
<p>
You should document your changes and updates to the source
package properly in the <tt>debian/changelog</tt> file. (Note
that mistakes in changelogs are usually best rectified by
- making a new changelog entry rather than "rewriting history"
- by editing old changelog entries)</p>
-
+ making a new changelog entry rather than "rewriting history"
+ by editing old changelog entries.)</p>
+
<p>
- In non-experimental packages you must only use a format for
+ In non-experimental packages you must use a format for
<tt>debian/changelog</tt> which is supported by the most
- recent released version of <prgn>dpkg</prgn>. If your
- format is not supported and there is general support for
- it you should contact the <prgn>dpkg</prgn> maintainer to
- have the parser script for your format included in the
- <prgn>dpkg</prgn> package. (You will need to agree that
- the parser and its manpage may be distributed under the
- GNU GPL, just as the rest of <prgn>dpkg</prgn>
- is.)</p></sect1>
-
-
- <sect1>
- <heading>Error trapping in makefiles</heading>
-
+ 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>
+
+
+ <sect1>
+ <heading>Error trapping in makefiles</heading>
+
<p>
When <prgn>make</prgn> invokes a command in a makefile
- (including your package's upstream makefiles and the
- <tt>debian/rules</tt>) it does so using <tt>sh</tt>. This
+ (including your package's upstream makefiles and
+ <tt>debian/rules</tt>), it does so using <tt>sh</tt>. This
means that <tt>sh</tt>'s usual bad error handling
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>
Every time you put more than one shell command (this
includes using a loop) in a makefile command you
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>
-
-
+
+
<sect1>
<heading>Obsolete constructs and libraries</heading>
-
+
<p>
- The include file <prgn><varargs.h></prgn> is
+ 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>
- Debian packages should be ported to include
- <prgn><stdarg.h></prgn> and <tt>ncurses</tt> when
- they are built.</p>
+ Debian packages should be patched to use
+ <tt><stdarg.h></tt> and <tt>ncurses</tt>
+ instead.
+ </p>
</sect1>
</sect>
</chapt>
<chapt id="controlfields"><heading>Control files and their fields</heading>
- <p>
+ <p>
Many of the tools in the package management suite manipulate
- data in a common format, known as control files. Binary and
- source packages have control data as do the <tt>.changes</tt>
- files which control the installation of uploaded files, and
- <prgn>dpkg</prgn>'s internal databases are in a similar
+ data represented in a common format, known as <em>control
+ data</em>. The data is often stored in <em>control
+ files</em>. Binary and source packages have control files,
+ and the <tt>.changes</tt> files which control the installation
+ of uploaded files are also in control file format.
+ <prgn>Dpkg</prgn>'s internal databases are in a similar
format.
</p>
-
- <sect><heading>Syntax of control files</heading>
- <p>
- A file consists of one or more paragraphs of fields. The
- paragraphs are separated by blank lines. Some control files
- only allow one paragraph; others allow several, in which
- case each paragraph often refers to a different package.
+ <sect id="controlsyntax"><heading>Syntax of control files</heading>
+
+ <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.)
</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 immediately before or after the value
- and is ignored there; it is conventional to put a single
- space after the colon.
+ <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>.
</p>
- <p>
+ <p>
Some fields' values may span several lines; in this case
each continuation line <em>must</em> start with a space or
tab. Any trailing spaces or tabs at the end of individual
lines of a field value are ignored.
</p>
- <p>
+ <p>
Except where otherwise stated only a single line of data is
allowed and whitespace is not significant in a field body.
- Whitespace may never appear inside names (of packages,
- architectures, files or anything else), version numbers or
- in between the characters of multi-character version
+ 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>
+ <p>
Field names are not case-sensitive, but it is usual to
capitalize the field names using mixed case as shown below.
</p>
- <p>
+ <p>
Blank lines, or lines consisting only of spaces and tabs,
are not allowed within field values or between fields - that
would mean a new paragraph.
</p>
- <p>
- 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 conjunction with the details
- below and the list of fields for the particular file.</p>
</sect>
-
+
<sect><heading>List of fields</heading>
<p>
- This list here is not supposed to be exhaustive. Typically
- only fields for whom policy exists are mentioned here.
+ This list here is not supposed to be exhaustive. Most fields
+ are dealt with elsewhere in this document.
</p>
<sect1 id="f-Package"><heading><tt>Package</tt>
</heading>
- <p>
+ <p>
The name of the binary package. Package names consist of
the alphanumerics and <tt>+</tt> <tt>-</tt> <tt>.</tt>
(plus, minus and full stop).
</p>
- <p>
+ <p>
They must be at least two characters long and must start
- with an alphanumeric character. The use of lowercase
- package names is strongly recommended unless the package
- you're building (or referring to, in other fields) is
- already using uppercase.</p>
+ with an alphanumeric character 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>
</sect1>
-
+
<sect1 id="f-Version"><heading><tt>Version</tt>
</heading>
- <p>
+ <p>
This lists the source or binary package's version number -
see <ref id="versions">.
</p>
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>
-
- <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="f-Distribution"><heading><tt>Distribution</tt>
</heading>
- <p>
+ <p>
In a <tt>.changes</tt> 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="f-Package">).
- </p>
-
- <p>
- <footnote>
- Current distribution values are:
- <taglist>
+ 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>
+ <p>
This is the current `released' version of Debian
- GNU/Linux. 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).
+ 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>
</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>unstable</em>
+ 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.
+ 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
+ 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>
- There are several sections in each
- distribution. Currently, these sections are:
-
- <taglist>
- <tag><em>contrib</em></tag>
- <item>
- <p>
- The packages in this section do not meet the
- criteria for inclusion in the main Debian
- distribution as defined by the Policy Manual,
- but are otherwise free, as defined by the Debian
- free software guidelines.</p>
- </item>
-
- <tag><em>non-free</em></tag>
- <item>
- <p>
- Packages in <em>non-free</em> do not meet the
- criteria of free software, as defined by the
- Debian free software guidelines. Again, use your
- best judgment in downloading from this
- Distribution.</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>.
+
+ 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>
+ <chapt id="versions"><heading>Version numbering</heading>
- <p>
- Every package has a version number, in its <tt>Version</tt>
- control file field.
+ <p>
+ Every package has a version number recorded in its
+ <tt>Version</tt> control file field.
</p>
- <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
concerned) at the beginning.
</p>
- <p>
+ <p>
The version number format is:
- &lsqb<var>epoch</var><tt>:</tt>]<var>upstream-version</var>[<tt>-/<var>debian-revision</var>].</tt>
+ [<var>epoch</var><tt>:</tt>]<var>upstream_version</var>[<tt>-</tt><var>debian_revision</var>]
</p>
- <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
+ omitted then the <var>upstream_version</var> may not
contain any colons.
</p>
- <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>
+
+ <tag><var>upstream_version</var></tag>
<item>
-
<p>
- This is the main part of the version. It is usually the
- version number of the original (`upstream') package from
- which the <tt>.deb</tt> 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.
+ This is the main part of the version number. It is
+ usually the version number of the original (`upstream')
+ package from which the <tt>.deb</tt> file has been made,
+ 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>
+ <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>
+ 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 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;
+ <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>
+
+ <tag><var>debian_revision</var></tag>
<item>
-
<p>
- This part of the version represents the version of the
- modifications that were made to the package to make it a
- Debian binary package. It is in the same format as the
- <var>upstream-version</var> and is compared in the same
- way.
+ 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>
+ <p>
It is optional; if it isn't present then the
- <var>upstream-version</var> may not contain a hyphen.
+ <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 binary package, and so there is only one
- `debianization' of it and therefore no revision
- indication is required.
+ Debian package, and so there is only one `debianization'
+ of it and therefore no revision indication is required.
</p>
- <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
- <var>upstream-version</var> and
- <var>debian-revision</var> apart at the last hyphen in
- the string. 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).
+ <var>debian_revision</var> at <tt>1</tt> each time the
+ <var>upstream_version</var> is increased.
</p>
- <p>
- The <var>debian-revision</var> may contain only
- alphanumerics and the characters <tt>+</tt> and
- <tt>.</tt> (plus and full stop).
+ <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>
- The <var>upstream-version</var> and <var>debian-revision</var>
+ </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>
+ <p>
The strings are compared from left to right.
</p>
- <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
sort earlier than all the non-letters.
</p>
- <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
as zero.
</p>
- <p>
- These two steps are repeated (chopping initial non-digit
- strings and initial digit strings off from the start) until a
+ <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>
+ <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 changes. It is <em>not</em> there
- 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).
+ 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>
+ <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.
too.</p>
<p>
- Note, that other version formats based on dates which are
+ Note that other version formats based on dates which are
parsed correctly by the package management system should
<em>not</em> be changed.</p>
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 are encouraged to preserve the modification
- times of the upstream source files in a package, as far as
- is reasonably possible. Even though this is optional, this
- is still a good idea.
- <footnote>
+ 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
</footnote>
</p>
</sect>
-
+
<sect id="debianrules"><heading><tt>debian/rules</tt> - the
- main building script </heading>
+ main building script</heading>
- <p>
+ <p>
This file must be an executable makefile, and contains the
package-specific recipes for compiling the package and
- building binary package(s) out of the source.
+ building binary package(s) from the source.
</p>
-
- <p>
+
+ <p>
It must start with the line <tt>#!/usr/bin/make -f</tt>,
so that it can be invoked by saying its name rather than
invoking <prgn>make</prgn> explicitly.
</p>
-
+
<p>
Since an interactive <tt>debian/rules</tt> script makes it
impossible to auto-compile that package and also makes it
hard for other people to reproduce the same binary
- package, all <strong>required targets</strong> MUST be
+ package, all <em>required targets</em> MUST be
non-interactive. At a minimum, required targets are the
ones called by <prgn>dpkg-buildpackage</prgn>, namely,
<em>clean</em>, <em>binary</em>, <em>binary-arch</em>,
that any target that these targets depend on must also be
non-interactive.
</p>
-
- <p>
- The targets which must be present are:
+
+ <p>
+ The required and optional targets are as follows:
<taglist>
- <tag><tt>build</tt></tag>
+ <tag><tt>build</tt>, <tt>build-arch</tt> (optional),
+ <tt>build-indep</tt> (optional)</tag>
<item>
<p>
- This should perform all non-interactive
- configuration and compilation of the package. If a
- package has an interactive pre-build configuration
- routine, the Debianised source package should be
- built after this has taken place, so that it can be
- built without rerunning the configuration.
+ The <tt>build</tt> target should perform all
+ non-interactive configuration and compilation of the
+ package. If a package has an interactive pre-build
+ configuration routine, the Debianized source package
+ must either be built after this has taken place (so
+ that the binary package can be built without rerunning
+ the configuration) or the configuration routine
+ modified to become non-interactive. (The latter is
+ preferable if there are architecture-specific features
+ detected by the configuration routine.)
</p>
-
- <p>
+
+ <p>
For some packages, notably ones where the same
source tree is compiled in different ways to produce
- two binary packages, the <prgn>build</prgn> target
+ two binary packages, the <tt>build</tt> target
does not make much sense. For these packages it is
good enough to provide two (or more) targets
(<tt>build-a</tt> and <tt>build-b</tt> or whatever)
for each of the ways of building the package, and a
- <prgn>build</prgn> target that does nothing. The
- <prgn>binary</prgn> target will have to build the
+ <tt>build</tt> target that does nothing. The
+ <tt>binary</tt> target will have to build the
package in each of the possible ways and make the
binary package out of each.
</p>
-
- <p>
- The <prgn>build</prgn> target must not do anything
+
+ <p>
+ The <tt>build</tt> target must not do anything
that might require root privilege.
</p>
-
- <p>
- The <prgn>build</prgn> target may need to run
- <prgn>clean</prgn> first - see below.
+
+ <p>
+ The <tt>build</tt> target may need to run the
+ <tt>clean</tt> target first - see below.
</p>
-
- <p>
- When a package has a configuration routine that
- takes a long time, or when the makefiles are poorly
- designed, or when <prgn>build</prgn> needs to run
- <prgn>clean</prgn> first, it is a good idea to
+
+ <p>
+ When a package has a configuration and build routine
+ which 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.
+ 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>
+ target to do the building and to <tt>touch
+ build-stamp</tt> on completion. This is
+ especially useful if the build routine creates a
+ file or directory called <tt>build</tt>; in such a
+ case, <tt>build</tt> will need to be listed as
+ a phony target (i.e., as a dependency of the
+ <tt>.PHONY</tt> target). See the documentation of
+ <prgn>make</prgn> for more information on phony
+ targets.
+ </p>
+ </footnote>
</p>
</item>
-
+
<tag><tt>binary</tt>, <tt>binary-arch</tt>,
<tt>binary-indep</tt>
- </tag>
+ </tag>
<item>
<p>
- The <prgn>binary</prgn> target must 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:
- <prgn>binary-arch</prgn> builds the packages' output
- files which are specific to a particular
- architecture, and <prgn>binary-indep</prgn> builds
+ The <tt>binary</tt> target must be all that is
+ necessary for the user to build the binary package(s)
+ produced from this source package. All of these
+ targets are required to be non-interactive. It is
+ split into two parts: <prgn>binary-arch</prgn> builds
+ the binary packages which are specific to a particular
+ architecture, and <tt>binary-indep</tt> builds
those which are not.
</p>
-
- <p>
- <prgn>binary</prgn> may be (and commonly is) a target
- with no commands which simply depends on
- <prgn>binary-arch</prgn> and
- <prgn>binary-indep</prgn>.
+ <p>
+ <tt>binary</tt> may be (and commonly is) a target with
+ no commands which simply depends on
+ <tt>binary-arch</tt> and <tt>binary-indep</tt>.
</p>
-
- <p>
- Both <prgn>binary-*</prgn> targets should depend on
- the <prgn>build</prgn> target, above, so that the
- package is built if it has not been already. It
- should then create the relevant binary package(s),
- using <prgn>dpkg-gencontrol</prgn> to make their
- control files and <prgn>dpkg-deb</prgn> to build
- them and place them in the parent of the top level
- directory.
+ <p>
+ Both <tt>binary-*</tt> targets should depend on the
+ <tt>build</tt> target, or on the appropriate
+ <tt>build-arch</tt> or <tt>build-indep</tt> target, if
+ provided, so that the package is built if it has not
+ been already. It should then create the relevant
+ binary package(s), using <tt>dpkg-gencontrol</tt> to
+ make their control files and <tt>dpkg-deb</tt> to
+ build them and place them in the parent of the top
+ level directory.
</p>
-
- <p>
- If one of the <prgn>binary-*</prgn> targets has
- nothing to do (this will be always be the case if
- the source generates only a single binary package,
- whether architecture-dependent or not) it
- <em>must</em> still exist, and must always
- succeed.
+
+ <p>
+ Both the <tt>binary-arch</tt> and
+ <tt>binary-indep</tt> targets <em>must</em> exist.
+ If one of them has nothing to do (which will always be
+ the case if the source generates only a single binary
+ package, whether architecture-dependent or not), it
+ must still exist and must always succeed.
</p>
- <p>
- The <prgn>binary</prgn> targets must be invoked as
- root.
+ <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>
-
+
<tag><tt>clean</tt></tag>
<item>
-
<p>
- This must undo any effects that the
- <prgn>build</prgn> and <prgn>binary</prgn> targets
- may have had, except that it should leave alone any
- output files created in the parent directory by a
- run of <prgn>binary</prgn>. This target must be
- non-interactive.
+ This must undo any effects that the <tt>build</tt>
+ and <tt>binary</tt> targets may have had, except
+ that it should leave alone any output files created in
+ the parent directory by a run of a <tt>binary</tt>
+ target. This target must be non-interactive.
</p>
- <p>
- If a <prgn>build</prgn> file is touched at the end
- of the <prgn>build</prgn> target, as suggested
- above, it should be removed as the first thing that
- <prgn>clean</prgn> does, so that running
- <prgn>build</prgn> again after an interrupted
- <prgn>clean</prgn> doesn't think that everything is
+ <p>
+ If a <tt>build</tt> file is touched at the end of
+ the <tt>build</tt> target, as suggested above, it
+ should be removed as the first action that
+ <tt>clean</tt> performs, so that running
+ <tt>build</tt> again after an interrupted
+ <tt>clean</tt> doesn't think that everything is
already done.
</p>
-
- <p>
- The <prgn>clean</prgn> target may need to be
- invoked as root if <prgn>binary</prgn> has been
- invoked since the last <prgn>clean</prgn>, or if
- <prgn>build</prgn> has been invoked as root (since
- <prgn>build</prgn> may create directories, for
+
+ <p>
+ The <tt>clean</tt> target may need to be
+ invoked as root if <tt>binary</tt> has been
+ invoked since the last <tt>clean</tt>, or if
+ <tt>build</tt> has been invoked as root (since
+ <tt>build</tt> may create directories, for
example).
</p>
</item>
-
+
<tag><tt>get-orig-source</tt> (optional)</tag>
<item>
-
- <p>
+ <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
current directory.
</p>
- <p>
+ <p>
This target may be invoked in any directory, and
should take care to clean up any temporary files it
may have left.
</p>
-
- <p>
+
+ <p>
This target is optional, but providing it if
possible is a good idea.
</p>
</item>
</taglist>
-
+
<p>
- The <prgn>build</prgn>, <prgn>binary</prgn> and
- <prgn>clean</prgn> targets must be invoked with a current
- directory of the package's top-level directory.
+ The <tt>build</tt>, <tt>binary</tt> and
+ <tt>clean</tt> targets must be invoked with the current
+ directory being the package's top-level directory.
</p>
-
-
- <p>
+
+
+ <p>
Additional targets may exist in <tt>debian/rules</tt>,
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. 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:
+ 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
+ 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
+ machine type we are building for). Here is a list of
+ supported <prgn>make</prgn> 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>
+ specification string)</p>
</item>
<item>
- <p><tt>DEB_*_GNU_CPU</tt> (the CPU part of DEB_*_GNU_TYPE)</p>
+ <p><tt>DEB_*_GNU_CPU</tt> (the CPU part of
+ <tt>DEB_*_GNU_TYPE</tt>)</p>
</item>
<item>
<p><tt>DEB_*_GNU_SYSTEM</tt> (the System part of
- DEB_*_GNU_TYPE)</p>
+ <tt>DEB_*_GNU_TYPE</tt>)</p>
</list>
- </p>
-
- <p>
where <tt>*</tt> is either <tt>BUILD</tt> for specification of
- the build machine or <tt>HOST</tt> for specification of the machine
- we build for.
+ the build machine or <tt>HOST</tt> for specification of the
+ host machine.
</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.
+ values; please refer to the documentation of
+ <prgn>dpkg-architecture</prgn> for details.
</p>
-
+
<p>
It is important to understand that the <tt>DEB_*_ARCH</tt>
string only determines which Debian architecture we are
used for that.
</p>
</sect>
-
+
<sect id="dpkgchangelog"><heading><tt>debian/changelog</tt>
</heading>
-
- <p>
+
+ <p>
This file records the changes to the Debian-specific parts of the
- package
- <footnote>
+ 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.
+ upstream maintainers become different people. In such a
+ case, however, it might be better to maintain the
+ package as a non-native package.
</p>
</footnote>.
</p>
-
- <p>
+
+ <p>
It has a special format which allows the package building
tools to discover which version of the package is being
built and find out other release-specific information.
</p>
-
+
<p>
- That format is a series of entries like this:
- <example>
- <var>package</var> (<var>version</var>) <var>distribution(s)</var>; urgency=<var>urgency</var>
-
- * <var>change details</var>
- <var>more change details</var>
- * <var>even more change details</var>
-
- -- <var>maintainer name and email address</var> <var>date</var>
+ 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>
-
- <p>
+
+ <p>
<var>package</var> and <var>version</var> are the source
package name and version number.
- </p>
-
- <p>
+ </p>
+
+ <p>
<var>distribution(s)</var> lists the distributions where
this version should be installed when it is uploaded - it
is copied to the <tt>Distribution</tt> field in the
<tt>.changes</tt> file. See <ref id="f-Distribution">.
</p>
-
- <p>
+
+ <p>
<var>urgency</var> is the value for the <tt>Urgency</tt>
field in the <tt>.changes</tt> file for the upload. It is
not possible to specify an urgency containing commas; commas
<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>
+ <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
line with the start of the text above. Blank lines may be
used here to separate groups of changes, if desired.
</p>
-
- <p>
- The maintainer name and email address need <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 <tt>.changes</tt> file, and then later used
- to send an acknowledgement when the upload has been
- installed.
+
+ <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 <var>date</var> should be in RFC822 format
- <footnote>
+
+ <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.
+ optionally present as a comment in parentheses.
</p>
-
- <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>
+
+ <p>
It is possible to use a different format to the standard
one, by providing a parser for the format you wish to
use.
</p>
- <p>
+ <p>
A changelog parser must not interact with the user at
all.
</p>
</sect1>
</sect>
-
+
<sect id="srcsubstvars"><heading><tt>debian/substvars</tt>
and variable substitutions </heading>
- <p>
+ <p>
When <prgn>dpkg-gencontrol</prgn>,
<prgn>dpkg-genchanges</prgn> and <prgn>dpkg-source</prgn>
- generate control files they do variable substitutions on
- their output just before writing it. Variable
- substitutions have the form
- <tt>${<var>variable-name</var>}</tt>. The optional file
- <tt>debian/substvars</tt> contains variable substitutions
- to be used; variables can also be set directly from
- <tt>debian/rules</tt> using the <tt>-V</tt> option to the
- source packaging commands, and certain predefined
- variables are available.
+ generate control files they perform variable substitutions
+ on their output just before writing it. Variable
+ substitutions have the form <tt>${<var>variable</var>}</tt>.
+ The optional file <tt>debian/substvars</tt> contains
+ variable substitutions to be used; variables can also be set
+ directly from <tt>debian/rules</tt> using the <tt>-V</tt>
+ option to the source packaging commands, and certain
+ predefined variables are also available.
</p>
- <p>
- The is usually generated and modified dynamically by
- <tt>debian/rules</tt> targets; in this case it must be
- removed by the <prgn>clean</prgn> target.
+ <p>
+ The <tt>debian/substvars</tt> file is usually generated and
+ modified dynamically by <tt>debian/rules</tt> targets; in
+ this case it must be removed by the <tt>clean</tt>
+ target.
</p>
<p>
details about source variable substitutions, including the
format of <tt>debian/substvars</tt>.</p>
</sect>
-
+
<sect id="debianfiles"><heading><tt>debian/files</tt>
</heading>
-
- <p>
+
+ <p>
This file is not a permanent part of the source tree; it
is used while building packages to record which files are
being generated. <prgn>dpkg-genchanges</prgn> uses it
when it generates a <tt>.changes</tt> file.
</p>
-
- <p>
+
+ <p>
It should not exist in a shipped source package, and so it
(and any backup files or temporary files such as
- <tt>files.new</tt>
- <footnote>
+ <tt>files.new</tt><footnote>
<p>
<tt>files.new</tt> is used as a temporary file by
<prgn>dpkg-gencontrol</prgn> and
occurs
</p>
</footnote>) should be removed by the
- <prgn>clean</prgn> target. It may also be wise to
+ <tt>clean</tt> target. It may also be wise to
ensure a fresh start by emptying or removing it at the
- start of the <prgn>binary</prgn> target.
+ start of the <tt>binary</tt> target.
</p>
-
- <p>
- <prgn>dpkg-gencontrol</prgn> adds an entry to this file
- for the <tt>.deb</tt> 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 <prgn>clean</prgn>.
+
+ <p>
+ When <prgn>dpkg-gencontrol</prgn> is run for a binary
+ package, it adds an entry to <tt>debian/files</tt> for the
+ <tt>.deb</tt> file that will be created when <tt>dpkg-deb
+ --build</tt> is run for that binary package. So for most
+ packages all that needs to be done with this file is to
+ delete it in the <tt>clean</tt> target.
</p>
-
- <p>
+
+ <p>
If a package upload includes files besides the source
package and any binary packages whose control files were
made with <prgn>dpkg-gencontrol</prgn> then they should be
<sect id="restrictions"><heading>Restrictions on objects in source packages
</heading>
-
- <p>
- The source package may not contain any hard links
- <footnote>
+
+ <p>
+ The source package may not contain any hard links<footnote>
<p>
This is not currently detected when building source
packages, but only when extracting
them.
</p>
- </footnote>
- <footnote>
<p>
Hard links may be permitted at some point in the
future, but would require a fair amount of
work.
</p>
</footnote>, device special files, sockets or setuid or
- setgid files.
- <footnote>
+ setgid files.<footnote>
<p>
Setgid directories are allowed.
</p>
</sect>
<sect id="descriptions"><heading>Descriptions of packages - the
<tt>Description</tt> field </heading>
-
- <p>
+
+ <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
and others, so that the user knows why these dependencies and
conflicts have been declared.
</p>
-
+
<sect1><heading>Notes about writing descriptions
</heading>
- <p>
+ <p>
The single line synopsis should be kept brief - certainly
- under 80 characters.
+ under 80 characters.
</p>
-
- <p>
+
+ <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>
+
+ <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
available.
</p>
- <p>
+ <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>
+
+ <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>
+ package deals with.<footnote>
<p>
The blurb that comes with a program in its
announcements and/or <prgn>README</prgn> files is
</p>
</footnote>
</p>
-
- <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>
+
+ <p>
You may include information about dependencies and so forth
in the extended description, if you wish.
</p>
-
- <p>
+
+ <p>
Do not use tab characters. Their effect is not predictable.
</p>
<sect><heading>Introduction to package maintainer scripts
</heading>
- <p>
+ <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.
</p>
- <p>
- These scripts should be the files <tt>preinst</tt>,
- <tt>postinst</tt>, <tt>prerm</tt> and <tt>postrm</tt> in the
+ <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
+ 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.
</p>
- <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
well.
</p>
- <p>
- It is necessary for the error recovery procedures that the
- scripts be idempotent: i.e., invoking the same script several
- times in the same situation should do no harm. 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.
- </p>
-
- <p>
+ <p>
When a package is upgraded a combination of the scripts from
- the old and new packages is called in amongst the other
- steps of 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 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>
- <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.
+ <prgn>postrm</prgn> afterwards.
</p>
- <!--
- next paragraph by Guy Maor to close bug #2481
- -->
-
- <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>,
+
+ <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 on the <tt>PATH</tt>,
- should thus be invoked without an absolute
+ 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 pre-
- or appending package-specific directories. These
+ <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>
<p>
- It is very important to make maintainer scripts
- idempotent.
- <footnote>
+ 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>
- 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.
+ 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> 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.
+ </footnote>
</p>
</sect>
+
<sect>
<heading>Controlling terminal for maintainer scripts</heading>
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>
</sect>
-
+
<sect id="mscriptsinstact"><heading>Summary of ways maintainer
scripts are called
</heading>
- <p>
+ <p>
<list compact="compact">
<item>
<p><var>new-preinst</var> <tt>install</tt></p>
<p><var>old-preinst</var> <tt>abort-upgrade</tt>
<var>new-version</var>
</p>
- </item>
+ </item>
</list>
- <p>
+ <p>
<list compact="compact">
<item>
<p><var>postinst</var> <tt>configure</tt>
</item>
<item>
<p><var>old-postinst</var> <tt>abort-upgrade</tt>
- <var>new version</var></p>
+ <var>new-version</var></p>
</item>
<item>
<p><var>conflictor's-postinst</var> <tt>abort-remove</tt>
</item>
</list>
- <p>
+ <p>
<list compact="compact">
<item>
<p><var>prerm</var> <tt>remove</tt></p>
</item>
</list>
- <p>
+ <p>
<list compact="compact">
<item>
<p><var>postrm</var> <tt>remove</tt></p>
<var>overwriter-version</var></p></item>
</list>
</p>
-
-
+
+
<sect id="unpackphase"><heading>Details of unpack phase of
installation or upgrade
</heading>
- <p>
+ <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 an error occurs 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.
-
+ 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>
<p>
<item>
<p>If a version of the package is already
installed, call
- <example>
- <var>old-prerm</var> upgrade <var>new-version</var>
+ <example compact="compact">
+<var>old-prerm</var> upgrade <var>new-version</var>
</example></p>
</item>
<item>
<p>
- If this gives an error (i.e., a non-zero exit
- status), dpkg will attempt instead:
- <example>
- <var>new-prerm</var> failed-upgrade <var>old-version</var>
+ 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>
- <var>old-postinst</var> abort-upgrade <var>new-version</var>
+ <example compact="compact">
+<var>old-postinst</var> abort-upgrade <var>new-version</var>
</example>
</p>
</item>
If any packages depended on that conflicting
package and <tt>--auto-deconfigure</tt> is
specified, call, for each such package:
- <example>
- <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 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>
- <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>
+ <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
</item>
<item>
<p>To prepare for removal of the conflicting package, call:
- <example>
- <var>conflictor's-prerm</var> remove in-favour <var>package</var> <var>new-version</var>
+ <example compact="compact">
+<var>conflictor's-prerm</var> remove \
+ in-favour <var>package</var> <var>new-version</var>
</example>
Error unwind:
- <example>
- <var>conflictor's-postinst</var> abort-remove \
- in-favour <var>package</var> <var>new-version</var>
+ <example compact="compact">
+<var>conflictor's-postinst</var> abort-remove \
+ in-favour <var>package</var> <var>new-version</var>
</example>
</p>
</item>
<enumlist>
<item>
<p>If the package is being upgraded, call:
- <example>
- <var>new-preinst</var> upgrade <var>old-version</var>
+ <example compact="compact">
+<var>new-preinst</var> upgrade <var>old-version</var>
</example></p>
</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>
- <var>new-preinst</var> install <var>old-version</var>
+ <example compact="compact">
+<var>new-preinst</var> install <var>old-version</var>
</example></p>
-
+
<item>
<p>Otherwise (i.e., the package was completely purged):
- <example>
- <var>new-preinst</var> install
+ <example compact="compact">
+<var>new-preinst</var> install
</example>
- Error unwind versions, respectively:
- <example>
- <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
+ 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>
</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 left
- around, and if anything goes wrong the package
+ 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).
+ part of the error unwind.
</p>
- <p>
+ <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">).
- Currently the <tt>--force-overwrite</tt> flag is
+ <!--
+ 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>
+ <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
advisable.
</p>
- <p>
+ <p>
Packages which overwrite each other's files produce
- behavior which though deterministic is hard for the
+ 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>
+ package, and is then removed again.<footnote>
<p>
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 links
+ <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>
+ <p>
+ <enumlist>
<item>
<p>If the package is being upgraded, call
- <example>
- <var>old-postrm</var> upgrade <var>new-version</var>
- </example></p>
+ <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>
- <var>new-postrm</var> failed-upgrade <var>old-version</var>
+ <example compact="compact">
+<var>new-postrm</var> failed-upgrade <var>old-version</var>
</example>
Error unwind, for both cases:
- <example>
- <var>old-preinst</var> abort-upgrade <var>new-version</var>
+ <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
</p>
</item>
<item>
- <p>
+ <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 maintainer scripts replace the old.</p>
</item>
-
+
<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,
+ For each such package
<enumlist>
<item>
<p><prgn>dpkg</prgn> calls:
- <example>
- <var>disappearer's-postrm</var> disappear \
- <var>overwriter</var> <var>overwriter-version</var>
+ <example compact="compact">
+<var>disappearer's-postrm</var> disappear \
+ <var>overwriter</var> <var>overwriter-version</var>
</example>
</p>
</item>
deleted.
</p>
</item>
-
+
<item>
<p>
The new package's status is now sane, and recorded as
- `unpacked'. 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.
+ `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>
<p>
If there was a conflicting package we go and do the
</p>
</sect>
- <sect><heading>Details of configuration</heading>
+ <sect id="configdetails"><heading>Details of configuration</heading>
- <p>
+ <p>
When we configure a package (this happens with <tt>dpkg
- --install</tt>, or with <tt>--configure</tt>), we first
- update the conffiles and then call:
- <example>
- <var>postinst</var> configure <var>most-recently-configured-version</var>
+ --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>
+ <p>
No attempt is made to unwind after errors during
configuration.
</p>
- <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
second argument at all, under any circumstances.
</p>
</sect>
-
- <sect><heading>Details of removal and/or configuration purging
- </heading>
- <p>
+ <sect id="removedetails"><heading>Details of removal and/or
+ configuration purging</heading>
+
+ <p>
<enumlist>
<item>
<p>
- <example>
- <var>prerm</var> remove
+ <example compact="compact">
+<var>prerm</var> remove
</example>
</p>
</item>
<item>
<p>
- The package's files are removed (except conffiles).
+ The package's files are removed (except <tt>conffile</tt>s).
</p>
</item>
<item>
- <p><example>
- <var>postrm</var> remove
- </example></p>
+ <p>
+ <example compact="compact">
+<var>postrm</var> remove
+ </example>
+ </p>
</item>
<item>
- <p>All the maintainer scripts except the postrm are removed.
+ <p>
+ All the maintainer scripts except the <prgn>postrm</prgn>
+ are removed.
</p>
- <p>
+ <p>
If we aren't purging the package we stop here. Note
- that packages which have no postrm and no conffiles
- are automatically purged when removed, as there is no
- difference except for the <prgn>dpkg</prgn>
- status.</p>
+ that packages which have no <prgn>postrm</prgn> and no
+ <tt>conffile</tt>s are automatically purged when
+ removed, as there is no difference except for the
+ <prgn>dpkg</prgn> status.</p>
</item>
<item>
<p>
- The conffiles and any backup files (<tt>~</tt>-files,
- <tt>#*#</tt> files, <tt>%</tt>-files,
- <tt>.dpkg-{old,new,tmp}</tt>, etc.) are removed.</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>
- <var>postrm</var> purge
- </example></p>
+ <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>
+ removal.
+ </p>
</sect>
</chapt>
-
+
<chapt id="relationships"><heading>Declaring relationships between
- packages </heading>
+ packages</heading>
- <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
if present.
</p>
- <p>
- This is done using the <tt>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>
+ This is done using the <tt>Depends</tt>, <tt>Pre-Depends</tt>,
+ <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
+ <tt>Conflicts</tt>, <tt>Provides</tt> and <tt>Replaces</tt>
+ control file fields.
</p>
<p>
Source packages may declare relationships to binary packages,
- saying that they require certain binary packages being
+ saying that they require certain binary packages to be
installed or absent at the time of building the package.
</p>
-
+
<p>
This is done using the <tt>Build-Depends</tt>,
- <tt>Build-Depends-Indep</tt>, <tt>Build-Conflicts</tt>, and
+ <tt>Build-Depends-Indep</tt>, <tt>Build-Conflicts</tt> and
<tt>Build-Conflicts-Indep</tt> control file fields.
</p>
<sect id="depsyntax"><heading>Syntax of relationship fields
</heading>
- <p>
+ <p>
These fields all have a uniform syntax. They are a list of
package names separated by commas.
</p>
<p>
- In <tt>Depends</tt>, <tt>Recommends</tt>, <tt>Suggests</tt>,
- <tt>Pre-Depends</tt>, <tt>Build-Depends</tt> and
- <tt>Build-Depends-Indep</tt>(the fields which declare
- dependencies of the package in which they occur on other
- packages) these package names may also be lists of
- alternative package names, separated by vertical bar symbols
- <tt>|</tt> (pipe symbols).
- </p>
-
- <p>
- All the fields except <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
+ 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="versions">.
</p>
- <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 forms
- <tt><</tt> and <tt>></tt> were used to mean
+ 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>
+ <p>
Whitespace may appear at any point in the version
- specification, and must appear where it's necessary to
+ 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 usual also to put a single space after each
- comma, on either side of each vertical bar, and before each
- open parenthesis.
+ 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>
- <p>
- For example:
- <example>
- Package: metamail
- Version: 2.7-3
- Depends: libc5 (>= 5.2.18-4), mime-support, csh | tcsh
+ <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 done in brackets after each individual package name and
+ 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.
- An exclamation mark may be prepended to each name. 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.
+ 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>
For example:
- <example>
- Source: glibc
- Build-Depends-Indep: texinfo
- Build-Depends: kernel-headers-2.2.10 [!hurd-i386],
- hurd-dev [hurd-i386], gnumach-dev [hurd-i386]
+ <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>
+
+ <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>
<heading>Binary Dependencies - <tt>Depends</tt>,
<tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
<tt>Pre-Depends</tt>
</heading>
- <p>
+ <p>
These five fields are used to declare a dependency
- relationship by one package on another. They appear in the
- depending package's control file.
+ 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>
- All but <tt>Pre-Depends</tt> and <tt>Conflicts</tt>
- (discussed below) take effect <em>only</em> when a package
- is to be configured. They do 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.
+ <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>
- <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
dependencies satisfied.
</p>
- <p>
- Thus <tt>Depends</tt> allows package maintainers to impose
- an order in which packages should be configured.
+ <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.
+ <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>
+ <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>
+ 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>
+ <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>
-
<p>
This is used to declare that one package may be more
useful with one or more others. Using this field
package.
</p>
</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.
+ pre-dependency, as follows:
</p>
- <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>
- When the package declaring it is being configured, a
- <tt>Pre-Dependency</tt> will be considered satisfied
- only if the depending package has been correctly
- configured, just as if an ordinary <tt>Depends</tt>
- had been used.
- </p>
-
- <p>
- However, when a package declaring a Pre-dependency is
- being unpacked the predependency can be satisfied even
- if 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>
+ <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>
+ <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
</p>
- <sect id="conflicts"><heading>Alternative binary packages -
- <tt>Conflicts</tt> and <tt>Replaces</tt>
- </heading>
+ <sect id="conflicts"><heading>Conflicting binary packages -
+ <tt>Conflicts</tt></heading>
- <p>
+ <p>
When one binary package declares a conflict with another
- <prgn>dpkg</prgn> will refuse to allow them to be installed
- on the system at the same time.
+ 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>
+ <p>
If one package is to be installed, the other must be removed
first - if the package being installed is marked as
- replacing (<ref id="replaces">) the one on the system, or
- the one on the system is marked as deselected, or both
+ 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 specifically doesn't work when the installed
- package is <tt>Essential</tt>, but the new package is not.
+ 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>
+ <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>
+ <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 something.
+ package providing some feature.
</p>
- <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.
+ of the conflicted-with package had been completed.
</p>
</sect>
-
+
<sect id="virtual"><heading>Virtual packages - <tt>Provides</tt>
</heading>
- <p>
+ <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>Recommends</tt>, <tt>Suggests</tt>, <tt>Conflicts</tt>,
- <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt> may
- mention virtual packages.
+ <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>
+ may mention `virtual packages'.
</p>
- <p>
- A virtual package is one which appears in the
+ <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>
- <p>
+ <p>
If there are both a real and a virtual package of the same
name then the dependency may be satisfied (or the conflict
caused) by either the real package or any of the virtual
packages which provide it. This is so that, for example,
supposing we have
- <example>
- Package: vm
- Depends: emacs
+ <example compact="compact">
+Package: foo
+Depends: bar
</example>
- and someone else releases an xemacs package they can say
- <example>
- Package: xemacs
- Provides: emacs
- </example> and all will work in the interim (until a purely
- virtual package name is decided on and the <tt>emacs</tt>
- and <tt>vm</tt> packages are changed to use it).
+ 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>
- <p>
+ <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 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.
+ 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>
+ <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
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.
+ <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><tt>Replaces</tt> - overwriting
- files and replacing packages
- </heading>
- <p>
- The <tt>Replaces</tt> control file field has two purposes,
- which come into play in different situations.
- </p>
- <p>
- Virtual packages (<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.
+ <sect id="replaces"><heading>Overwriting files and replacing
+ packages - <tt>Replaces</tt></heading>
+
+ <p>
+ The <tt>Replaces</tt> control file field has two distinct
+ purposes, which come into play in different situations.
</p>
-
- <sect1><heading>Overwriting files in other packages
- </heading>
- <p>
+ <sect1><heading>Overwriting files in other packages</heading>
+
+ <p>
Firstly, as mentioned before, it is usually an error for a
- package to contains files which are on the system in
- another package, though currently the
- <tt>--force-overwrite</tt> flag is enabled by default,
- downgrading the error to a warning,
+ package to contain files which are on the system in
+ another package.
</p>
- <p>
- If the overwriting package declares that it replaces the
- one containing the file being overwritten then
- <prgn>dpkg</prgn> will proceed, and 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>
+ 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>
+ <p>
If a package is completely replaced in this way, so that
<prgn>dpkg</prgn> does not know of any files it still
- contains, it is considered to have disappeared. It will
+ contains, it is considered to have `disappeared'. It will
be marked as not wanted on the system (selected for
- removal) and not installed. Any conffiles details noted
- in the package will be ignored, as they will have been
- taken over by the replacing package(s). The package's
- <prgn>postrm</prgn> script will be run to allow the
- package to do any final cleanup required. See <ref
- id="mscriptsinstact">.
+ 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">.
</p>
- <p>
- In the future <prgn>dpkg</prgn> will discard files which
- overwrite those from another package which declares that
- it replaces the one being installed (so that you can
- install an older version of a package without problems).
+ <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.
+ </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>
- <p>
- 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>
+ removal</heading>
- <p>
+ <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 effects do not interfere with each other.
+ 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>
<p>
A source package may declare a dependency or a conflict on a
- binary 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>. Their
- semantics is that the dependencies and conflicts they define
- must be satisfied (as defined earlier for binary packages),
- when one of the targets in <tt>debian/rules</tt> that the
- particular field applies to is invoked.
+ 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:
<taglist>
<tag><tt>Build-Depends</tt>, <tt>Build-Conflicts</tt></tag>
<item>
<p>
The <tt>Build-Depends</tt> and
- <tt>Build-Conflicts</tt> fields apply to the targets
+ <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>
<p>
The <tt>Build-Depends-Indep</tt> and
- <tt>Build-Conflicts-Indep</tt> fields apply to the
- targets <tt>binary</tt> and <tt>binary-indep</tt>.
+ <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>
<chapt id="conffiles"><heading>Configuration file handling
</heading>
- <p>
- <prgn>dpkg</prgn> can do a certain amount of automatic
- handling of package configuration files.
- </p>
-
- <p>
- Whether this mechanism is appropriate depends on a number of
- factors, but basically there are two approaches to any
- particular configuration file.
- </p>
-
- <p>
- The easy method is to ship a best-effort configuration in the
- package, and use <prgn>dpkg</prgn>'s conffile mechanism to
- handle updates. If the user is unlikely to want to edit the
- file, but you need them to be able to without losing their
- changes, and a new package with a changed version of the file
- is only released infrequently, this is a good approach.
+ <p>
+ This chapter has been superseded by <ref id="config files">.
</p>
- <p>
- The hard method is to build the configuration file from
- scratch in the <prgn>postinst</prgn> script, and to take the
- responsibility for fixing any mistakes made in earlier
- versions of the package automatically. This will be
- appropriate if the file is likely to need to be different on
- each system.
- </p>
-
- <chapt id="sharedlibs"><heading>Shared libraries
- </heading>
+ <chapt id="sharedlibs"><heading>Shared libraries</heading>
- <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 libc.
+ shared libraries are vitally important, such as the C library
+ (currently <tt>libc6</tt>).
</p>
- <p>
- Firstly, your package should install the shared libraries
- under their normal names. For example, the
- <prgn>libgdbm1</prgn> package should install
- <tt>libgdbm.so.1.7.3</tt> as
+ <p>
+ Firstly, the package should install the shared libraries under
+ their normal names. For example, the <tt>libgdbmg1</tt>
+ package should install <tt>libgdbm.so.1.7.3</tt> as
<tt>/usr/lib/libgdbm.so.1.7.3</tt>. The files should not be
- renamed or re-linked by any prerm or postrm 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.
+ 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>
- Secondly, your package should include the symlink that
+ <p>
+ Secondly, the package should include the symbolic link that
<prgn>ldconfig</prgn> would create for the shared libraries.
- For example, the <prgn>libgdbm1</prgn> package should include
- a symlink from <tt>/usr/lib/libgdbm.so.1</tt> to
- <tt>libgdbm.so.1.7.3</tt>. This is needed so that
- <prgn>ld.so</prgn> can find the library in between the time
- <prgn>dpkg</prgn> installs it and <prgn>ldconfig</prgn> is run
- in the <prgn>postinst</prgn> script. Furthermore, older
- versions of the package management system required the library
- must be placed before the symlink pointing to it in the
- <tt>.deb</tt> file. This is so that by the time
- <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.
- Unfortunately, this was not not always possible, since it
- highly depends on the behavior of the file system. Some
- file systems (such as reiserfs) will reorder the files so it
- doesn't matter in what order you create them. Starting with
- release <tt>1.7.0</tt> <prgn>dpkg</prgn> will reorder the
- files itself when building a package.
+ For example, the <prgn>libgdbmg1</prgn> package should include
+ a symbolic link from <tt>/usr/lib/libgdbm.so.1</tt> to
+ <tt>libgdbm.so.1.7.3</tt>. This is needed so that the dynamic
+ 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
+ <tt>.deb</tt> 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
+ <tt>.deb</tt> 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.
+ </p>
+ </footnote>
</p>
- <!--
- next Paragraph added to close Bug #5299, Guy Maor
- -->
-
- <p>
- Thirdly, the development package should contain a symlink for
- the shared library without a version number. For example, the
- <tt>libgdbm1-dev</tt> package should include a symlink from
- <tt>/usr/lib/libgdm.so</tt> to <tt>libgdm.so.1.7.3</tt>. This
- symlink is needed by <prgn>ld</prgn> when compiling packages
- as it will only look for <tt>libgdm.so</tt> and
- <tt>libgdm.a</tt> when compiling dynamically or statically,
- respectively.
+ <p>
+ Thirdly, the associated development package should contain a
+ symlink for the shared library without a version number. For
+ example, the <tt>libgdbmg1-dev</tt> package should include a
+ symlink from <tt>/usr/lib/libgdbm.so</tt> to
+ <tt>libgdbm.so.1.7.3</tt>. This symlink is needed by the
+ linker (<prgn>ld</prgn>) when compiling packages, as it will
+ only look for <tt>libgdbm.so</tt> when compiling dynamically.
</p>
- <!--
- next paragraph changed by Christian Schwarz (see policy weekly #6)
- -->
-
- <p>
- Any package installing shared libraries in a directory that's listed
- in <tt>/etc/ld.so.conf</tt> or in one of the default library
- directories of <prgn>ld.so</prgn> (currently, these are <tt>/usr/lib</tt>
- and <tt>/lib</tt>) must call <prgn>ldconfig</prgn> in its <prgn>postinst</prgn>
- script if and only if the first argument is `configure'. However, it
- is important not to call <prgn>ldconfig</prgn> in the postrm or preinst
- scripts in the case where the package is being upgraded (see <ref
- id="unpackphase">), as <prgn>ldconfig</prgn> will see the temporary names
- that <prgn>dpkg</prgn> uses for the files while it is
+ <p>
+ Any package installing shared libraries in one of the default
+ library directories of the dynamic linker (which are currently
+ <tt>/usr/lib</tt> and <tt>/lib</tt>) or a directory that is
+ listed in <tt>/etc/ld.so.conf</tt><footnote>
+ <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>
+ </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>
+
+ <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 removes the links!
+ installation and renames the temporary files!
</p>
- <!--
- moved from section 2.2 , DMorris
- -->
-
- <sect id="shlibs"><heading>The <tt>shlibs</tt> File Format
- </heading>
-
- <p>
- This file is for use by <prgn>dpkg-shlibdeps</prgn> and is
- required when your package provides shared libraries.
- </p>
-
- <p>
- Each line is of the form:
- <example>
- <var>library-name</var> <var>version-or-soname</var> <var>dependencies ...</var>
- </example>
- </p>
+ <sect>
+ <heading>Handling shared library dependencies - 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 <tt>shlibs</tt> files.
+ </p>
+
+ <p>
+ Thus, when a package is built which contains any shared
+ libraries, it must provide a <tt>shlibs</tt> 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>
- <var>library-name</var> is the name of the shared library,
- for example <tt>libc5</tt>.
- </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>
- <var>version-or-soname</var> is the soname of the library -
- i.e., the thing that must exactly match for the library to be
- recognized by <prgn>ld.so</prgn>. Usually this is major
- version number of the library.
- </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>
- <var>dependencies</var> has the same syntax as a dependency
- field in a binary package control file. It should give
- details of which package(s) are required to satisfy a binary
- built against the version of the library contained in the
- package. See <ref id="depsyntax">.
+ <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>
- For example, if the package <tt>foo</tt> contains
- <tt>libfoo.so.1.2.3</tt>, where the soname of the library is
- <tt>libfoo.so.1</tt>, and the first version of the package
- which contained a minor number of at least <tt>2.3</tt> was
- <var>1.2.3-1</var>, then the package's <var>shlibs</var>
- could say:
- <example>
- libfoo 1 foo (>= 1.2.3-1)
- </example>
+ <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>
-
- <p>
- The version-specific dependency is to avoid warnings from
- <prgn>ld.so</prgn> about using older shared libraries with
- newer binaries.</p>
</sect>
-
- <sect><heading>Further Technical information on
- <tt>shlibs</tt></heading>
-
- <!--
- following section mostly provided by Heiko Schlittermann
- edited by DMorris
- -->
-
- <sect1><heading><em>What</em> are the <tt>shlibs</tt> files?
- </heading>
+ <sect><heading>The <tt>shlibs</tt> files present on the system
+ </heading>
- <p>
- The <tt>debian/shlibs</tt> file provides a way of checking
- for shared library dependencies on packaged binaries.
- They are intended to be used by package maintainers to
- make their lives easier.
- </p>
+ <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.)
+ </p>
- <p>
- Other <tt>shlibs</tt> files that exist on a Debian system are
- <list>
- <item> <p><tt>/etc/dpkg/shlibs.default</tt></p></item>
- <item> <p><tt>/etc/dpkg/shlibs.override</tt></p></item>
- <item> <p><tt>/var/lib/dpkg/info/*.shlibs</tt></p></item>
- <item> <p><tt>debian/shlibs.local</tt></p></item>
- </list>
- These files are used by <prgn>dpkg-shlibdeps</prgn> when
- creating a binary package.</p>
- </sect1>
-
- <sect1><heading><em>How</em> does <prgn>dpkg-shlibdeps</prgn>
- work?
- </heading>
- <p>
- <prgn>dpkg-shlibdeps</prgn>
- determines the shared libraries directly
- <footnote>
- <p>
- Currently, it calls <prgn>ldd</prgn>, but in a
- forthcoming version it shall call <prgn>objdump</prgn>
- to to this. This however changes will need a couple of
- changes in the way that packages are build.
+ <p>
+ <list>
+ <item>
+ <p><tt>debian/shlibs.local</tt></p>
+ <p>
+ This lists overrides for this package. Its use is
+ described below (see <ref id="shlibslocal">).
</p>
+ </item>
+
+ <item>
+ <p><tt>/etc/dpkg/shlibs.override</tt></p>
<p>
- Suppose a binary <tt>foo</tt> directly use a library
- <tt>libbar</tt> if it is linked with that
- library. Other libraries that are needed by
- <tt>libbar</tt> are linked indirectly to <tt>foo</tt>,
- and the dynamic linker will load the automatically
- when it loads <tt>libbar</tt>. Using <prgn>ldd</prgn>
- lists all the libraries, used directly and indirectly;
- but <prgn>objdump</prgn> only lists the directly
- linked libraries. A package only needs to depend on
- the libraries it is directly linked to, since the
- dependencies for those libraries should automatically
- pull in the other libraries.</p>
-
- <p>
- This change does mean a change in the way packages are
- build though: currently dpkg-shlibdeps is only run on
- binaries. But since we will now depend on the
- libraries to depend on the libraries they need the
- packages containing those libraries will need to run
- dpkg-shlibdeps on the libraries.
+ This lists global overrides. This list is normally
+ empty. It is maintained by the local system
+ administrator.
</p>
+ </item>
+
+ <item>
+ <p><tt>DEBIAN/shlibs</tt> files in the `build directory'</p>
<p>
- A good example where this would help us is the current
- mess with multiple version of the mesa library. With
- the ldd-based system every package that uses mesa need
- to add a dependency on svgalib|svgalib-dummy in order
- to handle the glide mesa variant. With an
- objdump-based system this isn't necessary anymore and
- would have saved everyone a lot of work.
+ When packages are being built, any
+ <tt>debian/shlibs</tt> files are copied into the
+ control file area of the temporary build directory and
+ given the name <tt>shlibs</tt>. 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 <tt>debian/libfoo2</tt> and
+ <tt>debian/foo-runtime</tt> respectively.
+ (<tt>debian/tmp</tt> could be used instead of one
+ of these.) Since <tt>libfoo2</tt> provides the
+ <tt>libfoo</tt> shared library, it will require a
+ <tt>shlibs</tt> file, which will be installed in
+ <tt>debian/libfoo2/DEBIAN/shlibs</tt>, eventually
+ to become
+ <tt>/var/lib/dpkg/info/libfoo2.shlibs</tt>. Then
+ when <prgn>dpkg-shlibdeps</prgn> is run on the
+ executable
+ <tt>debian/foo-runtime/usr/bin/foo-prog</tt>, it
+ will examine the
+ <tt>debian/libfoo2/DEBIAN/shlibs</tt> 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>
+
+ <item>
+ <p><tt>/var/lib/dpkg/info/*.shlibs</tt></p>
<p>
- Another example: we could update libimlib with a new
- version that supports a new graphics format called
- dgf. If we use the old ldd method every package that
- uses libimlib would need to be recompiled so it would
- also depend on libdgf or it wouldn't run due to
- missing symbols. However with the new system packages
- using libimlib can depend on libimlib itself having
- the dependency on libgdh and wouldn't need to be
- updated.
+ These are the <tt>shlibs</tt> files corresponding to
+ all of the packages installed on the system, and are
+ maintained by the relevant package maintainers.
</p>
- </footnote>
- used by the compiled binaries (and libraries, in a version
- of <prgn>dpkg-shlibdeps</prgn> coming soon) passed through
- on its command line.
- </p>
+ </item>
- <p>
- For each shared library, <prgn>dpkg-shlibdeps</prgn> needs to know
- <list compact="compact">
- <item><p>the package containing the library, and</p></item>
- <item><p>the library version number,</p></item>
+ <item>
+ <p><tt>/etc/dpkg/shlibs.default</tt></p>
+ <p>
+ This file lists any shared libraries whose packages
+ have failed to provide correct <tt>shlibs</tt> files.
+ It was used when the <tt>shlibs</tt> setup was first
+ introduced, but it is now normally empty. It is
+ maintained by the <tt>dpkg</tt> maintainer.
+ </p>
+ </item>
+ </list>
+ </p>
+ </sect>
- </list> <p>
- it scans the following files in this order.
- <enumlist compact="compact">
- <item><p><tt>debian/shlibs.local</tt></p></item>
- <item><p><tt>/etc/dpkg/shlibs.override</tt></p></item>
- <item><p><tt>/var/lib/dpkg/info/*.shlibs</tt></p></item>
- <item><p><tt>/etc/dpkg/shlibs.default</tt></p></item>
- </enumlist></p>
- </sect1>
-
- <sect1><heading><em>Who</em> maintains the various
- <tt>shlibs</tt> files?
- </heading>
+ <sect>
+ <heading>How to use <prgn>dpkg-shlibdeps</prgn> and the
+ <tt>shlibs</tt> files</heading>
- <p>
- <list compact="compact">
- <item>
- <p><tt>/etc/dpkg/shlibs.default</tt> - the maintainer
- of dpkg</p>
- </item>
- <item>
- <p>
- <tt>/var/lib/dpkg/info/<var>package</var>.shlibs</tt>
- - the maintainer of each package</p>
- </item>
- <item>
- <p>
- <tt>/etc/dpkg/shlibs.override</tt> - the local
- system administrator</p>
- </item>
- <item>
- <p><tt>debian/shlibs.local</tt> - the maintainer of
- the package
- </p>
- </item>
- </list>
- The <tt>shlibs.default</tt> file is managed by
- <prgn>dpkg</prgn>. The entries in <tt>shlibs.default</tt>
- that are provided by <prgn>dpkg</prgn> are just there to
- fix things until the shared library packages all have
- <tt>shlibs</tt> files.
- </p>
- </sect1>
+ <p>
+ Put a call to <prgn>dpkg-shlibdeps</prgn> into your
+ <tt>debian/rules</tt> 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>
+ </footnote>
+ </p>
- <sect1><heading><em>How</em> to use <prgn>dpkg-shlibdeps</prgn> and
- the <tt>shlibs</tt> files?
- </heading>
-
- <sect2><heading>If your package doesn't provide a shared
- library
- </heading>
+ <p>
+ This command puts the dependency information into the
+ <tt>debian/substvars</tt> 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>
- <p>
- Put a call to <prgn>dpkg-shlibdeps</prgn> into your
- <tt>debian/rules</tt> file. If your package contains
- only binaries (e.g. no scripts) use:
- <example>
- dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/*
- </example>
- If <prgn>dpkg-shlibdeps</prgn> doesn't complain, you're
- done. If it does complain you might need to create your
- own <tt>debian/shlibs.local</tt> file.</p>
- </sect2>
+ <p>
+ If <prgn>dpkg-shlibdeps</prgn> doesn't complain, you're
+ done. If it does complain you might need to create your own
+ <tt>debian/shlibs.local</tt> file, as explained below (see
+ <ref id="shlibslocal">).
+ </p>
- <sect2><heading>If your package provides a shared library
- </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 <tt>substvars</tt> file.
+ For more details on this and other options, see <manref
+ name="dpkg-shlibdeps" section="1">.
+ </p>
+ </sect>
- <p>
- Create a <tt>debian/shlibs</tt> file and let
- <tt>debian/rules</tt> install it in the control area:
- <example>
- install -m644 debian/shlibs debian/tmp/DEBIAN
- </example>
- If your package contains additional binaries see above.
- </p>
- </sect2>
- </sect1>
+ <sect id="shlibs"><heading>The <tt>shlibs</tt> File Format
+ </heading>
- <sect1><heading><em>How</em> to write
- <tt>debian/shlibs.local</tt>
- </heading>
+ <p>
+ Each <tt>shlibs</tt> 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>
- <p>
- This file is intended only as a <em>temporary</em> fix if
- your binaries depend on a library which doesn't provide
- its own <tt>/var/lib/dpkg/info/*.shlibs</tt> file yet.
- </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 <tt>/usr/lib/libz.so.1.1.3</tt>.
+ </p>
- <p>
- Let's assume you are packaging a binary <tt>foo</tt>. Your
- output in building the package might look like this.
- <example>
- $ ldd foo
- libbar.so.1 => /usr/X11R6/lib/libbar.so.1.0
- libc.so.5 => /lib/libc.so.5.2.18
- libX11.so.6 => /usr/X11R6/lib/libX11.so.6.0
- </example>
- And when you ran <prgn>dpkg-shlibdeps</prgn>
- <example>
- $ dpkg-shlibdeps -o foo
- dpkg-shlibdeps: warning: unable to find dependency information
- for shared library libbar
- (soname 1, path /usr/X11R6/lib/libbar.so.1.0, dependency field Depends)
- shlibs:Depends=elf-x11r6lib, libc5 (>= 5.2.18)
- </example>
- The <prgn>foo</prgn> binary depends on the
- <prgn>libbar</prgn> shared library, but no package seems
- to provide a <tt>*.shlibs</tt> file in
- <tt>var/lib/dpkg/info/</tt>. Let's determine the package
- responsible:
- </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>
- <example>
- $ dpkg -S /usr/X11R6/lib/libbar.so.1.0
- bar1: /usr/X11R6/lib/libbar.so.1.0
- $ dpkg -s bar1 | grep Version
- Version: 1.0-1
- </example>
- This tells us that the <prgn>bar1</prgn> package, version
- 1.0-1 is the one we are using. Now we can create our own
- <tt>debian/shlibs.local</tt> to temporarily fix the above
- problem. Include the following line into your
- <tt>debian/shlibs.local</tt> file.
- <example>
- libbar 1 bar1 (>= 1.0-1)
- </example>
- Now your package build should work. As soon as the
- maintainer of <prgn>libbar1</prgn> provides a
- <tt>shlibs</tt> file, you can remove your
- <tt>debian/shlibs.local</tt> file.
- </p>
- </sect1>
+ <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>.
+ </p>
+
+ <p>
+ <var>dependencies</var> has the same syntax as a dependency
+ field in a binary package control file. It should give
+ details of which packages are required to satisfy a binary
+ built against the version of the library contained in the
+ package. See <ref id="depsyntax"> for details.
+ </p>
+
+ <p>
+ In our example, if the first version of the <tt>zlib1g</tt>
+ package which contained a minor number of at least
+ <tt>1.3</tt> was <var>1:1.1.3-1</var>, then the
+ <tt>shlibs</tt> entry for this library could say:
+ <example compact="compact">
+libz 1 zlib1g (>= 1:1.1.3)
+ </example>
+ The version-specific dependency is to avoid warnings from
+ the dynamic linker about using older shared libraries with
+ newer binaries.
+ </p>
+ </sect>
+
+ <sect>
+ <heading>Providing a <tt>shlibs</tt> file</heading>
+
+ <p>
+ If your package provides a shared library, you should create
+ a <tt>shlibs</tt> file following the format described above.
+ It is usual to call this file <tt>debian/shlibs</tt> (but if
+ you have multiple binary packages, you might want to call it
+ <tt>debian/shlibs.<var>package</var></tt> instead). Then
+ let <tt>debian/rules</tt> install it in the control area:
+ <example compact="compact">
+install -m644 debian/shlibs debian/tmp/DEBIAN
+ </example>
+ or, in the case of a multi-binary package:
+ <example compact="compact">
+install -m644 debian/shlibs.<var>package</var> debian/<var>package</var>/DEBIAN/shlibs
+ </example>
+ An alternative way of doing this is to create the
+ <tt>shlibs</tt> file in the control area directly from
+ <tt>debian/rules</tt> without using a <tt>debian/shlibs</tt>
+ file at all,<footnote>
+ <p>
+ This is what <prgn>dh_makeshlibs</prgn> in the
+ <tt>debhelper</tt> suite does.
+ </p>
+ </footnote>
+ since the <tt>debian/shlibs</tt> file itself is ignored by
+ <prgn>dpkg-shlibdeps</prgn>.
+ </p>
+
+ <p>
+ As <prgn>dpkg-shlibdeps</prgn> reads the
+ <tt>DEBIAN/shlibs</tt> files in all of the binary packages
+ being built from this source package, all of the
+ <tt>DEBIAN/shlibs</tt> files should be installed before
+ <prgn>dpkg-shlibdeps</prgn> is called on any of the binary
+ packages.
+ </p>
+ </sect>
+
+ <sect id="shlibslocal">
+ <heading>Writing the <tt>debian/shlibs.local</tt> file</heading>
+
+ <p>
+ This file is intended only as a <em>temporary</em> fix if
+ your binaries or libraries depend on a library whose package
+ does not yet provide a correct <tt>shlibs</tt> file.
+ </p>
+
+ <p>
+ We will assume that you are trying to package a binary
+ <tt>foo</tt>. When you try running
+ <prgn>dpkg-shlibdeps</prgn> you get the following error
+ message (<tt>-O</tt> displays the dependency information on
+ <tt>stdout</tt> instead of writing it to
+ <tt>debian/substvars</tt>, and the lines have been wrapped
+ for ease of reading):
+ <example compact="compact">
+$ dpkg-shlibdeps -O debian/tmp/usr/bin/foo
+dpkg-shlibdeps: warning: unable to find dependency
+ information for shared library libbar (soname 1,
+ path /usr/lib/libbar.so.1, dependency field Depends)
+shlibs:Depends=libc6 (>= 2.2.2-2)
+ </example>
+ You can then run <prgn>ldd</prgn> on the binary to find the
+ full location of the library concerned:
+ <example compact="compact">
+$ ldd foo
+libbar.so.1 => /usr/lib/libbar.so.1 (0x4001e000)
+libc.so.6 => /lib/libc.so.6 (0x40032000)
+/lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
+ </example>
+ So the <prgn>foo</prgn> binary depends on the
+ <prgn>libbar</prgn> shared library, but no package seems to
+ provide a <tt>*.shlibs</tt> file handling
+ <tt>libbar.so.1</tt> in <tt>/var/lib/dpkg/info/</tt>. Let's
+ determine the package responsible:
+ <example compact="compact">
+$ dpkg -S /usr/lib/libbar.so.1
+bar1: /usr/lib/libbar.so.1
+$ dpkg -s bar1 | grep Version
+Version: 1.0-1
+ </example>
+ This tells us that the <tt>bar1</tt> package, version 1.0-1,
+ is the one we are using. Now we can file a bug against the
+ <tt>bar1</tt> package and create our own
+ <tt>debian/shlibs.local</tt> to locally fix the problem.
+ Including the following line into your
+ <tt>debian/shlibs.local</tt> file:
+ <example compact="compact">
+libbar 1 bar1 (>= 1.0-1)
+ </example>
+ should allow the package build to work.
+ </p>
+
+ <p>
+ As soon as the maintainer of <tt>bar1</tt> provides a
+ correct <tt>shlibs</tt> file, you should remove this line
+ from your <tt>debian/shlibs.local</tt> file. (You should
+ probably also then have a versioned <tt>Build-Depends</tt>
+ on <tt>bar1</tt> to help ensure that others do not have the
+ same problem building your package.)
+ </p>
</sect>
</chapt>
-
- <chapt><heading>The Operating System</heading>
-
-
+
+ <chapt id="opersys"><heading>The Operating System</heading>
+
<sect>
- <heading>File system hierarchy</heading>
-
-
+ <heading>Filesystem hierarchy</heading>
+
+
<sect1>
- <heading>Linux File system Structure</heading>
-
+ <heading>Filesystem Structure</heading>
+
<p>
The location of all installed files and directories must
- comply with the Linux File system Hierarchy Standard
- (FHS). The latest version of this document can be found
- alongside this manual or on
- <url id="http://www.pathname.com/fhs/">.
+ 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
+ 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 <prgn>debian-devel</prgn>, or referred to Daniel
- Quinlan, the FHS coordinator, at
- <email>quinlan@pathname.com</email>.</p></sect1>
-
-
+ asked on the <tt>debian-devel</tt> mailing list, or
+ referred to the FHS mailing list (see the
+ <url id="http://www.pathname.com/fhs/" name="FHS web site"> for
+ more information).
+ </p>
+ </sect1>
+
<sect1>
<heading>Site-specific programs</heading>
-
+
<p>
As mandated by the FHS, packages must not place any
files in <tt>/usr/local</tt>, either by putting them in
the file system archive to be unpacked by <prgn>dpkg</prgn>
- or by manipulating them in their maintainer scripts.</p>
-
+ or by manipulating them in their maintainer scripts.
+ </p>
+
<p>
However, the package may create empty directories below
<tt>/usr/local</tt> so that the system administrator knows
- where to place site-specific files. These directories
+ where to place site-specific files. These directories
should be removed on package removal if they are
- empty.</p>
-
+ empty.
+ </p>
+
<p>
Note, that this applies only to directories <em>below</em>
- <tt>/usr/local</tt>, not <em>in</em>
- <tt>/usr/local</tt>. Packages must not create sub-directories
- in the directory <tt>/usr/local</tt> itself, except those listed in
- FHS, section 4.5. However, you may create directories
- below them as you wish. You must not remove any of the
- directories listed in 4.5, even if you created them.</p>
-
+ <tt>/usr/local</tt>, not <em>in</em> <tt>/usr/local</tt>.
+ Packages must not create sub-directories in the directory
+ <tt>/usr/local</tt> itself, except those listed in FHS,
+ section 4.5. However, you may create directories below
+ them as you wish. You must not remove any of the
+ directories listed in 4.5, even if you created them.
+ </p>
+
<p>
Since <tt>/usr/local</tt> can be mounted read-only from a
remote server, these directories must be created and
- removed by the <tt>postinst</tt> and <tt>prerm</tt>
- maintainer scripts. These scripts must not fail if either
- of these operations fail. (In the future, it will be
- possible to tell <prgn>dpkg</prgn> not to unpack files
- matching certain patterns, so that the directories can be
- included in the <tt>.deb</tt> packages and system
- administrators who do not wish these directories in
- /usr/local do not need to have them.)</p>
-
+ removed by the <prgn>postinst</prgn> and <prgn>prerm</prgn>
+ maintainer scripts and not be included in the
+ <tt>.deb</tt> archive. These scripts must not fail if
+ either of these operations fail.
+ </p>
+
<p>
- For example, the <prgn>emacs</prgn> package will contain
- <example>
- mkdir -p /usr/local/lib/emacs/site-lisp || true
+ For example, the <tt>emacsen-common</tt> package could
+ contain something like
+ <example compact="compact">
+if [ ! -e /usr/local/share/emacs ]
+then
+ if mkdir /usr/local/share/emacs 2>/dev/null
+ then
+ chown root:staff /usr/local/share/emacs
+ chmod 2775 /usr/local/share/emacs
+ fi
+fi
</example>
- in the <tt>postinst</tt> script, and
- <example>
- rmdir /usr/local/lib/emacs/site-lisp || true
- rmdir /usr/local/lib/emacs || true
+ in its <prgn>postinst</prgn> script, and
+ <example compact="compact">
+rmdir /usr/local/share/emacs/site-lisp 2>/dev/null || true
+rmdir /usr/local/share/emacs 2>/dev/null || true
</example>
- in the <tt>prerm</tt> script.</p>
-
+ in the <prgn>prerm</prgn> script. (Note that this form is
+ used to ensure that if the script is interrupted, the
+ directory <tt>/usr/local/share/emacs</tt> will still be
+ removed.)
+ </p>
+
<p>
If you do create a directory in <tt>/usr/local</tt> for
local additions to a package, you should ensure that
settings in <tt>/usr/local</tt> take precedence over the
- equivalents in <tt>/usr</tt>.</p>
+ equivalents in <tt>/usr</tt>.
+ </p>
<p>
- However, because '/usr/local' and its contents are for
- exclusive use of the local administrator, a package must
- not rely on the presence or absence of files or
- directories in '/usr/local' for normal operation.</p>
-
+ However, because <tt>/usr/local</tt> and its contents are
+ for exclusive use of the local administrator, a package
+ must not rely on the presence or absence of files or
+ directories in <tt>/usr/local</tt> for normal operation.
+ </p>
+
<p>
The <tt>/usr/local</tt> directory itself and all the
subdirectories created by the package should (by default) have
permissions 2775 (group-writable and set-group-id) and be
- owned by <tt>root.staff</tt>.</p>
+ owned by <tt>root.staff</tt>.
+ </p>
+ </sect1>
+
+ <sect1>
+ <heading>The system-wide mail directory</heading>
+ <p>
+ The system-wide mail directory is <tt>/var/mail</tt>. This
+ directory is part of the base system and should not owned
+ by any particular mail agents. The use of the old
+ location <tt>/var/spool/mail</tt> is deprecated, even
+ though the spool may still be physically located there.
+ To maintain partial upgrade compatibility for systems
+ which have <tt>/var/spool/mail</tt> as their physical mail
+ spool, packages using <tt>/var/mail</tt> must depend on
+ either <package>libc6</package> (>= 2.1.3-13), or on
+ <package>base-files</package> (>= 2.2.0), or on later
+ versions of either one of these packages.
+ </p>
</sect1>
</sect>
-
+
<sect>
<heading>Users and groups</heading>
-
- <p>
- The Debian system can be configured to use either plain or
- shadow passwords.</p>
-
- <p>
- Some user ids (UIDs) and group ids (GIDs) are reserved
- globally for use by certain packages. Because some packages
- need to include files which are owned by these users or
- groups, or need the ids compiled into binaries, these ids
- must be used on any Debian system only for the purpose for
- which they are allocated. This is a serious restriction, and
- we should avoid getting in the way of local administration
- policies. In particular, many sites allocate users and/or
- local system groups starting at 100.</p>
-
- <p>
- Apart from this we should have dynamically allocated ids,
- which should by default be arranged in some sensible
- order--but the behavior should be configurable.</p>
-
- <p>
- Packages other than <tt>base-passwd</tt> must not modify
- <tt>/etc/passwd</tt>, <tt>/etc/shadow</tt>,
- <tt>/etc/group</tt> or <tt>/etc/gshadow</tt>.</p>
-
- <p>
- The UID and GID ranges are as follows:
- <taglist>
- <tag>0-99:</tag>
- <item>
- <p>
- Globally allocated by the Debian project, the
- same on every Debian system. These ids will appear in
- the <tt>passwd</tt> and <tt>group</tt> files of all
- Debian systems, new ids in this range being added
- automatically as the <tt>base-passwd</tt> package is
- updated.</p>
-
- <p>
- Packages which need a single statically allocated uid
- or gid should use one of these; their maintainers
- should ask the <tt>base-passwd</tt> maintainer for
- ids.</p>
- </item>
-
- <tag>100-999:</tag>
- <item>
- <p>
- Dynamically allocated system users and groups.
- Packages which need a user or group, but can have this
- user or group allocated dynamically and differently on
- each system, should use `<tt>adduser --system</tt>' to
- create the group and/or user. <prgn>adduser</prgn>
- will check for the existence of the user or group, and
- if necessary choose an unused id based on the ranges
- specified in <tt>adduser.conf</tt>.</p></item>
-
-
- <tag>1000-29999:</tag>
- <item>
- <p>
- Dynamically allocated user accounts. By default
- <prgn>adduser</prgn> will choose UIDs and GIDs for
- user accounts in this range, though
- <tt>adduser.conf</tt> may be used to modify this
- behavior.</p>
- </item>
-
- <tag>30000-59999:</tag>
- <item>
- <p>Reserved.</p></item>
-
-
- <tag>60000-64999:</tag>
- <item>
- <p>
- Globally allocated by the Debian project, but only
- created on demand. The ids are allocated centrally and
- statically, but the actual accounts are only created
- on users' systems on demand.</p>
-
- <p>
- These ids are for packages which are obscure or which
- require many statically-allocated ids. These packages
- should check for and create the accounts in
- <tt>/etc/passwd</tt> or <tt>/etc/group</tt> (using
- <prgn>adduser</prgn> if it has this facility) if
- necessary. Packages which are likely to require
- further allocations should have a `hole' left after
- them in the allocation, to give them room to
- grow.</p></item>
-
-
- <tag>65000-65533:</tag>
- <item>
- <p>Reserved.</p></item>
-
-
- <tag>65534:</tag>
- <item>
- <p>User `<tt>nobody</tt>.' The corresponding gid refers
- to the group `<tt>nogroup</tt>.'</p></item>
-
-
- <tag>65535:</tag>
- <item>
- <p>
- <tt>(uid_t)(-1) == (gid_t)(-1)</tt>. NOT TO BE USED,
- because it is the error return sentinel value.</p>
- </item>
- </taglist>
- </p>
+
+ <sect1>
+ <heading>Introduction</heading>
+ <p>
+ The Debian system can be configured to use either plain or
+ shadow passwords.
+ </p>
+
+ <p>
+ Some user ids (UIDs) and group ids (GIDs) are reserved
+ globally for use by certain packages. Because some
+ packages need to include files which are owned by these
+ users or groups, or need the ids compiled into binaries,
+ these ids must be used on any Debian system only for the
+ purpose for which they are allocated. This is a serious
+ restriction, and we should avoid getting in the way of
+ local administration policies. In particular, many sites
+ allocate users and/or local system groups starting at 100.
+ </p>
+
+ <p>
+ Apart from this we should have dynamically allocated ids,
+ which should by default be arranged in some sensible
+ order, but the behavior should be configurable.
+ </p>
+
+ <p>
+ Packages other than <tt>base-passwd</tt> must not modify
+ <tt>/etc/passwd</tt>, <tt>/etc/shadow</tt>,
+ <tt>/etc/group</tt> or <tt>/etc/gshadow</tt>.
+ </p>
+ </sect1>
+
+ <sect1>
+ <heading>UID and GID classes</heading>
+ <p>
+ The UID and GID numbers are divided into classes as
+ follows:
+ <taglist>
+ <tag>0-99:</tag>
+ <item>
+ <p>
+ Globally allocated by the Debian project, the same
+ on every Debian system. These ids will appear in
+ the <tt>passwd</tt> and <tt>group</tt> files of all
+ Debian systems, new ids in this range being added
+ automatically as the <tt>base-passwd</tt> package is
+ updated.
+ </p>
+
+ <p>
+ Packages which need a single statically allocated
+ uid or gid should use one of these; their
+ maintainers should ask the <tt>base-passwd</tt>
+ maintainer for ids.
+ </p>
+ </item>
+
+ <tag>100-999:</tag>
+ <item>
+ <p>
+ Dynamically allocated system users and groups.
+ Packages which need a user or group, but can have
+ this user or group allocated dynamically and
+ differently on each system, should use <tt>adduser
+ --system</tt> to create the group and/or user.
+ <prgn>adduser</prgn> will check for the existence of
+ the user or group, and if necessary choose an unused
+ id based on the ranges specified in
+ <tt>adduser.conf</tt>.
+ </p>
+ </item>
+
+ <tag>1000-29999:</tag>
+ <item>
+ <p>
+ Dynamically allocated user accounts. By default
+ <prgn>adduser</prgn> will choose UIDs and GIDs for
+ user accounts in this range, though
+ <tt>adduser.conf</tt> may be used to modify this
+ behavior.
+ </p>
+ </item>
+
+ <tag>30000-59999:</tag>
+ <item>
+ <p>Reserved.</p>
+ </item>
+
+ <tag>60000-64999:</tag>
+ <item>
+ <p>
+ Globally allocated by the Debian project, but only
+ created on demand. The ids are allocated centrally
+ and statically, but the actual accounts are only
+ created on users' systems on demand.
+ </p>
+
+ <p>
+ These ids are for packages which are obscure or
+ which require many statically-allocated ids. These
+ packages should check for and create the accounts in
+ <tt>/etc/passwd</tt> or <tt>/etc/group</tt> (using
+ <prgn>adduser</prgn> if it has this facility) if
+ necessary. Packages which are likely to require
+ further allocations should have a `hole' left after
+ them in the allocation, to give them room to
+ grow.
+ </p>
+ </item>
+
+ <tag>65000-65533:</tag>
+ <item>
+ <p>Reserved.</p>
+ </item>
+
+ <tag>65534:</tag>
+ <item>
+ <p>
+ User <tt>nobody</tt>. The corresponding gid refers
+ to the group <tt>nogroup</tt>.
+ </p>
+ </item>
+
+ <tag>65535:</tag>
+ <item>
+ <p>
+ <tt>(uid_t)(-1) == (gid_t)(-1)</tt> <em>must
+ not</em> be used, because it is the error return
+ sentinel value.
+ </p>
+ </item>
+ </taglist>
+ </p>
+ </sect1>
</sect>
+
<sect id="sysvinit">
- <heading>System run levels</heading>
-
-
+ <heading>System run levels and <tt>init.d</tt> scripts</heading>
+
<sect1 id="/etc/init.d">
<heading>Introduction</heading>
-
+
<p>
The <tt>/etc/init.d</tt> directory contains the scripts
- executed by <prgn>init</prgn> at boot time and when init
- state (or `runlevel') is changed (see <manref name="init"
- section="8">).</p>
+ executed by <prgn>init</prgn> at boot time and when the
+ init state (or `runlevel') is changed (see <manref
+ name="init" section="8">).
+ </p>
<p>
There are at least two different, yet functionally
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
- maintainer scripts must be performed using `update-rc.d'
- as described below and not by manually installing or
- removing symlinks. For information on the
- implementation details of the other method, implemented in
- the <tt>file-rc</tt> package, please refer to the
- documentation of that package.</p>
+ maintainer scripts must be performed using
+ <prgn>update-rc.d</prgn> as described below and not by
+ manually installing or removing symlinks. For information
+ on the implementation details of the other method,
+ implemented in the <tt>file-rc</tt> package, please refer
+ to the documentation of that package.
+ </p>
<p>
- These scripts are referenced by symbolic links in
- the <tt>/etc/rc<var>n</var>.d</tt> directories. When
- changing runlevels, <prgn>init</prgn> looks in the
- directory <tt>/etc/rc<var>n</var>.d</tt> for the scripts
- it should execute, where <var>n</var> is the runlevel that
- is being changed to, or `S' for the boot-up scripts.</p>
-
+ These scripts are referenced by symbolic links in the
+ <tt>/etc/rc<var>n</var>.d</tt> directories. When changing
+ runlevels, <prgn>init</prgn> looks in the directory
+ <tt>/etc/rc<var>n</var>.d</tt> for the scripts it should
+ execute, where <tt><var>n</var></tt> is the runlevel that
+ is being changed to, or <tt>S</tt> for the boot-up
+ scripts.
+ </p>
+
<p>
The names of the links all have the form
<tt>S<var>mm</var><var>script</var></tt> or
<tt>K<var>mm</var><var>script</var></tt> where
<var>mm</var> is a two-digit number and <var>script</var>
is the name of the script (this should be the same as the
- name of the actual script in <tt>/etc/init.d</tt>.</p>
-
+ name of the actual script in <tt>/etc/init.d</tt>).
+ </p>
+
<p>
When <prgn>init</prgn> changes runlevel first the targets
- of the links whose names starting with a <tt>K</tt> are
+ of the links whose names start with a <tt>K</tt> are
executed, each with the single argument <tt>stop</tt>,
followed by the scripts prefixed with an <tt>S</tt>, each
- with the single argument <tt>start</tt>. The <tt>K</tt>
- links are responsible for killing services and the
- <tt>S</tt> link for starting services upon entering the
- runlevel.</p>
-
+ with the single argument <tt>start</tt>. (The links are
+ those in the <tt>/etc/rc<var>n</var>.d</tt> directory
+ corresponding to the new runlevel.) The <tt>K</tt> links
+ are responsible for killing services and the <tt>S</tt>
+ link for starting services upon entering the runlevel.
+ </p>
+
<p>
For example, if we are changing from runlevel 2 to
runlevel 3, init will first execute all of the <tt>K</tt>
prefixed scripts it finds in <tt>/etc/rc3.d</tt>, and then
- all of the <tt>S</tt> prefixed scripts. The links
- starting with <tt>K</tt> will cause the referred-to file
- to be executed with an argument of <tt>stop</tt>, and the
- <tt>S</tt> links with an argument of <tt>start</tt>.</p>
-
+ all of the <tt>S</tt> prefixed scripts in that directory.
+ The links starting with <tt>K</tt> will cause the
+ referred-to file to be executed with an argument of
+ <tt>stop</tt>, and the <tt>S</tt> links with an argument
+ of <tt>start</tt>.
+ </p>
+
<p>
- The two-digit number <var>mm</var> is used to decide which
- order to start and stop things in--low-numbered links have
- their scripts run first. For example, the <tt>K20</tt>
- scripts will be executed before the <tt>K30</tt> scripts.
- This is used when a certain service must be started before
- another. For example, the name server <prgn>bind</prgn>
- might need to be started before the news server
- <prgn>inn</prgn> so that <prgn>inn</prgn> can set up its
- access lists. In this case, the script that starts
- <prgn>bind</prgn> would have a lower number than the
- script that starts <prgn>inn</prgn> so that it runs first:
- <example>
- /etc/rc2.d/S17bind
- /etc/rc2.d/S70inn
+ The two-digit number <var>mm</var> is used to determine
+ the order in which to run the scripts: low-numbered links
+ have their scripts run first. For example, the
+ <tt>K20</tt> scripts will be executed before the
+ <tt>K30</tt> scripts. This is used when a certain service
+ must be started before another. For example, the name
+ server <prgn>bind</prgn> might need to be started before
+ the news server <prgn>inn</prgn> so that <prgn>inn</prgn>
+ can set up its access lists. In this case, the script
+ that starts <prgn>bind</prgn> would have a lower number
+ than the script that starts <prgn>inn</prgn> so that it
+ runs first:
+ <example compact="compact">
+/etc/rc2.d/S17bind
+/etc/rc2.d/S70inn
</example>
</p>
+
+ <p>
+ The two runlevels 0 (halt) and 6 (reboot) are slightly
+ different. In these runlevels, the links with an
+ <tt>S</tt> prefix are still called after those with a
+ <tt>K</tt> prefix, but they too are called with the single
+ argument <tt>stop</tt>.
+ </p>
+
+ <p>
+ Also, if the script name ends <tt>.sh</tt>, the script
+ will be sourced in runlevel <tt>S</tt> rather that being
+ run in a forked subprocess, but will be explicitly run by
+ <prgn>sh</prgn> in all other runlevels.
+ </p>
</sect1>
-
+
<sect1>
<heading>Writing the scripts</heading>
-
+
<p>
Packages that include daemons for system services should
place scripts in <tt>/etc/init.d</tt> to start or stop
These scripts should be named
<tt>/etc/init.d/<var>package</var></tt>, and they should
accept one argument, saying what to do:
-
+
<taglist>
<tag><tt>start</tt></tag>
<item><p>start the service,</p></item>
-
+
<tag><tt>stop</tt></tag>
<item><p>stop the service,</p></item>
-
+
<tag><tt>restart</tt></tag>
<item><p>stop and restart the service,</p></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>
-
- <tag><tt>force-reload</tt></tag> <item><p>cause the
- configuration to be reloaded if the service supports
- this, otherwise restart the service.</p></item>
+
+ <tag><tt>force-reload</tt></tag>
+ <item><p>cause the configuration to be reloaded if the
+ service supports this, otherwise restart the
+ service.</p></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 <tt>/etc/init.d</tt>, the <tt>reload</tt>
option is optional.</p>
-
+
<p>
The <tt>init.d</tt> scripts should ensure that they will
behave sensibly if invoked with <tt>start</tt> when the
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>
-
+
<p>
If a service reloads its configuration automatically (as
in the case of <prgn>cron</prgn>, for example), the
<tt>reload</tt> option of the <tt>init.d</tt> script
should behave as if the configuration has been reloaded
successfully.</p>
-
+
+ <p>
+ The <tt>/etc/init.d</tt> scripts must be treated as
+ configuration files, either (if they are present in the
+ package, that is, in the .deb file) by marking them as
+ <tt>conffile</tt>s, or, (if they do not exist in the .deb)
+ by managing them correctly in the maintainer scripts (see
+ <ref id="config files">). This is important since we want
+ to give the local system administrator the chance to adapt
+ the scripts to the local system, e.g., to disable a
+ service without de-installing the package, or to specify
+ some special command line options when starting a service,
+ while making sure her changes aren't lost during the next
+ package upgrade.
+ </p>
+
<p>
These scripts should not fail obscurely when the
configuration files remain but the package has been
removed, as configuration files remain on the system after
- the package has been removed. Only when <prgn>dpkg</prgn>
+ the package has been removed.
Only when <prgn>dpkg</prgn>
is executed with the <tt>--purge</tt> option will
- configuration files be removed. In particular, the init
- script itself is usually a configuration file (see
- <ref id="init.d notes">), and will remain on the system if
- the package is removed but not purged. Therefore, you
+ configuration files be removed. In particular, as the
+ <tt>/etc/init.d/<var>package</var></tt> script itself is
+ usually a <tt>conffile</tt>, it will remain on the system
+ if the package is removed but not purged. Therefore, you
should include a <tt>test</tt> statement at the top of the
script, like this:
- <example>
- test -f <var>program-executed-later-in-script</var> || exit 0
- </example></p>
+ <example compact="compact">
+test -f <var>program-executed-later-in-script</var> || exit 0
+ </example>
+ </p>
<p>
- Often there are some values in the `<tt>init.d</tt>'
- scripts that a system administrator will frequently want
- to change. While the scripts are frequently conffiles,
- modifying them requires that the administrator merge in
- their changes each time the package is upgraded and the
- conffile changes. To ease the burden on the system
- administrator, such configurable values should not be
- placed directly in the script. Instead, they should be
- placed in a file in `<tt>/etc/default</tt>', which
- typically will have the same base name as the
- `<tt>init.d</tt>' script. This extra file can be sourced
- by the script when the script runs. It must contain only
- variable settings and comments.
+ Often there are some variables in the <tt>init.d</tt>
+ scripts whose values control the bahaviour of the scripts,
+ and which a system administrator is likely to want to
+ change. As the scripts themselves are frequently
+ <tt>conffile</tt>s, modifying them requires that the
+ administrator merge in their changes each time the package
+ is upgraded and the <tt>conffile</tt> changes. To ease
+ the burden on the system administrator, such configurable
+ values should not be placed directly in the script.
+ Instead, they should be placed in a file in
+ <tt>/etc/default</tt>, which typically will have the same
+ base name as the <tt>init.d</tt> script. This extra file
+ should be sourced by the script when the script runs. It
+ must contain only variable settings and comments in POSIX
+ <prgn>sh</prgn> format. It may either be a
+ <tt>conffile</tt> or a configuration file maintained by
+ the package maintainer scripts. See <ref id="config files">
+ for more details.
</p>
<p>
To ensure that vital configurable values are always
- available, the `<tt>init.d</tt>' script should set default
- values for each of the shell variables it uses before
- sourcing the <tt>/etc/default/</tt> file. Also, since the
- `<tt>/etc/default/</tt>' file is often a conffile, the
- `<tt>init.d</tt>' script must behave sensibly without
- failing if it is deleted.
+ available, the <tt>init.d</tt> script should set default
+ values for each of the shell variables it uses, either
+ before sourcing the <tt>/etc/default/</tt> file or
+ afterwards using something like the <tt>:
+ ${VAR:=default}</tt> syntax. Also, the <tt>init.d</tt>
+ script must behave sensibly and not fail if the
+ <tt>/etc/default</tt> file is deleted.
</p>
-
</sect1>
-
+
<sect1>
<heading>Managing the links</heading>
-
+
<p>
- The program <prgn>update-rc.d</prgn> is provided to make
- it easier for package maintainers to arrange for the
- proper creation and removal of
- <tt>/etc/rc<var>n</var>.d</tt> symbolic links, or their
- functional equivalent if another method is being used.
- This may be used by maintainers in their packages'
- <tt>postinst</tt> and <tt>postrm</tt> scripts.</p>
-
+ The program <prgn>update-rc.d</prgn> is provided for
+ package maintainers to arrange for the proper creation and
+ removal of <tt>/etc/rc<var>n</var>.d</tt> symbolic links,
+ or their functional equivalent if another method is being
+ used. This may be used by maintainers in their packages'
+ <prgn>postinst</prgn> and <prgn>postrm</prgn> scripts.</p>
+
<p>
- You must use this script to make changes to
- <tt>/etc/rc<var>n</var>.d</tt> and <em>never</em> either
- include any <tt>/etc/rc<var>n</var>.d</tt> symbolic links
- in the actual archive or manually create or remove the
- symbolic links in maintainer scripts. (The latter will
- fail if an alternative method of maintaining runlevel
- information is being used.)</p>
-
+ You must not include any <tt>/etc/rc<var>n</var>.d</tt>
+ symbolic links in the actual archive or manually create or
+ remove the symbolic links in maintainer scripts; you must
+ use the <prgn>update-rc.d</prgn> program instead. (The
+ former will fail if an alternative method of maintaining
+ runlevel information is being used.) You must not include
+ the <tt>/etc/rc<var>n</var>.d</tt> directories themselves
+ in the archive either. (Only the <tt>sysvinit</tt>
+ package may do so.)
+ </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 either running <prgn>update-rc.d</prgn>, by
- simply adding, moving, or removing the symbolic links in
- <tt>/etc/rc<var>n</var>.d</tt> if symbolic links are being
- used, or by modifying <tt>/etc/runlevel.conf</tt> if the
- <tt>file-rc</tt> method is being used.</p>
-
+ runlevels by simply adding, moving, or removing the
+ symbolic links in <tt>/etc/rc<var>n</var>.d</tt> if
+ symbolic links are being used, or by modifying
+ <tt>/etc/runlevel.conf</tt> if the <tt>file-rc</tt> method
+ is being used.
+ </p>
+
<p>
To get the default behavior for your package, put in your
- <tt>postinst</tt> script
- <example>
- update-rc.d <var>package</var> defaults >/dev/null
+ <prgn>postinst</prgn> script
+ <example compact="compact">
+update-rc.d <var>package</var> defaults >/dev/null
</example>
- and in your <tt>postrm</tt>
- <example>
- if [ purge = "$1" ]; then
- update-rc.d <var>package</var> remove >/dev/null
- fi
+ and in your <prgn>postrm</prgn>
+ <example compact="compact">
+if [ "$1" = purge ]; then
+ update-rc.d <var>package</var> remove >/dev/null
+fi
</example></p>
-
+
<p>
This will use a default sequence number of 20. If it does
- not matter when or in which order the 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>
-
+ not matter when or in which order the <tt>init.d</tt>
+ script is run, use this default. If it does, then you
+ should talk to the maintainer of the <prgn>sysvinit</prgn>
+ package or post to <tt>debian-devel</tt>, and they will
+ help you choose a number.
+ </p>
+
<p>
For more information about using <tt>update-rc.d</tt>,
please consult its manpage <manref name="update-rc.d"
- section="8">.</p></sect1>
-
-
+ section="8">.
+ </p>
+ </sect1>
+
+
<sect1>
<heading>Boot-time initialization</heading>
-
+
<p>
There used to be another directory, <tt>/etc/rc.boot</tt>,
which contained scripts which were run once per machine
described in <ref id="/etc/init.d">. Packages must not
place files in <tt>/etc/rc.boot</tt>.</p>
- <sect1 id="init.d notes">
- <heading>Notes</heading>
-
- <p>
- <em>Do not</em> include the
- <tt>/etc/rc<var>n</var>.d/*</tt> symbolic links in the
- <tt>.deb</tt> file system archive! <em>This will cause
- problems!</em> You must create them with
- <prgn>update-rc.d</prgn>, as above.</p>
-
- <p>
- <em>Do not</em> include the
- <tt>/etc/rc<var>n</var>.d/*</tt> symbolic links in
- <prgn>dpkg</prgn>'s conffiles list! <em>This will cause
- problems!</em> You should, however, treat the
- <tt>/etc/init.d</tt> scripts as configuration files,
- either by marking them as conffiles or managing them
- correctly in the maintainer scripts (see
- <ref id="config files">). (This is important since we want
- to give the local system administrator the chance to adapt
- the scripts to the local system--e.g., to disable a
- service without de-installing the package, or to specify
- some special command line options when starting a
- service--while making sure her changes aren't lost during
- the next package upgrade.)</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
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 user can say
+ configuration); this way the system administrator can say
<tt>/etc/init.d/bind reload</tt> to reload the name
server. The script has one configurable value, which can
be used to pass parameters to the named program at
- startup.
+ startup; this value is read from
+ <tt>/etc/default/bind</tt> (see below).
</p>
-
- <p>
- <example>
- #!/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
+ <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 file
- '<tt>/etc/default/bind</tt>', which contains configurable
- parameters used by the script.
- </p>
- <p>
- <example>
- # Specified parameters to pass to named. See named(8).
- # You may uncomment the following line, and edit to taste.
- #PARAMS="-u nobody"
+ Complementing the above init script is a configuration
+ file <tt>/etc/default/bind</tt>, 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 to base your <tt>/etc/init.d</tt>
- scripts is in <tt>/etc/init.d/skeleton</tt>.</p>
-
+ Another example on which you can base your
+ <tt>/etc/init.d</tt> scripts is found in
+ <tt>/etc/init.d/skeleton</tt>.
+ </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 <tt>postinst</tt>:
- <example>
- update-rc.d bind defaults >/dev/null
+ its <prgn>postinst</prgn>:
+ <example compact="compact">
+update-rc.d bind defaults >/dev/null
</example>
- And in its <tt>postrm</tt>, to remove the links when the
- package is purged:
- <example>
- if [ purge = "$1" ]; then
- update-rc.d bind remove >/dev/null
- fi
- </example></p>
- </sect1></sect>
-
- <sect>
- <heading>Cron jobs</heading>
-
- <p>
- Packages must not modify the configuration file
- <tt>/etc/crontab</tt>, and they must not modify the files in
- <tt>/var/spool/cron/crontabs</tt>.</p>
-
- <p>
- If a package wants to install a job that has to be executed
- via cron, it should place a file with the name if the
- package in one of the following directories:
- <example>
- /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,
- respectively. The exact times are listed in
- <tt>/etc/crontab</tt>.</p>
-
- <p>
- All files installed in any of these directories must be
- scripts (shell scripts, Perl scripts, etc.) so that they can
- easily be modified by the local system administrator. In
- addition, they should 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
- <tt>/etc/cron.d/<var>package-name</var></tt>. This file uses
- the same syntax as <tt>/etc/crontab</tt> and is processed by
- <prgn>cron</prgn> automatically. The file must also be
- treated as a configuration file. (Note, that entries in the
- <tt>/etc/cron.d</tt> directory are not handled by
- <prgn>anacron</prgn>. Thus, you should only use this
- directory for jobs which may be skipped if the system is not
- running.)</p>
-
- <p>
- The scripts or crontab entries in these directories should
- check if all necessary programs are installed before they
- try to execute them. Otherwise, problems will arise when a
- package was removed but not purged since configuration files
- are kept on the system in this situation.</p>
+ 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>
<sect>
- <heading>Console messages</heading>
-
+ <heading>Console messages from <tt>init.d</tt> scripts</heading>
+
<p>
- This section describes different formats for messages
+ This section describes the formats to be used for messages
written to standard output by the <tt>/etc/init.d</tt>
- scripts. The intent is to improve the consistency of
- Debian's startup and shutdown look and feel.</p>
-
- <p>
- Please look very careful at the details. We want to get the
- messages to look exactly the same way concerning spaces,
- punctuation, and case of letters.</p>
-
+ scripts. The intent is to improve the consistency of
+ Debian's startup and shutdown look and feel. For this
+ reason, please look very carefully at the details. We want
+ the messages to have the same format in terms of wording,
+ spaces, punctuation and case of letters.
+ </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 isn't covered in the sections
- below.</p>
-
+ create output messages. They can be useful if you have a
+ non-standard message that is not covered specifically in the
+ sections below.
+ </p>
+
<p>
<list>
<item>
<p>
- Every message should cover one line, start with a
- capital letter and end with a period `.'.</p></item>
-
-
- <item>
+ Every message should fit in one line (fewer than 80
+ characters), start with a capital letter and end with
+ a period (<tt>.</tt>) and line feed (<tt>"\n"</tt>).
+ </p>
+ </item>
+
+ <item>
<p>
If you want to express that the computer is working on
- something (performing a specific task, not starting or
- stopping a program), we use an ``ellipsis'', namely
- three dots `...'. Note that we don't insert spaces in
- front of or behind the dots. If the task has been
- completed we write `done.' and a line feed.</p></item>
-
-
+ something (that is, performing a specific task, not
+ starting or stopping a program), we use an "ellipsis"
+ (three dots: <tt>...</tt>). Note that we don't insert
+ spaces before or after the dots. If the task has been
+ completed we write <tt>done.</tt> and a line feed.
+ </p>
+ </item>
+
<item>
<p>
Design your messages as if the computer is telling you
- what he is doing (let him be polite :-) but don't
- mention ``him'' directly. For example, if you think
- of saying
- <example>
- I'm starting network daemons: nfsd mountd.
+ what he is doing (let him be polite :-), but don't
+ mention "him" directly. For example, if you think of
+ saying
+ <example compact="compact">
+I'm starting network daemons: nfsd mountd.
</example>
just say
- <example>
- Starting network daemons: nfsd mountd.
- </example></p></item>
- </list></p>
-
+ <example compact="compact">
+Starting network daemons: nfsd mountd.
+ </example>
+ </p>
+ </item>
+ </list>
+ </p>
+
<p>
- The following formats should be used</p>
-
+ There are standard message formats for the following
+ situations. They should be used by the <tt>init.d</tt>
+ scripts.
+ </p>
+
<p>
<list>
<item>
- <p>when daemons get started.</p>
-
+ <p>When daemons are started</p>
+
<p>
- Use this format if your script starts one or more
- daemons. The output should look like this (a single
- line, no leading spaces):
- <example>
- Starting <description>: <daemon-1> <daemon-2> <...> <daemon-n>.
+ If your script starts one or more daemons, the output
+ should look like this (a single line, no leading
+ spaces):
+ <example compact="compact">
+Starting <var>description</var>: <var>daemon-1</var> ... <var>daemon-n</var>.
</example>
- The <description> should describe the subsystem
- the daemon or set of daemons are part of, while
- <daemon-1> up to <daemon-n> denote each
- daemon's name (typically the file name of the
- program).</p>
-
+ The <var>description</var> should describe the
+ subsystem the daemon or set of daemons are part of,
+ while <var>daemon-1</var> up to <var>daemon-n</var>
+ denote each daemon's name (typically the file name of
+ the program).
+ </p>
+
<p>
- For example, the output of /etc/init.d/lpd would look like:
- <example>
- Starting printer spooler: lpd.
- </example></p>
-
+ For example, the output of <tt>/etc/init.d/lpd</tt>
+ would look like:
+ <example compact="compact">
+Starting printer spooler: lpd.
+ </example>
+ </p>
+
<p>
This can be achieved by saying
- <example>
- echo -n "Starting printer spooler: lpd"
- start-stop-daemon --start --quiet lpd
- echo "."
+ <example compact="compact">
+echo -n "Starting printer spooler: lpd"
+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:
- <example>
- echo -n "Starting remote file system services:"
- echo -n " nfsd"; start-stop-daemon --start --quiet nfsd
- echo -n " mountd"; start-stop-daemon --start --quiet mountd
- echo -n " ugidd"; start-stop-daemon --start --quiet ugidd
- echo "."
+ <example compact="compact">
+echo -n "Starting remote file system services:"
+echo -n " nfsd"; start-stop-daemon --start --quiet nfsd
+echo -n " mountd"; start-stop-daemon --start --quiet mountd
+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
+ 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
- looks good.</p></item>
-
-
+ looks good.
+ </p>
+ </item>
+
<item>
- <p>when something needs to be configured.</p>
-
+ <p>When a system parameter is being set</p>
+
<p>
- If you have to set up different parameters of the
- system upon boot up, you should use this format:
- <example>
- Setting <parameter> to `<value>'.
- </example></p>
-
+ If you have to set up different system parameters
+ during the system boot, you should use this format:
+ <example compact="compact">
+Setting <var>parameter</var> to `<var>value</var>'.
+ </example>
+ </p>
+
<p>
- You can use the following echo statement to get the quotes right:
- <example>
- echo "Setting DNS domainname to \`"value"'."
- </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'."
+ </example>
+ </p>
+
<p>
- Note that the left quotation mark (`) is different
- from the right (').</p></item>
-
+ Note that the left quotation mark (<tt>`</tt>) is
+ different from the right one (<tt>'</tt>).
+ </p>
+ </item>
+
<item>
- <p>when a daemon is stopped.</p>
-
+ <p>When a daemon is stopped or restarted</p>
+
<p>
- When you stop a daemon you should issue a message
- similar to the startup message, except that `Starting'
- is replaced with `Stopping'.</p>
-
+ When you stop or restart a daemon, you should issue a
+ message identical to the startup message, except that
+ <tt>Starting</tt> is replaced with <tt>Stopping</tt>
+ or <tt>Restarting</tt> respectively.
+ </p>
+
<p>
- So stopping the printer daemon will like like this:
- <example>
- Stopping printer spooler: lpd.
- </example></p></item>
-
+ For example, stopping the printer daemon will like
+ like this:
+ <example compact="compact">
+Stopping printer spooler: lpd.
+ </example>
+ </p>
+ </item>
+
<item>
- <p>when something is executed.</p>
-
+ <p>When something is executed</p>
+
<p>
There are several examples where you have to run a
program at system startup or shutdown to perform a
- specific task. For example, setting the system's clock
- via `netdate' or killing all processes when the system
- comes down. Your message should like this:
- <example>
- Doing something very useful...done.
+ specific task, for example, setting the system's clock
+ using <prgn>netdate</prgn> or killing all processes
+ when the system shuts down. Your message should look
+ like this:
+ <example compact="compact">
+Doing something very useful...done.
</example>
- You should print the `done.' right after the job has been completed,
- so that the user gets informed why he has to wait. You can get this
+ 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
behavior by saying
- <example>
- echo -n "Doing something very useful..."
- do_something
- echo "done."
+ <example compact="compact">
+echo -n "Doing something very useful..."
+do_something
+echo "done."
</example>
- in your script.</p></item>
-
+ in your script.
+ </p>
+ </item>
+
<item>
- <p>when the configuration is reloaded.</p>
-
+ <p>When the configuration is reloaded</p>
+
<p>
When a daemon is forced to reload its configuration
files you should use the following format:
- <example>
- Reloading <daemon's-name> configuration...done.
- </example></p></item>
-
- <item>
- <p>when none of the above rules apply.</p>
-
- <p>
- If you have to print a message that doesn't fit into
- the styles described above, you can use something
- appropriate, but please have a look at the overall
- rules listed above.</p></item>
- </list></p></sect>
-
-
+ <example compact="compact">
+Reloading <var>description</var> configuration...done.
+ </example>
+ where <var>description</var> is the same as in the
+ daemon starting message.
+ </p>
+ </item>
+ </list>
+ </p>
+ </sect>
+
+ <sect>
+ <heading>Cron jobs</heading>
+
+ <p>
+ Packages must not modify the configuration file
+ <tt>/etc/crontab</tt>, and they must not modify the files in
+ <tt>/var/spool/cron/crontabs</tt>.</p>
+
+ <p>
+ If a package wants to install a job that has to be executed
+ 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.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,
+ respectively. The exact times are listed in
+ <tt>/etc/crontab</tt>.</p>
+
+ <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.
+ </p>
+
+ <p>
+ If a certain job has to be executed more frequently than
+ daily, the package should install a file
+ <tt>/etc/cron.d/<var>package</var></tt>. This file uses the
+ same syntax as <tt>/etc/crontab</tt> and is processed by
+ <prgn>cron</prgn> automatically. The file must also be
+ treated as a configuration file. (Note that entries in the
+ <tt>/etc/cron.d</tt> directory are not handled by
+ <prgn>anacron</prgn>. Thus, you should only use this
+ directory for jobs which may be skipped if the system is not
+ running.)</p>
+
+ <p>
+ The scripts or crontab entries in these directories should
+ check if all necessary programs are installed before they
+ try to execute them. Otherwise, problems will arise when a
+ package was removed but not purged since configuration files
+ are kept on the system in this situation.</p>
+ </sect>
+
<sect>
<heading>Menus</heading>
<p>
- Menu entries should follow the current menu policy as
- defined in the file <ftpsite>ftp.debian.org</ftpsite> in
- <ftppath>/debian/doc/package-developer/menu-policy.text.gz</ftppath>
- or your local mirror. In addition, it is included in the
- <tt>debian-policy</tt> package.
+ 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> packages provides a unique
+ 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 as
- <prgn>pdmenu</prgn>).</p>
-
+ managers or text-based menu programs such as
+ <prgn>pdmenu</prgn>).
+ </p>
+
<p>
All packages that provide applications that need not be
passed any special command line arguments for normal
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>
-
+
<p>
- Please refer to the <em>Debian Menu System</em> document
- that comes with the <tt>menu</tt> package for information
- about how to register your applications and web
- documents.</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.
+ </p>
</sect>
-
-
+
<sect>
<heading>Multimedia handlers</heading>
-
+
<p>
Packages which provide the ability to view/show/play,
compose, edit or print MIME types should register themselves
- as such following the current MIME support policy as defined
- in the file found on <ftpsite>ftp.debian.org</ftpsite> in
- <ftppath>/debian/doc/package-developer/mime-policy.text.gz</ftppath>
- or your local mirror. In addition, it is included in the
- <tt>debian-policy</tt> package.
+ as such following the current MIME support policy found in
+ the <tt>mime-policy</tt> files in the <tt>debian-policy</tt>
+ package. It may also be found on the Debian FTP site
+ <ftpsite>ftp.debian.org</ftpsite> as the file
+ <ftppath>/debian/doc/package-developer/mime-policy.txt.gz</ftppath>,
+ or in the equivalent location on your local mirror.
</p>
<p>
- MIME (Multipurpose Internet Mail Extensions, RFC 1521) is a
- mechanism for encoding files and data streams and providing
- meta-information about them, in particular their type (e.g.
- audio or video) and format (e.g. PNG, HTML, MP3).
+ MIME (Multipurpose Internet Mail Extensions, RFCs 2045-2049)
+ is a mechanism for encoding files and data streams and
+ providing meta-information about them, in particular their
+ type (e.g. audio or video) and format (e.g. PNG, HTML,
+ MP3).
</p>
-
+
<p>
Registration of MIME type handlers allows programs like mail
user agents and web browsers to to invoke these handlers to
<sect>
<heading>Keyboard configuration</heading>
-
+
<p>
- To achieve a consistent keyboard configuration (i.e., all
- applications interpret a keyboard event the same way) all
+ To achieve a consistent keyboard configuration so that all
+ applications interpret a keyboard event the same way, all
programs in the Debian distribution must be configured to
- comply with the following guidelines.</p>
-
+ comply with the following guidelines.
+ </p>
+
<p>
- Here is a list that contains certain keys and their interpretation:
-
+ The following keys must have the specified interpretations:
+
<taglist>
<tag><tt><--</tt></tag>
<item><p>delete the character to the left of the cursor</p></item>
-
+
<tag><tt>Delete</tt></tag>
<item><p>delete the character to the right of the cursor</p></item>
-
+
<tag><tt>Control+H</tt></tag>
<item><p>emacs: the help prefix</p></item>
</taglist>
-
- The interpretation of any keyboard events should be independent
- of the terminal that's used, be it a virtual console, an X
- terminal emulator, an rlogin/telnet session, etc.</p>
-
+
+ The interpretation of any keyboard events should be
+ independent of the terminal that is used, be it a virtual
+ console, an X terminal emulator, an rlogin/telnet session,
+ etc.
+ </p>
+
<p>
The following list explains how the different programs
- should be set up to achieve this:</p>
-
+ should be set up to achieve this:
+ </p>
+
<p>
- <list compact="compact">
- <item><p>`<tt><--</tt>' generates KB_Backspace in
- X.</p></item>
-
- <item><p>`<tt>Delete</tt>' generates KB_Delete in X.</p></item>
-
+ <list>
+ <item><p><tt><--</tt> generates <tt>KB_Backspace</tt>
+ in X.</p></item>
+
+ <item><p><tt>Delete</tt> generates <tt>KB_Delete</tt> in
+ X.</p></item>
+
<item>
<p>
- X translations are set up to make KB_Backspace
- generate ASCII DEL, and to make KB_Delete generate
- <tt>ESC [ 3 ~</tt> (this is the vt220 escape code for
- the `delete character' key). This must be done by
- loading the resources using xrdb on all local X
- displays, not using the application defaults, so that
- the translation resources used correspond to the
- xmodmap settings.</p></item>
-
+ 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'
+ 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>
+
<item>
<p>
The Linux console is configured to make
- `<tt><--</tt>' generate DEL, and `Delete' generate
- <tt>ESC [ 3 ~</tt> (this is the case at the
- moment).</p></item>
-
- X applications are configured so that Backspace
- deletes left, and Delete deletes right. Motif
+ <tt><--</tt> generate DEL, and <tt>Delete</tt>
+ generate <tt>ESC [ 3 ~</tt>.</p></item>
+
+ <item>
+ X applications are configured so that <tt><</tt>
+ deletes left, and <tt>Delete</tt> deletes right. Motif
applications already work like this.</p></item>
-
- <item><p>stty erase <tt>^?</tt> .</p></item>
-
- <item><p>
- The `xterm' terminfo entry should have <tt>ESC [ 3
- ~</tt> for kdch1, just like TERM=linux and
- TERM=vt220.</p></item>
-
- <item><p>
- Emacs is programmed to map KB_Backspace or the `stty
- erase' character to delete-backward-char, and
- KB_Delete or kdch1 to delete-forward-char, and
- <tt>^H</tt> to help as always.</p></item>
-
- <item><p>
- Other applications use the `stty erase' character and
- kdch1 for the two delete keys, with ASCII DEL being
- `delete previous character' and kdch1 being `delete
- character under cursor'.</p></item>
- </list></p>
-
+
+ <item><p>Terminals should have <tt>stty erase ^?</tt> .</p></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>
+
+ <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>
+
+ <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>
+
+ </list>
+ </p>
+
<p>
- This will solve the problem except for:</p>
-
+ This will solve the problem except for the following
+ cases:
+ </p>
+
<p>
- <list compact="compact">
- <item><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 `stty erase' character
- takes precedence in Emacs, and has been set
- correctly). M-x help or F1 (if available) can be used
- instead.</p></item>
-
- <item><p>
- Some operating systems use <tt>^H</tt> for stty erase.
- However, modern telnet versions and all rlogin
- versions propagate stty settings, and almost all UNIX
- versions honour stty erase. Where the stty settings
- are not propagated correctly things can be made to
- work by using stty manually.</p></item>
-
- <item><p>
+ <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>
+
+ <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>
+
+ <item>
+ <p>
Some systems (including previous Debian versions) use
- xmodmap to arrange for both <tt><--</tt> and Delete
- to generate KB_Delete. We can change the behavior
- of their X clients via the same X resources that we
- use to do it for our own, or have our clients be
- configured via their resources when things are the
- other way around. On displays configured like this
- Delete will not work, but <tt><--</tt>
+ <prgn>xmodmap</prgn> to arrange for both
+ <tt><--</tt> and <tt>Delete</tt> to generate
+ <tt>KB_Delete</tt>. We can change the behavior of
+ their X clients using the same X resources that we use
+ to do it for our own clients, or configure our clients
+ 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>
-
- <item><p>
- Some operating systems have different kdch1 settings
- in their terminfo for xterm and others. On these
- systems the Delete key will not work correctly when
- you log in from a system conforming to our policy, but
+
+ <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>
</list>
</p>
</sect>
-
-
+
<sect>
<heading>Environment variables</heading>
-
+
<p>
A program must not depend on environment variables to get
- reasonable defaults. (That's because these environment
+ reasonable defaults. (That's because these environment
variables would have to be set in a system-wide
- configuration file like /etc/profile, which is not supported
- by all shells.)</p>
-
+ configuration file like <tt>/etc/profile</tt>, which is not
+ supported by all shells.)</p>
+
<p>
If a program usually depends on environment variables for its
configuration, the program should be changed to fall back to
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>
-
+
<p>
Here is an example of a wrapper script for this purpose:
-
- <example>
- #!/bin/sh
- BAR=${BAR:-/var/lib/fubar}
- export BAR
- exec /usr/lib/foo/foo "$@"
- </example></p>
-
+
+ <example compact="compact">
+#!/bin/sh
+BAR=${BAR:-/var/lib/fubar}
+export BAR
+exec /usr/lib/foo/foo "$@"
+ </example>
+ </p>
+
<p>
Furthermore, as <tt>/etc/profile</tt> is a configuration
file of the <prgn>base-files</prgn> package, other packages must not
file.</p>
</sect>
</chapt>
- <chapt>
+
+ <chapt id="files">
<heading>Files</heading>
-
-
+
<sect>
<heading>Binaries</heading>
-
+
<p>
Two different packages must not install programs with
- different functionality but with the same filenames. (The
+ different functionality but with the same filenames. (The
case of two programs having the same functionality but
- different implementations is handled via `alternatives.')
- If this case happens, one of the programs must be
- renamed. The maintainers should report this to the
- developers' mailing and try to find a consensus about
- which package will have to be renamed. If a consensus can
- not be reached, <em>both</em> programs must be
- renamed.</p>
-
+ 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
+ try to find a consensus about which program will have to be
+ renamed. If a consensus cannot be reached, <em>both</em>
+ programs must be renamed.
+ </p>
+
<p>
Generally the following compilation parameters should be used:
- <example>
- CC = gcc
- CFLAGS = -O2 -Wall # sane warning options vary between programs
- LDFLAGS = # none
- install -s # (or use strip on the files in debian/tmp)
+ <example compact="compact">
+CC = gcc
+CFLAGS = -O2 -Wall # sane warning options vary between programs
+LDFLAGS = # none
+install -s # (or use strip on the files in debian/tmp)
</example></p>
-
+
<p>
Note that by default all installed binaries should be stripped,
either by using the <tt>-s</tt> flag to
the binaries after they have been copied into
<tt>debian/tmp</tt> but before the tree is made into a
package.</p>
-
+
<p>
- The <tt>-N</tt> flag should not be used. On a.out systems
- it may have been useful for some very small binaries, but
- for ELF it has no good effect.</p>
-
+ The <tt>-N</tt> flag should not be used. On <tt>a.out</tt>
+ systems it may have been useful for some very small
+ binaries, but for ELF it has no good effect.</p>
+
<p>
Debugging symbols are useful for error diagnosis,
investigation of core dumps (which may be submitted by users
- in bug reports), or testing and developing the
- software. Therefore it is recommended to support building
- the package with debugging information through the following
- interface: If the environment variable
- <tt>DEB_BUILD_OPTIONS</tt> contains the string
- <tt>debug</tt>, compile the software with debugging
- information (usually this involves adding the <tt>-g</tt>
- flag to <tt>CFLAGS</tt>). This allows the generation of a
- build tree with debugging information. If the environment
- variable <tt>DEB_BUILD_OPTIONS</tt> contains the string
- <tt>nostrip</tt>, do not strip the files at installation
- time. This allows one to generate a package with debugging
- information included. The following makefile snippet is only
- an example of how one may test for either condition:
- <footnote>
+ 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: Building by default with -g causes more
- wasted CPU cycles since the information is stripped away
- anyway. The package can by default build without -g if
- it also provides a mechanism to easily be rebuilt with
- debugging information. This can be done by providing a
- "build-debug" make target, or allowing the user to
- specify "DEB_BUILD_OPTIONS=debug" in the environment while
- compiling that package.
- </p>
- <p>Now this has several added benefits:
- <list>
- <item>
- <p>
- It is actually easier to build debugging bins and
- libraries this way (no more editing debian/rules
- or similar) since it provides a documented way of
- getting this type of build.</p>
- </item>
- <item>
- <p>
- There will be much less wasted CPU time for the
- autobuilders since not having debugging
- information (and hence also not having to strip
- it) will increase the speed of compiles. This
- skips an entire pass of the compiler.
- </p>
- </item>
- </list>
+ Rationale: Using <tt>-g</tt> by default causes wasted
+ CPU cycles since the information is stripped away
+ anyway; this can have a significant impact on the
+ efficiency of the autobuilders. Having a standard way
+ to build a debugging variant also makes it easier to
+ build debugging bins and libraries since it provides a
+ documented way of getting this type of build; one does
+ not have to manually edit <tt>debian/rules</tt> or
+ <tt>Makefile</tt>s.
</p>
</footnote>
-
-
- <example>
- 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
-
- ifneq (,$(findstring debug,$(DEB_BUILD_OPTIONS)))
- CFLAGS += -g
- endif
- ifeq (,$(findstring nostrip,$(DEB_BUILD_OPTIONS)))
- INSTALL_PROGRAM += -s
- endif
+ 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
+
+ifneq (,$(findstring debug,$(DEB_BUILD_OPTIONS)))
+CFLAGS += -g
+endif
+ifeq (,$(findstring nostrip,$(DEB_BUILD_OPTIONS)))
+INSTALL_PROGRAM += -s
+endif
</example>
-
- Please note that the above example is merely informative,
- and is not a policy mandate. You may have to massage this
- example in order to make it work for your package.
-
</p>
<p>
here. Don't use flags for the sake of it; only use them
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
+ options are best: they are often inappropriate for our
environment.</p></sect>
-
-
+
+
<sect>
<heading>Libraries</heading>
-
+
<p>
- All libraries must have a shared version in the lib
- package and a static version in the lib-dev 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>
-
+ 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>
+
<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>
-
+
<p>
Note that all installed shared libraries should be
stripped with
- <example>
- strip --strip-unneeded <your-lib>
- </example>
- (The option `--strip-unneeded' makes <tt>strip</tt> remove
- only the symbols which aren't needed for relocation
- processing.) Shared libraries can function perfectly well
- when stripped, since the symbols for dynamic linking are
- in a separate part of the ELF object file.</p>
-
+ <example compact="compact">
+strip --strip-unneeded <var>your-lib</var>
+ </example>
+ (The option <tt>--strip-unneeded</tt> makes
+ <prgn>strip</prgn> remove only the symbols which aren't
+ needed for relocation processing.) Shared libraries can
+ 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>
+
<p>
Note that under some circumstances it may be useful to
install a shared library unstripped, for example when
building a separate package to support debugging.
</p>
-
- <p>
- An ever increasing number of packages are using libtool to
- do their linking. The latest GNU libtools (>= 1.3a) can take
- advantage of the metadata in the installed libtool archive
- files (`*.la'). The main advantage of libtool's .la files is
- that it allows libtool to store and subsequently access
- metadata with respect to the libraries it builds. libtool
- will search for those files, which contain a lot of useful
- information about a library (e.g. dependency libraries for
- static linking). Also, they're <em>essential</em> for
- programs using libltdl.
- </p>
- <p>
- Certainly libtool is fully capable of linking against shared
- libraries which don't have .la files, but being a mere shell
- script it can add considerably to the build time of a
- libtool using package if that shell-script has to derive all
- this information from first principles for each library every
- time it is linked. With the advent of libtool-1.4 (and to a
- lesser extent libtool-1.3), the .la files will also store
- information about inter-library dependencies which cannot
- necessarily be derived after the .la file is deleted.
+ <p>
+ Shared object files (often <tt>.so</tt> files) that are not
+ public libraries, that is, they are not meant to be linked
+ to by third party executables (binaries of other packages),
+ should be installed in subdirectories of the
+ <tt>/usr/lib</tt> directory. Such files are exempt from the
+ rules that govern ordinary shared libraries, except that
+ they must not be installed executable and should be
+ stripped.<footnote>
+ <p>
+ A common example are the so-called ``plug-ins'',
+ internal shared objects that are dynamically loaded by
+ programs using <manref name="dlopen" section="3">.
+ </p>
+ </footnote>
+ </p>
+
+ <p>
+ Packages containing shared libraries that may be linked to
+ by other packages' binaries, but which for some
+ <em>compelling</em> reason can not be installed in
+ <tt>/usr/lib</tt> directory, may install the shared library
+ files in subdirectories of the <tt>/usr/lib</tt> directory,
+ in which case they should arrange to add that directory in
+ <tt>/etc/ld.so.conf</tt> in the package's post-installation
+ script, and remove it in the package's post-removal script.
+ </p>
+
+ <p>
+ An ever increasing number of packages are using
+ <prgn>libtool</prgn> to do their linking. The latest GNU
+ libtools (>= 1.3a) can take advantage of the metadata in the
+ installed <prgn>libtool</prgn> archive files (<tt>*.la</tt>
+ files). The main advantage of <prgn>libtool</prgn>'s
+ <tt>.la</tt> files is that it allows <prgn>libtool</prgn> to
+ store and subsequently access metadata with respect to the
+ libraries it builds. <prgn>libtool</prgn> will search for
+ those files, which contain a lot of useful information about
+ 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
+ add considerably to the build time of a
+ <prgn>libtool</prgn>-using package if that shell script
+ has to derive all this information from first principles
+ for each library every time it is linked. With the
+ advent of <prgn>libtool</prgn> version 1.4 (and to a
+ lesser extent <prgn>libtool</prgn> version 1.3), the
+ <tt>.la</tt> files also store information about
+ inter-library dependencies which cannot necessarily be
+ derived after the <tt>.la</tt> file is deleted.
+ </p>
+ </footnote>
</p>
<p>
- Packages that use libtool to create shared libraries should
- include the <em>.la</em> files in the <em>-dev</em>
- packages, with the exception that if the package relies on
- libtool's <em>libltdl</em> library, in which case the .la
- files must go in the run-time library package. This is a
- good idea in general, and especially for static linking
- issues.
+ Packages that use <prgn>libtool</prgn> to create shared
+ libraries should include the <tt>.la</tt> files in the
+ <tt>-dev</tt> package, unless the package relies on
+ <tt>libtool</tt>'s <tt>libltdl</tt> library, in which case
+ the <tt>.la</tt> files must go in the run-time library
+ package.
</p>
-
+
<p>
You must make sure that you use only released versions of
shared libraries to build your packages; otherwise other
idea.
</p>
</sect>
-
-
+
<sect>
<heading>Shared libraries</heading>
-
+
<p>
Packages involving shared libraries should be split up
into several binary packages.</p>
-
+
<p>
For a straightforward library which has a development
environment and a runtime kit including just shared
libraries you need to create two packages:
- <tt><var>libraryname</var><var>soname</var></tt>
- (<var>soname</var> is the shared object name of the shared
- library--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; usually the
- <var>soname</var> is the major number of the library) and
- <tt><var>libraryname</var><var>soname</var>-dev</tt>.</p>
-
+ <tt><var>libraryname</var><var>soversion</var></tt>, where
+ <tt><var>soversion</var></tt> is the version number in the
+ soname of the shared library<footnote>
+ <p>
+ The soname is the shared object name: it's the thing
+ that has to match exactly between building an executable
+ and running it for the dynamic linker to be able run the
+ program. For example, if the soname of the library is
+ <tt>libfoo.so.6</tt>, the library package would be
+ called <tt>libfoo6</tt>.
+ </p>
+ </footnote>
+ and <tt><var>libraryname</var><var>soversion</var>-dev</tt>.
+ </p>
+
<p>
If you prefer only to support one development version at a
time you may name the development package
- <tt><var>libraryname</var>-dev</tt>; otherwise you may
- wish to use <prgn>dpkg</prgn>'s conflicts mechanism to
- ensure that the user only installs one development version
- at a time (after all, different development versions are
- likely to have the same header files in them, causing a
- filename clash if both are 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.</p>
-
+ <tt><var>libraryname</var>-dev</tt>; otherwise you may need
+ to use <prgn>dpkg</prgn>'s Conflicts mechanism (see <ref
+ id="conflicts">) to ensure that the user only installs one
+ development version at a time (as different development
+ versions are likely to have the same header files in them,
+ which would cause a filename clash if both were installed).
+ Typically the development version should also have an exact
+ version dependency on the runtime library, to make sure that
+ compilation and linking happens correctly. The
+ <tt>${Source-Version}</tt> substitution variable can be
+ useful for this purpose.
+ </p>
+
<p>
Packages which use the shared library should have a
dependency on the name of the shared library package,
- <tt><var>libraryname</var><var>soname</var></tt>. When
- the <var>soname</var> changes you can have both versions
- of the library installed while moving from the old library
- to the new.</p>
-
+ <tt><var>libraryname</var><var>soversion</var></tt>. When
+ the soname changes you can have both versions of the library
+ installed while migrating from the old library to the new.
+ </p>
+
<p>
- If your package has some run-time support programs which
- use the shared library you must not put them in
- the shared library package. If you do that then you won't
- be able to install several versions of the shared library
- without getting filename clashes. Instead, either create
- a third package for the runtime binaries (this package
- might typically be named
- <tt><var>libraryname</var>-runtime</tt>--note the absence
- of the <var>soname</var> in the package name) or if the
- development package is small include them in there.</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 their
- <var>soname</var>s at once (so that you don't get filename
+ 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>
- You should follow the directions in the <em>Debian Packaging
- Manual</em> for putting the shared library in its package,
- and you must include a <tt>shlibs</tt> control area
- file with details of the dependencies for packages which
- use the library.</p>
-
+ combined shared libraries package).
+ </p>
+
<p>
- Shared libraries should not be installed
- executable, since <prgn>ld.so</prgn> does not require this
- and trying to execute a shared library results in a core
- dump.</p></sect>
-
-
+ 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>
+ </sect>
+
<sect id="scripts">
<heading>Scripts</heading>
-
+
<p>
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>
-
+
<p>
In the case of Perl scripts this should be
<tt>#!/usr/bin/perl</tt>.</p>
-
+
<p>
Shell scripts (<prgn>sh</prgn> and <prgn>bash</prgn>)
should almost certainly start with <tt>set -e</tt> so that
errors are detected. Every script should use
<tt>set -e</tt> or check the exit status of <em>every</em>
command.</p>
-
+
<p>
- The standard shell interpreter `<tt>/bin/sh</tt>' can be a
+ The standard shell interpreter <tt>/bin/sh</tt> can be a
symbolic link to any POSIX compatible shell, if <tt>echo
- -n</tt> does not generate a newline.
- <footnote>
+ -n</tt> does not generate a newline.<footnote>
<p>
- Debian policy specifies POSIX behavior for /bin/sh, but
- echo -n has widespread use in the Linux community
- (including especially debian policy, the linux kernel
- source, many debian scripts, etc.). This echo -n
- 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.
+ Debian policy specifies POSIX behavior for
+ <tt>/bin/sh</tt>, 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>
</footnote>
- Thus, shell scripts
- specifying `<tt>/bin/sh</tt>' 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', e.g., in the case of
+ Thus, shell scripts specifying <tt>/bin/sh</tt> as
+ interpreter should only use POSIX features. If a script
+ requires non-POSIX features from the shell interpreter, the
+ appropriate shell must be specified in the first line of the
+ script (e.g., <tt>#!/bin/bash</tt>) and the package must
+ depend on the package providing the shell (unless the shell
+ package is marked `Essential', as in the case of
<prgn>bash</prgn>).
</p>
-
+
<p>
- You may wish to restrict your script to POSIX features when possible so
- that it may use <tt>/bin/sh</tt> as its interpreter. If
- your script works with <prgn>ash</prgn>, it's probably
- POSIX compliant, but if you are in doubt, use
- <tt>/bin/bash</tt>.</p>
-
+ You may wish to restrict your script to POSIX features when
+ possible so that it may use <tt>/bin/sh</tt> as its
+ interpreter. If your script works with <prgn>ash</prgn>,
+ it's probably POSIX compliant, but if you are in doubt, use
+ <tt>/bin/bash</tt>.
+ </p>
+
<p>
Perl scripts should check for errors when making any
system calls, including <tt>open</tt>, <tt>print</tt>,
- <tt>close</tt>, <tt>rename</tt> and <tt>system</tt>.</p>
-
+ <tt>close</tt>, <tt>rename</tt> and <tt>system</tt>.
+ </p>
+
<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. It can be found on
- <url id="http://language.perl.com/versus/csh.whynot">, or
- <url id="http://www.cpan.org/doc/FMTEYEWTK/versus/csh.whynot">
- or even on <ftpsite>ftp.cpan.org</ftpsite>
- <ftppath>/pub/perl/CPAN/doc/FMTEYEWTK/versus/csh.whynot</ftppath>.
+ <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>
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
- <prgn>c-shell</prgn> virtual package.</p>
-
+ <prgn>c-shell</prgn> virtual package.
+ </p>
+
<p>
Any scripts which create files in world-writeable
directories (e.g., in <tt>/tmp</tt>) must use a
mechanism which will fail if a file with the same name
already exists.</p>
-
+
<p>
- The Debian base distribution provides the
- <prgn>tempfile</prgn> and <prgn>mktemp</prgn> utilities
- for use by scripts for this purpose.</p></sect>
-
-
+ The Debian base system provides the <prgn>tempfile</prgn>
+ and <prgn>mktemp</prgn> utilities for use by scripts for
+ this purpose.</p></sect>
+
+
<sect>
<heading>Symbolic links</heading>
-
+
<p>
In general, symbolic links within a top-level directory
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 `/'.)</p>
-
+ directory <tt>/</tt>.)</p>
+
<p>
- In addition, symbolic links should be specified as short
- as possible, i.e., link targets like `foo/../bar' are
+ In addition, symbolic links should be specified as short as
+ possible, i.e., link targets like <tt>foo/../bar</tt> are
deprecated.</p>
-
+
<p>
Note that when creating a relative link using
<prgn>ln</prgn> it is not necessary for the target of the
link to exist relative to the working directory you're
- running <prgn>ln</prgn> from; nor is it necessary to
- change directory to the directory where the link is to be
- made. 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>
-
+ running <prgn>ln</prgn> from, nor is it necessary to change
+ directory to the directory where the link is to be made.
+ 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>
+
<p>
For example, in your <prgn>Makefile</prgn> or
- <tt>debian/rules</tt>, do things like:
- <example>
- ln -fs gcc $(prefix)/bin/cc
- ln -fs gcc debian/tmp/usr/bin/cc
- ln -fs ../sbin/sendmail $(prefix)/bin/runq
- ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
+ <tt>debian/rules</tt>, you can do things like:
+ <example compact="compact">
+ln -fs gcc $(prefix)/bin/cc
+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>
-
+
<p>
- A symbolic link pointing to a compressed file should
- always have the same file extension as the referenced
- file. (For example, if a file `<tt>foo.gz</tt>' is
- referenced by a symbolic link, the filename of the link
- has to end with `<tt>.gz</tt>' too, as in
- `bar.gz.')</p></sect>
-
-
+ A symbolic link pointing to a compressed file should always
+ have the same file extension as the referenced file. (For
+ example, if a file <tt>foo.gz</tt> is referenced by a
+ symbolic link, the filename of the link has to end with
+ `<tt>.gz</tt>' too, as in <tt>bar.gz</tt>.)
+ </p>
+ </sect>
+
<sect>
<heading>Device files</heading>
-
+
<p>
Packages must not include device files in the package file
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 <tt>postinst</tt> script,
+ <prgn>MAKEDEV</prgn> in the <prgn>postinst</prgn> script,
after asking the user for permission to do so.</p>
-
+
<p>
Packages must not remove any device files in the
- <tt>postrm</tt> or any other script. This is left to the
+ <prgn>postrm</prgn> or any other script. This is left to the
system administrator.</p>
-
+
<p>
Debian uses the serial devices
<tt>/dev/ttyS*</tt>. Programs using the old
<tt>/dev/cu*</tt> devices should be changed to use
<tt>/dev/ttyS*</tt>.</p>
</sect>
-
+
<sect id="config files">
<heading>Configuration files</heading>
<sect1>
<p>
<taglist>
<tag>configuration file</tag>
- <item><p>
- A file that affects the operation of program, or
+ <item>
+ <p>
+ A file that affects the operation of a program, or
provides site- or host-specific information, or
- otherwise customizes the behavior of program.
+ otherwise customizes the behavior of a program.
Typically, configuration files are intended to be
modified by the system administrator (if needed or
- desired) to conform to local policy or provide more
- useful site-specific behavior.</p>
+ desired) to conform to local policy or to provide
+ more useful site-specific behavior.
+ </p>
</item>
<tag><tt>conffile</tt></tag>
- <item><p>
+ <item>
+ <p>
A file listed in a package's <tt>conffiles</tt>
file, and is treated specially by <prgn>dpkg</prgn>
- (see the <em>Debian Packaging Manual</em>).</p>
+ (see <ref id="configdetails">).
+ </p>
</item>
</taglist>
</p>
<p>
The distinction between these two is important; they are
not interchangeable concepts. Almost all
- <tt>conffiles</tt> are configuration files, but many
- configuration files are not <tt>conffiles</tt>.</p>
+ <tt>conffile</tt>s are configuration files, but many
+ configuration files are not <tt>conffiles</tt>.
+ </p>
<p>
Note that a script that embeds configuration information
- (such as most of the files in <tt>/etc/init.d</tt> and
+ (such as most of the files in <tt>/etc/default</tt> and
<tt>/etc/cron.{daily,weekly,monthly}</tt>) is de-facto a
- configuration file and should be treated as such.</p>
+ configuration file and should be treated as such.
+ </p>
</sect1>
<sect1>
<p>
Configuration file handling must conform to the following
behavior:
- <list>
+ <list compact="compact">
<item>
- <p>local changes must be preserved during a package
- upgrade</p>
+ <p>
+ local changes must be preserved during a package
+ upgrade, and
+ </p>
</item>
<item>
- <p>configuration files must be preserved when the
+ <p>
+ configuration files must be preserved when the
package is removed, and only deleted when the
- package is purged.</p>
+ package is purged.
+ </p>
</item>
- </list></p>
+ </list>
+ </p>
<p>
The easy way to achieve this behavior is to make the
<p>
In order to ensure that local changes are preserved
correctly, no package may contain or make hard links to
- conffiles.
- <footnote>
+ 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 different. The second is that
- <prgn>dpkg</prgn> might break the hard link while
- upgrading <tt>conffile</tt>s.
+ 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>
- 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
+ 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
distribution. If the existence of a file is required for
the package to be sensibly configured it is the
- responsibility of the package maintainer to write scripts
- which correctly create, update, maintain and
- remove-on-purge the file. These scripts must be idempotent
- (i.e., must work correctly if <prgn>dpkg</prgn> needs to
- re-run them due to errors during installation or removal),
- must cope with all the 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.</p>
+ responsibility of the package maintainer to provide
+ maintainer scripts which correctly create, update and
+ maintain the file and remove it on purge. (See <ref
+ id="maintainerscripts"> for more information.) These
+ scripts must be idempotent (i.e., must work correctly if
+ <prgn>dpkg</prgn> needs to re-run them due to errors
+ during installation or removal), must cope with all the
+ 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.
+ </p>
<p>
- The scripts are not required to configure every possible option for
- the package, but only those necessary to get the package
- running on a given system. Ideally the sysadmin should not
- have to do any configuration other than that done
- (semi-)automatically by the <tt>postinst</tt> script.</p>
+ The scripts are not required to configure every possible
+ option for the package, but only those necessary to get
+ the package running on a given system. Ideally the
+ sysadmin should not have to do any configuration other
+ than that done (semi-)automatically by the
+ <prgn>postinst</prgn> script.
+ </p>
<p>
A common practice is to create a script called
<tt><var>package</var>-configure</tt> and have the
- package's <tt>postinst</tt> call it if and only if the
- configuration file does not already exist. In certain
+ package's <prgn>postinst</prgn> call it if and only if the
+ configuration file does not already exist. In certain
cases it is useful for there to be an example or template
- file which the maintainer scripts use. Such files should
- be in <tt>/usr/share/doc</tt> if they are examples or
- <tt>/usr/lib</tt> if they are templates, and should be
- perfectly ordinary <prgn>dpkg</prgn>-handled files
- (<em>not</em> <tt>conffiles</tt>).</p>
+ file which the maintainer scripts use. Such files should
+ be in <tt>/usr/share/<var>package</var></tt> or
+ <tt>/usr/lib/<var>package</var></tt> (depending on whether
+ they are architecture-independent or not). There should
+ be symbolic links to them from
+ <tt>/usr/share/doc/<var>package</var>/examples</tt> if
+ they are examples, and should be perfectly ordinary
+ <prgn>dpkg</prgn>-handled files (<em>not</em>
+ configuration files).
+ </p>
<p>
These two styles of configuration file handling must
not be mixed, for that way lies madness:
<prgn>dpkg</prgn> will ask about overwriting the file
- every time the package is upgraded.</p>
-
+ every time the package is upgraded.
+ </p>
</sect1>
<sect1>
<heading>Sharing configuration files</heading>
<p>
- Packages which specify the same file as
- `<tt>conffile</tt>' must be tagged as <em>conflicting</em>
- with each other.
- </p>
+ Packages which specify the same file as a
+ <tt>conffile</tt> must be tagged as <em>conflicting</em>
+ with each other. (This is an instance of the general rule
+ about not sharing files. Note that neither alternatives
+ nor diversions are likely to be appropriate in this case;
+ in particular, <prgn>dpkg</prgn> does not handle diverted
+ <tt>conffile</tt>s well.)
+ </p>
<p>
- The maintainer scripts must not alter the conffile of
- <em>any</em> package, including the one the scripts belong
- to.</p>
+ The maintainer scripts must not alter a <tt>conffile</tt>
+ of <em>any</em> package, including the one the scripts
+ belong to.
+ </p>
<p>
If two or more packages use the same configuration file
and it is reasonable for both to be installed at the same
time, one of these packages must be defined as
<em>owner</em> of the configuration file, i.e., it will be
- the package to list that distributes the file and lists it
- as a <tt>conffile</tt>. Other packages that use the
- configuration file must 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>
+ the package which handles that file as a configuration
+ file. Other packages that use the configuration file must
+ 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>
<p>
If it is desirable for two or more related packages to
share a configuration file <em>and</em> for all of the
related packages to be able to modify that configuration
file, then the following should be done:
- <enumlist>
+ <enumlist compact="compact">
<item>
<p>
- have one of the related packages (the "core"
- package) manage the configuration file with
- maintainer scripts as described in the previous
- section.</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 core package should also provide a program that
- the other packages may use to modify the
- configuration file.</p>
+ <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 modifications to the configuration file.
- They should either depend on the core package to
- guarantee that the configuration modifier program is
- available or accept gracefully that they cannot
- modify the configuration file if it is not.</p>
+ The related packages must use the provided program
+ to make any desired modifications to the
+ configuration file. They should either depend on
+ the core package to guarantee that the configuration
+ modifier program is available or accept gracefully
+ that they cannot modify the configuration file if it
+ 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>
+ </enumlist>
+ </p>
<p>
Sometimes it's appropriate to create a new package which
provides the basic infrastructure for the other packages
- and which manages the shared configuration files. (Check
- out the <tt>sgml-base</tt> package as an example.)</p>
+ and which manages the shared configuration files. (The
+ <tt>sgml-base</tt> package is a good example.)
+ </p>
</sect1>
<sect1>
<heading>User configuration files ("dotfiles")</heading>
<p>
- Files in <tt>/etc/skel</tt> will automatically be copied
- into new user accounts by <prgn>adduser</prgn>. They
- should not be referenced there by any program.</p>
+ The files in <tt>/etc/skel</tt> will automatically be
+ copied into new user accounts by <prgn>adduser</prgn>.
+ No other program should reference the files in
+ <tt>/etc/skel</tt>.
+ </p>
<p>
Therefore, if a program needs a dotfile to exist in
advance in <tt>$HOME</tt> to work sensibly, that dotfile
- should be installed in <tt>/etc/skel</tt> (and listed in
- conffiles, if it is not generated and modified dynamically
- by the package's installation scripts).</p>
+ should be installed in <tt>/etc/skel</tt> and treated as a
+ configuration file.
+ </p>
<p>
However, programs that require dotfiles in order to
operate sensibly (dotfiles that they do not create
- themselves automatically, that is) are a bad thing, and
- programs should be configured by the Debian default
- installation as close to normal as possible.</p>
+ themselves automatically, that is) are a bad thing.
+ Furthermore, programs should be configured by the Debian
+ default installation to behave as closely to the upstream
+ default behaviour as possible.
+ </p>
<p>
Therefore, if a program in a Debian package needs to be
- configured in some way in order to operate sensibly that
- configuration should be done in a site-wide global
- configuration file elsewhere in <tt>/etc</tt>. Only if the
- program doesn't support a site-wide default configuration
- and the package maintainer doesn't have time to add it
- may a default per-user file be placed in
- <tt>/etc/skel</tt>.</p>
+ configured in some way in order to operate sensibly, that
+ should be done using a site-wide configuration file placed
+ in <tt>/etc</tt>. Only if the program doesn't support a
+ site-wide default configuration and the package maintainer
+ doesn't have time to add it may a default per-user file be
+ placed in <tt>/etc/skel</tt>.
+ </p>
<p>
<tt>/etc/skel</tt> should be as empty as we can make it.
- This is particularly true because there is no easy
- mechanism for ensuring that the appropriate dotfiles are
- copied into the accounts of existing users when a package
- is installed.</p>
+ This is particularly true because there is no easy (or
+ necessarily desirable) mechanism for ensuring that the
+ appropriate dotfiles are copied into the accounts of
+ existing users when a package is installed.
+ </p>
</sect1>
</sect>
-
+
<sect>
<heading>Log files</heading>
- <p>
- The traditional approach to log files has been to set up ad
- hoc log rotation schemes using simple shell scripts and
- cron. While this approach is highly customizable, it
- requires quite a lot of sysadmin work. Even though the
- original Debian system helped a little by automatically
- installing a system which can be used as a template, this
- was deemed not enough.
- </p>
-
- <p>
- A better scheme is to use logrotate, a GPL'd program
- developed by Red Hat, which centralizes log management. It
- has both a configuration file (<tt>/etc/logrotate.conf</tt>)
- and a directory where packages can drop logrotation info
- (<tt>/etc/logrotate.d</tt>).
- </p>
-
<p>
Log files should usually be named
<tt>/var/log/<var>package</var>.log</tt>. If you have many
- log files, or need a separate directory for permissions
+ log files, or need a separate directory for permission
reasons (<tt>/var/log</tt> is writable only by
<tt>root</tt>), you should usually create a directory named
- <tt>/var/log/<var>package</var></tt>.</p>
-
+ <tt>/var/log/<var>package</var></tt> and place your log
+ files there.
+ </p>
+
<p>
- Log files must be rotated occasionally so
- that they don't grow indefinitely; the best way to do this
- is to drop a script into the directory
+ Log files must be rotated occasionally so that they don't
+ grow indefinitely; the best way to do this is to drop a log
+ rotation configuration file into the directory
<tt>/etc/logrotate.d</tt> and use the facilities provided by
- logrotate. Here is a good example for a logrotate config
- file (for more information see <manref name="logrotate"
- section="8">):
- <example>
- /var/log/foo/* {
- rotate 12
- weekly
- compress
- postrotate
- /etc/init.d/foo force-reload
- endscript
- }
- </example>
- Which rotates all files under `/var/log/foo', saves 12
- compressed generations, and sends a HUP signal at the end of
- rotation.
+ logrotate.<footnote>
+ <p>
+ The traditional approach to log files has been to set up
+ <em>ad hoc</em> log rotation schemes using simple shell
+ scripts and cron. While this approach is highly
+ customizable, it requires quite a lot of sysadmin work.
+ Even though the original Debian system helped a little
+ by automatically installing a system which can be used
+ as a template, this was deemed not enough.
+ </p>
+ <p>
+ The use of <prgn>logrotate</prgn>, a program developed
+ by Red Hat, is better, as it centralizes log management.
+ It has both a configuration file
+ (<tt>/etc/logrotate.conf</tt>) and a directory where
+ packages can drop their individual log rotation
+ configurations (<tt>/etc/logrotate.d</tt>).
+ </p>
+ </footnote>
+ Here is a good example for a logrotate config
+ file (for more information see <manref name="logrotate"
+ section="8">):
+ <example compact="compact">
+/var/log/foo/* {
+rotate 12
+weekly
+compress
+postrotate
+/etc/init.d/foo force-reload
+endscript
+}
+ </example>
+ This rotates all files under <tt>/var/log/foo</tt>, saves 12
+ compressed generations, and forces the daemon to reload its
+ configuration information after the log rotation.
</p>
-
+
<p>
Log files should be removed when the package is
- purged (but not when it is only removed), by checking the
- argument to the <tt>postrm</tt> script (see the <em>Debian
- Packaging Manual</em> for details).</p>
+ purged (but not when it is only removed). This should be
+ done by the <prgn>postrm</prgn> script when it is called
+ with the argument <tt>purge</tt> (see <ref
+ id="removedetails">).
+ </p>
</sect>
-
-
+
<sect>
<heading>Permissions and owners</heading>
-
+
<p>
The rules in this section are guidelines for general use.
If necessary you may deviate from the details below.
However, if you do so you must make sure that what is done
is secure and you should try to be as consistent as possible
with the rest of the system. You should probably also
- discuss it on <prgn>debian-devel</prgn> first.</p>
-
+ discuss it on <prgn>debian-devel</prgn> first.
+ </p>
+
<p>
Files should be owned by <tt>root.root</tt>, and made
writable only by the owner and universally readable (and
- executable, if appropriate).</p>
-
+ executable, if appropriate), that is mode 644 or 755.
+ </p>
+
<p>
Directories should be mode 755 or (for group-writability)
mode 2775. The ownership of the directory should be
- consistent with its mode--if a directory is mode 2775, it
+ consistent with its mode: if a directory is mode 2775, it
should be owned by the group that needs write access to
- it.</p>
-
+ it.
+ </p>
+
<p>
Setuid and setgid executables should be mode 4755 or 2755
respectively, and owned by the appropriate user or group.
They should not be made unreadable (modes like 4711 or
2711 or even 4111); doing so achieves no extra security,
because anyone can find the binary in the freely available
- Debian package--it is merely inconvenient. For the same
+ Debian package; it is merely inconvenient. For the same
reason you should not restrict read or execute permissions
- on non-set-id executables.</p>
-
+ on non-set-id executables.
+ </p>
+
<p>
Some setuid programs need to be restricted to particular
sets of users, using file permissions. In this case they
- should be owned by the uid to which they are set-id, and
- by the group which should be allowed to execute them.
- They should have mode 4754; there is no point in making
+ should be owned by the uid to which they are set-id, and by
+ the group which should be allowed to execute them. They
+ should have mode 4754; again there is no point in making
them unreadable to those users who must not be allowed to
- execute them.</p>
-
+ execute them.
+ </p>
+
<p>
- You must not arrange that the system administrator can only
+ It is possible to arrange that the system administrator can
reconfigure the package to correspond to their local
- security policy by changing the permissions on a binary.
- Ordinary files installed by <prgn>dpkg</prgn> (as opposed
- to conffiles and other similar objects) have their
- permissions reset to the distributed permissions when the
- package is reinstalled. Instead you should consider (for
- example) creating a group for people allowed to use the
- program(s) and making any setuid executables executable
- only by that group.</p>
-
+ 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
+ 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
+ executables executable only by that group.
+ </p>
+
<p>
If you need to create a new user or group for your package
there are two possibilities. Firstly, you may need to
group id (rather than just the name) into the binary
(though this latter should be avoided if possible, as in
this case you need a statically allocated id).</p>
-
+
<p>
If you need a statically allocated id, you must ask for a
- user or group id from the base system
- maintainer, and must not release the package until you
- have been allocated one. Once you have been allocated one
- you must make the package depend on a version of the base
- system with the id present in <tt>/etc/passwd</tt> or
- <tt>/etc/group</tt>, or alternatively arrange for your
- package to create the user or group itself with the
- correct id (using <tt>adduser</tt>) in its pre- or
- post-installation script (the latter is to be preferred if
- it is possible).</p>
-
- <p>
- On the other hand, the program might be able to determine the
- uid or gid from the group name at runtime, so that a
- dynamic 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 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
- <prgn>adduser</prgn> in the pre- or post-installation
- script (again, the latter is to be preferred if it is
- possible).</p>
-
- <p>
- Note that changing the numeric value of an id associated with a name
- is very difficult, and involves searching the file system for all
- appropriate files. You need to think carefully whether a static or
- dynamic id is required, since changing your mind later will cause
- problems.</p>
+ user or group id from the <tt>base-passwd</tt> maintainer,
+ and must not release the package until you have been
+ allocated one. Once you have been allocated one you must
+ either make the package depend on a version of the
+ <tt>base-passwd</tt> package with the id present in
+ <tt>/etc/passwd</tt> or <tt>/etc/group</tt>, or arrange for
+ your package to create the user or group itself with the
+ correct id (using <tt>adduser</tt>) in its
+ <prgn>preinst</prgn> or <prgn>postinst</prgn>. (Doing it in
+ the <prgn>postinst</prgn> is to be preferred if it is
+ possible, otherwise a pre-dependency will be needed on the
+ <tt>adduser</tt> package.)
+ </p>
+
+ <p>
+ On the other hand, the program might be able to determine
+ the uid or gid from the user or group name at runtime, so
+ 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
+ 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
+ <prgn>adduser</prgn> in the <prgn>preinst</prgn> or
+ <prgn>postinst</prgn> script (again, the latter is to be
+ preferred if it is possible).
+ </p>
+
+ <p>
+ Note that changing the numeric value of an id associated
+ with a name is very difficult, and involves searching the
+ file system for all appropriate files. You need to think
+ carefully whether a static or dynamic id is required, since
+ changing your mind later will cause problems.
+ </p>
+
+ <sect1><heading>The use of <prgn>dpkg-statoverride</prgn></heading>
+ <p>
+ This section is not intended as policy, but as a
+ 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>
+ 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
+ normal permissions, and leave it for the system
+ administrator to make any desired changes. For example, a
+ daemon which is normally required to be setuid root, but
+ in certain situations could be used without being setuid,
+ should be installed setuid in the <tt>.deb</tt>. Then the
+ local system administrator can change this if they wish.
+ If there are two standard ways of doing it, the package
+ 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.
+ </p>
+
+ <p>
+ Given the above, <prgn>dpkg-statoverride</prgn> is
+ essentially a tool for system administrators and would not
+ normally be needed in the maintainer scripts. There is
+ one type of situation, though, where calls to
+ <prgn>dpkg-statoverride</prgn> would be needed in the
+ maintainer scripts, and that involves packages which use
+ dynamically allocated user or group ids. In such a
+ situation, something like the following idiom can be very
+ helpful in the package's <prgn>postinst</prgn>, where
+ <tt>sysuser</tt> is a dynamically allocated id:
+ <example>
+for i in /usr/bin/foo /usr/sbin/bar
+do
+ if ! dpkg-statoverride --list $i >/dev/null
+ then
+ dpkg-statoverride --update --add sysuser root 4755 $i
+ fi
+done
+ </example>
+ The corresponding <tt>dpkg-statoverride --remove</tt>
+ calls can then be made unconditionally when the package is
+ purged.
+ </p>
+ </sect1>
</sect>
</chapt>
- <chapt>
+ <chapt id="customized-programs">
<heading>Customized programs</heading>
-
+
<sect id="arch-spec">
<heading>Architecture specification strings</heading>
-
+
<p>
If a program needs to specify an <em>architecture specification
- string</em> in some place, the following format should be used:
- <example>
- <arch>-<os>
- </example>
- where `<arch>' is one of the following: i386, alpha, arm, m68k,
- powerpc, sparc and `<os>' is one of: linux, gnu. Use
- of <em>gnu</em> in this string is reserved for the GNU/Hurd
- operating system.</p>
- <p>
- Note, that we don't want to use `<arch>-debian-linux'
- to apply to the rule `architecture-vendor-os' since this
- would make our programs incompatible to other Linux
- distributions. Also note, that we don't use
- `<arch>-unknown-linux', since the `unknown' does not
- look very good.</p></sect>
-
-
+ 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>.
+ </p>
+
+ <p>
+ Note that we don't want to use
+ <tt><var>arch</var>-debian-linux</tt> to apply to the rule
+ <tt><var>architecture</var>-<var>vendor</var>-<var>os</var></tt>
+ since this would make our programs incompatible with other
+ Linux distributions. We also don't use something like
+ <tt><var>arch</var>-unknown-linux</tt>, since the
+ <tt>unknown</tt> does not look very good.
+ </p>
+ </sect>
+
<sect>
<heading>Daemons</heading>
-
+
<p>
The configuration files <tt>/etc/services</tt>,
<tt>/etc/protocols</tt>, and <tt>/etc/rpc</tt> are managed
- by the <prgn>netbase</prgn> package and may not be modified
- by other packages.</p>
-
+ by the <prgn>netbase</prgn> package and must not be modified
+ by other packages.
+ </p>
+
<p>
If a package requires a new entry in one of these files, the
maintainer should get in contact with the
<prgn>netbase</prgn> maintainer, who will add the entries
and release a new version of the <prgn>netbase</prgn>
- package.</p>
-
+ package.
+ </p>
+
<p>
The configuration file <tt>/etc/inetd.conf</tt> must not be
modified by the package's scripts except via the
<prgn>update-inetd</prgn> script or the
- <prgn>DebianNet.pm</prgn> Perl module.</p>
-
+ <tt>DebianNet.pm</tt> Perl module. See their documentation
+ for details on how to add entries.
+ </p>
+
<p>
If a package wants to install an example entry into
<tt>/etc/inetd.conf</tt>, the entry must be preceded with
exactly one hash character (<tt>#</tt>). Such lines are
treated as `commented out by user' by the
<prgn>update-inetd</prgn> script and are not changed or
- activated during a package updates.</p></sect>
-
-
+ activated during package updates.
+ </p>
+ </sect>
+
<sect>
- <heading>Using pseudo-ttys and modifying wtmp, utmp and lastlog</heading>
-
+ <heading>Using pseudo-ttys and modifying wtmp, utmp and
+ lastlog</heading>
+
<p>
Some programs need to create pseudo-ttys. This should be done
using Unix98 ptys if the C library supports it. The resulting
program must not be installed setuid root, unless that
is required for other functionality.
</p>
-
+
<p>
The files <tt>/var/run/utmp</tt>, <tt>/var/log/wtmp</tt> and
<tt>/var/log/lastlog</tt> must be installed writeable by
- group utmp. Programs who need to modify those files must
- be installed setgid utmp.
+ group <tt>utmp</tt>. Programs which need to modify those
+ files must be installed setgid <tt>utmp</tt>.
</p>
</sect>
<sect>
<heading>Editors and pagers</heading>
-
+
<p>
Some programs have the ability to launch an editor or pager
- program to edit or display a text document. Since there are
+ 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
- pager.</p>
-
+ pager.
+ </p>
+
<p>
In addition, every program should choose a good default
editor/pager if none is selected by the user or system
- administrator.</p>
-
+ administrator.
+ </p>
+
<p>
Thus, every program that launches an editor or pager must
- use the EDITOR or PAGER environment variables to determine
- the editor/pager the user wants to get started. If these
+ use the EDITOR or PAGER environment variable to determine
+ the editor or pager the user wishes to use. If these
variables are not set, the programs <tt>/usr/bin/editor</tt>
- and <tt>/usr/bin/pager</tt> should be used, respectively.</p>
-
+ and <tt>/usr/bin/pager</tt> should be used, respectively.
+ </p>
+
<p>
- These two files are managed through `alternatives.' That is,
- every package providing an editor or pager must call the
+ These two files are managed through the <prgn>dpkg</prgn>
+ `alternatives' mechanism. Thus every package providing an
+ editor or pager must call the
<prgn>update-alternatives</prgn> script to register these
- programs.</p>
-
+ programs.
+ </p>
+
<p>
- If it is very hard to adapt a program to make us of the
- EDITOR and PAGER variables, that program may be configured
- to use <tt>/usr/bin/sensible-editor</tt> and
- <tt>/usr/bin/sensible-pager</tt> as editor or pager program,
- respectively. These are two scripts provided in the Debian
- base system that check the EDITOR and PAGER variables and
- launch the appropriate program or fall back to
- <tt>/usr/bin/editor</tt> and <tt>/usr/bin/pager</tt>,
- automatically.</p>
-
+ If it is very hard to adapt a program to make use of the
+ EDITOR or PAGER variables, that program may be configured to
+ use <tt>/usr/bin/sensible-editor</tt> and
+ <tt>/usr/bin/sensible-pager</tt> as the editor or pager
+ program respectively. These are two scripts provided in the
+ Debian base system that check the EDITOR and PAGER variables
+ and launch the appropriate program, and fall back to
+ <tt>/usr/bin/editor</tt> and <tt>/usr/bin/pager</tt> if the
+ variable is not set.
+ </p>
+
<p>
A program may also use the VISUAL environment variable to
- determine the user's choice of editor. If it exists, it
- should take precedence over EDITOR. This is in fact what
- <tt>/usr/bin/sensible-editor</tt> does.</p>
+ determine the user's choice of editor. If it exists, it
+ should take precedence over EDITOR. This is in fact what
+ <tt>/usr/bin/sensible-editor</tt> does.
+ </p>
<p>
It is not required for a package to depend on
- `editor' and `pager', nor is it required for a package to
- provide such virtual packages.
- <footnote>
+ <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,
+ The Debian base system already provides an editor and a
+ pager program,
</p>
</footnote>
</p>
-
</sect>
-
-
+
<sect id="web-appl">
<heading>Web servers and applications</heading>
-
+
<p>
This section describes the locations and URLs that should
- be used by all web servers and web application in the Debian
- system.</p>
-
+ be used by all web servers and web applications in the
+ Debian system.
+ </p>
+
<p>
<enumlist>
<item>
- <p>Cgi-bin executable files are installed in the
+ <p>
+ Cgi-bin executable files are installed in the
directory
- <example>
- /usr/lib/cgi-bin/<cgi-bin-name>
+ <example compact="compact">
+/usr/lib/cgi-bin/<var>cgi-bin-name</var>
</example>
and should be referred to as
- <example>
- http://localhost/cgi-bin/<cgi-bin-name>
- </example></p></item>
-
-
- <item><p>Access to html documents</p>
-
+ <example compact="compact">
+http://localhost/cgi-bin/<var>cgi-bin-name</var>
+ </example>
+ </p>
+ </item>
+
+ <item><p>Access to HTML documents</p>
+
<p>
- Html documents for a package are stored in
- <tt>/usr/share/doc/<var>package</var></tt> but should
- be accessed via symlinks as
- <tt>/usr/doc/<var>package</var></tt><footnote> for
- backward compatibility, see <ref id="usrdoc"></footnote>
+ HTML documents for a package are stored in
+ <tt>/usr/share/doc/<var>package</var></tt>
and can be referred to as
- <example>
- http://localhost/doc/<package>/<filename>
- </example></p></item>
-
-
+ <example compact="compact">
+http://localhost/doc/<var>package</var>/<var>filename</var>
+ </example>
+ </p>
+ <p>
+ The web server should restrict access to the document
+ tree so that only clients on the same host can read
+ the documents. If the web server does not support such
+ access controls, then it should not provide access at
+ all, or ask about providing access during installation.
+ </p>
+ </item>
+
<item><p>Web Document Root</p>
-
+
<p>
Web Applications should try to avoid storing files in
the Web Document Root. Instead they should use the
- /usr/share/doc/<package> directory for documents and
- register the Web Application via the menu package. If
- access to the web-root is unavoidable then use
- <example>
- /var/www
- </example>
- as the Document Root. This might be just a
- symbolic link to the location where the sysadmin has
- put the real document root.</p>
+ /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
+ <example compact="compact">
+/var/www
+ </example>
+ as the Document Root. This might be just a symbolic
+ link to the location where the system administrator
+ has put the real document root.
+ </p>
</item>
-
+
</enumlist></p></sect>
-
-
- <sect>
+
+
+ <sect id="mail-transport-agents">
<heading>Mail transport, delivery and user agents</heading>
-
+
<p>
- Debian packages which process electronic mail, whether
- mail-user-agents (MUAs) or mail-transport-agents (MTAs),
- must make sure that they are compatible with the
- configuration decisions below. Failure to do this may
- result in lost mail, broken <tt>From:</tt> lines, and other
- serious brain damage!</p>
-
+ Debian packages which process electronic mail, whether mail
+ user agents (MUAs) or mail transport agents (MTAs), must
+ ensure that they are compatible with the configuration
+ decisions below. Failure to do this may result in lost
+ mail, broken <tt>From:</tt> lines, and other serious brain
+ damage!
+ </p>
+
<p>
- The mail spool is <tt>/var/spool/mail</tt> and the interface
- to send a mail message is <tt>/usr/sbin/sendmail</tt> (as
- per the FHS). The mail spool is part of the base system
- and not part of the MTA package.</p>
-
+ The mail spool is <tt>/var/mail</tt> and the interface to
+ send a mail message is <tt>/usr/sbin/sendmail</tt> (as per
+ the FHS). On older systems, the mail spool may be
+ physically located in <tt>/var/spool/mail</tt>, but all
+ access to the mail spool should be via the
+ <tt>/var/mail</tt> symlink. The mail spool is part of the
+ base system and not part of the MTA package.
+ </p>
+
<p>
All Debian MUAs, MTAs, MDAs and other mailbox accessing
- programs (like IMAP daemons) must lock the mailbox in an
+ programs (such as IMAP daemons) must lock the mailbox in an
NFS-safe way. This means that <tt>fcntl()</tt> locking must
- be combined with dot locking. To avoid deadlocks, a
- program should use <tt>fcntl()</tt> first and dot locking
- after this or alternatively implement the two locking
- methods in a non blocking way<footnote>
+ be combined with dot locking. To avoid deadlocks, a program
+ 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>
+ 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>
- <tt>liblockfile</tt> version >>1.01</p>
+ You will need to depend on <tt>liblockfile1
+ (>>1.01)</tt> to use these functions.
+ </p>
</footnote> packages is the recommended way to realize this.
</p>
-
+
<p>
- Mailboxes are generally 660 <tt><var>user</var>.mail</tt>
- unless the user has chosen otherwise. A MUA may remove a
+ Mailboxes are generally mode 660
+ <tt><var>user</var>.mail</tt> unless the system
+ administrator has chosen otherwise. A MUA may remove a
mailbox (unless it has nonstandard permissions) in which
case the MTA or another MUA must recreate it if needed.
- Mailboxes must be writable by group mail.</p>
-
+ Mailboxes must be writable by group mail.
+ </p>
+
<p>
The mail spool is 2775 <tt>root.mail</tt>, and MUAs should
be setgid mail to do the locking mentioned above (and
must obviously avoid accessing other users' mailboxes
using this privilege).</p>
-
+
<p>
<tt>/etc/aliases</tt> is the source file for the system mail
- aliases (e.g., postmaster, usenet, etc.)--it is the one
- which the sysadmin and <tt>postinst</tt> scripts may edit.
- After <tt>/etc/aliases</tt> is edited the program or human
- editing it must call <prgn>newaliases</prgn>. All MTA
+ aliases (e.g., postmaster, usenet, etc.), it is the one
+ which the sysadmin and <prgn>postinst</prgn> scripts may
+ edit. After <tt>/etc/aliases</tt> is edited the program or
+
human editing it must call <prgn>newaliases</prgn>. All MTA
packages must come with a <prgn>newaliases</prgn> program,
- even if it does nothing, but older MTA packages do not do
+ even if it does nothing, but older MTA packages did not do
this so programs should not fail if <prgn>newaliases</prgn>
- cannot be found.</p>
-
+ cannot be found. Note that because of this, all MTA
+ packages must have <tt>Provides</tt>, <tt>Conflicts</tt> and
+ <tt>Replaces: mail-transport-agent</tt> control file
+ fields.
+ </p>
+
<p>
The convention of writing <tt>forward to
<var>address</var></tt> in the mailbox itself is not
supported. Use a <tt>.forward</tt> file instead.</p>
-
+
<p>
The <prgn>rmail</prgn> program used by UUCP
for incoming mail should be <tt>/usr/sbin/rmail</tt>.
- Likewise, <prgn>rsmtp</prgn>, for receiving
+ Likewise, <prgn>rsmtp</prgn>, for receiving
batch-SMTP-over-UUCP, should be <tt>/usr/sbin/rsmtp</tt> if it
is supported.</p>
-
- <p>
- If you need to know what name to use (for example) on
- outgoing news and mail messages which are generated locally,
- you should use the file <tt>/etc/mailname</tt>. It will
- contain the portion after the username and <tt>@</tt> (at)
- sign for email addresses of users on the machine (followed
- by a newline).</p>
-
+
<p>
- A package should check for the existence of this file. If
- it exists it should use it without comment. (An MTA's
- prompting configuration script may wish to prompt the user
- even if it finds this file exists.) If it does not exist it
- should prompt the user for the value and store it in
- <tt>/etc/mailname</tt> as well as using it in the package's
- configuration. The prompt should make it clear that the
- name will not just be used by that package. For example, in
- this situation the INN package says:
- <example>
- 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>']:
+ If your package needs to know what hostname to use on (for
+ example) outgoing news and mail messages which are generated
+ locally, you should use the file <tt>/etc/mailname</tt>. It
+ will contain the portion after the username and <tt>@</tt>
+ (at) sign for email addresses of users on the machine
+ (followed by a newline).
+ </p>
+
+ <p>
+ Such 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
+ exists. If the file does not exist, the package should
+ prompt the user for the value (preferably using
+ <prgn>debconf</prgn>) and store it in <tt>/etc/mailname</tt>
+ as well as using it in the package's configuration. The
+ prompt should make it clear that the name will not just be
+ used by that package. For example, in this situation the
+ <tt>inn</tt> package could say something like:
+ <example compact="compact">
+Please enter the `mail name' of your system. This is the
+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>']:
</example>
where <var>syshostname</var> is the output of <tt>hostname
- --fqdn</tt>.</p></sect>
-
-
+ --fqdn</tt>.
+ </p>
+ </sect>
+
<sect>
<heading>News system configuration</heading>
-
+
<p>
All the configuration files related to the NNTP (news)
servers and clients should be located under
<tt>/etc/news</tt>.</p>
-
+
<p>
There are some configuration issues that apply to a number
of news clients and server packages on the machine. These
are:
-
+
<taglist>
- <tag>/etc/news/organization</tag>
+ <tag><tt>/etc/news/organization</tt></tag>
<item><p>A string which should appear as the
organization header for all messages posted
by NNTP clients on the machine</p></item>
-
- <tag>/etc/news/server</tag>
+
+ <tag><tt>/etc/news/server</tt></tag>
<item><p>Contains the FQDN of the upstream NNTP
server, or localhost if the local machine is
an NNTP server.</p></item>
</taglist>
-
- Other global files may be added as required for cross-package news
+
+ Other global files may be added as required for cross-package news
configuration.</p></sect>
-
-
+
+
<sect>
<heading>Programs for the X Window System</heading>
-
- <p>
- <em>Programs that may be configured with support for the X Window
- System</em> must be configured to do so and must declare any
- package dependencies necessary to satisfy their runtime
- requirements when using the X Window System, unless the package
- in question is of standard or higher priority, in which case
- X-specific binaries may be split into a separate package, or
- alternative versions of the package with X support may be
- provided.
- </p>
-
-
- <p>
- <em>Packages which provide an X server</em> that, directly or
- 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 "xserver" virtual package which
- appears in the virtual packages list. In a nutshell, X
- servers that interface directly with the display and input
- hardware or via another subsystem (e.g., GGI) should provide
- xserver. Things like Xvfb, Xnest, and Xprt should not.
- </p>
- </footnote>
- </p>
- <p>
- <em>Packages that provide a terminal emulator</em> for the X
- Window System which support a terminal type with a terminfo
- description provided in the <tt>ncurses-base</tt> package
- should declare in their control data that they provide the
- virtual package <tt>x-terminal-emulator</tt>. They should
- also register themselves as an alternative for
- <tt>/usr/bin/x-terminal-emulator</tt>, with a priority of
- 20.
- </p>
+ <sect1>
+ <heading>Providing X support and package priorities</heading>
- <p>
- <em>Packages that provide window managers</em> should declare in
- their control data that they provide the virtual package
- <tt>x-window-manager</tt>. They should also register themselves as an
- alternative for <tt>/usr/bin/x-window-manager</tt>, with a priority
- calculated as follows:
- <list>
- <item>Start with a priority of 20.</item>
- <item>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
- configuration files belonging to the system or user
- have to be edited to activate the feature); if
- configuration files must be modified, add only 10
- points.</item>
- <item>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.</item>
- </list>
- </p>
+ <p>
+ Programs that can be configured with support for the X
+ Window System must be configured to do so and must declare
+ any package dependencies necessary to satisfy their
+ runtime requirements when using the X Window System. If
+ such a package is of higher priority than the X packages
+ on which it depends, it is required that either the
+ X-specific components be split into a separate package, or
+ that an alternative version of the package, which includes
+ X support, be provided, or that the package's priority be
+ lowered.
+ </p>
+ </sect1>
- <p>
- <em>Packages that provide fonts for the X Window System</em>
- must do a number of things to ensure that they are both
- available without modification of the X or font server
- configuration, and that they do not corrupt files used by
- other font packages to register information about themselves.
- <enumlist>
- <item>
- Fonts of any type supported by the X Window System
- should be be in a separate binary package from any
- executables, libraries, or documentation (except that
- specific to the fonts shipped); if a program or
- library is <em>unusable</em> without one or more
- specific fonts, the package containing the program or
- library should declare a dependency on the package(s)
- containing the font(s) it requires.
- </item>
- <item>
- BDF fonts should be converted to PCF fonts with the
- <tt>bdftopcf</tt> utility (available in the
- <tt>xutils</tt> package, <tt>gzip</tt>ped, and
- placed in a directory that corresponds to their
- resolution:
- <list>
- <item>
- 100 dpi fonts should be placed in
- <tt>/usr/X11R6/lib/X11/fonts/100dpi/</tt>.
- </item>
- <item>
- 75 dpi fonts should be placed in
- <tt>/usr/X11R6/lib/X11/fonts/75dpi/</tt>.
- </item>
- <item>
- Character-cell fonts, cursor fonts, and other
- low-resolution fonts should be placed in
- <tt>/usr/X11R6/lib/X11/fonts/misc/</tt>.
- </item>
- </list>
- </item>
- <item>
- Speedo fonts should be placed in
- <tt>/usr/X11R6/lib/X11/fonts/Speedo/</tt>.
- </item>
- <item>
- Type 1 fonts should be placed in
- <tt>/usr/X11R6/lib/X11/fonts/Type1/</tt>. If font
- metric files are available, they may be placed here as
- well.
- </item>
- <item>
- Subdirectories of <tt>/usr/X11R6/lib/X11/fonts/</tt>
- other than those listed above should be neither created nor
- used. (The <tt>PEX</tt> and <tt>cyrillic</tt> directories are
- excepted for historical reasons, but installation of files into
- these directories remains discouraged.)
- </item>
- <item>
- 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 the files' actual location
- in the filesystem. Such a location should comply with the
- FHS.
- </item>
- <item>
- 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 "-75dpi" or "-100dpi"
- appended to the names of the packages containing the
- corresponding fonts.
- </item>
- <item>
- Fonts destined for the <tt>misc</tt> subdirectory should
- not be included in the same package as 75dpi or 100dpi fonts;
- instead, they should be provided in a separate package with
- "-misc" appended to its name.
- </item>
- <item>
- Font packages <em>must not</em> provide the files
- <tt>fonts.dir</tt>, <tt>fonts.alias</tt>, or
- <tt>fonts.scale</tt> in a font directory.
- <list>
- <item>
- <tt>fonts.dir</tt> files must not be provided at
- all.
- </item>
- <item>
- <tt>fonts.alias</tt> and <tt>fonts.scale</tt>
- files, if needed, should be provided in the
- directory
- <tt>/etc/X11/fonts/<em>fontdir</em>/<em>package</em>.<em>extension</em></tt>,
- where <em>fontdir</em> is the name of the
- subdirectory of
- <tt>/usr/X11R6/lib/X11/fonts/</tt> where the
- package's corresponding fonts are stored (e.g.,
- <tt>75dpi</tt> or <tt>misc</tt>),
- <em>package</em> is the name of the package that
- provides these fonts, and <em>extension</em> is
- either <tt>scale</tt> or <tt>alias</tt>,
- whichever corresponds to the file
- contents.
- </item>
- </list>
- </item>
- <item>
- Font packages must declare a dependency on
- <tt>xutils</tt> and, in the package
- post-installation and post-removal scripts, invoke the
- <tt>mkfontdir</tt> command on each directory into
- which they installed fonts.
- </item>
- <item>
- Font packages that provide one or more
- <tt>fonts.scale</tt> files as described above must declare a
- versioned dependency on <tt>xutils (>=
- 4.0.2)</tt> and invoke <tt>update-fonts-scale</tt> on each
- directory into which they installed fonts
- <em>before</em> invoking <tt>mkfontdir</tt> on that
- directory. This invocation must occur in both the
- post-installation and post-removal scripts.
- </item>
- <item>
- Font packages that provide one or more
- <tt>fonts.alias</tt> files as described above must
- declare a versioned dependency on <tt>xutils
- (>= 4.0.2)</tt> and, in the package
- post-installation and post-removal scripts, invoke
- <tt>update-fonts-alias</tt> on each directory into
- which they installed fonts.
- </item>
- <item>
- Font packages must not provide alias names for the
- fonts they include which collide with alias names already in
- use by fonts already packaged.
- </item>
- <item>
- Font packages must not provide fonts with the same XLFD
- registry name as another font already packaged.
- </item>
- </enumlist>
- </p>
-
- <p>
- <em>Application defaults</em> files must be installed in the
- directory <tt>/usr/X11R6/lib/X11/app-defaults/</tt>.
- <footnote>
- <p>Note: This shall change very shortly.</p>
- </footnote>
- They should not be registered as <em>conffile</em>s or
- otherwise treated as configuration files. Customization of
- programs' X resources may be supported with the provision of
- a file with the same name as that of the package placed in
- the <tt>/etc/X11/Xresources/</tt> directory, which must
- registered as a <em>conffile</em>. <em>Important:</em>
- packages that install files into the
- <tt>/etc/X11/Xresources/</tt> directory <em>must</em>
- declare a conflict with <tt>xbase (<<
- 3.3.2.3a-2)</tt>; if this is not done it is possible for the
- installing package to destroy a previously-existing
- <tt>/etc/X11/Xresources</tt> <em>file</em> which had been
- customized by the system administrator.
- <footnote>
- <p>Rationale: clarifies the language to properly
- address the package maintainer, not the system
- administrator, as to how to manage
- /etc/X11/Xresources.</p>
- </footnote>
- </p>
+ <sect1>
+ <heading>Packages providing an X server</heading>
-
- <p>
- <em>Packages using the X Window System should abide by the FHS
- standard whenever possible</em>; they should install binaries,
- libraries, manual pages, and other files in FHS-mandated
- locations wherever possible. This means that files must
- not be installed into <tt>/usr/X11R6/bin/</tt>,
- <tt>/usr/X11R6/lib/</tt>, or <tt>/usr/X11R6/man/</tt> unless
- this is necessary for the package to operate properly.
- Configuration files for window managers and display managers
- should be placed in a subdirectory of <tt>/etc/X11/</tt>
- corresponding to the package name due to these programs'
- tight integration with the mechanisms of the X Window
- System. Application-level programs should use the
- <tt>/etc/</tt> directory unless otherwise mandated by
- policy. The installation of files into subdirectories of
- <tt>/usr/X11R6/include/X11/</tt> and
- <tt>/usr/X11R6/lib/X11/</tt> is permitted but discouraged;
- package maintainers should determine if subdirectories of
- <tt>/usr/lib/</tt> and <tt>/usr/share/</tt> can be used
- instead (symlinks from the X11R6 directories to
- FHS-compliant locations is encouraged if the program is not
- easily configured to look elsewhere for its files).
- Packages must not provide -- or install files into -- the
- directories <tt>/usr/bin/X11/</tt>,
- <tt>/usr/include/X11/</tt>, or <tt>/usr/lib/X11/</tt>.
- Files within a package should, however, make reference to
- these directories, rather than their X11R6-named
- counterparts <tt>/usr/X11R6/bin/</tt>,
- <tt>/usr/X11R6/include/X11/</tt>, and
- <tt>/usr/X11R6/lib/X11/</tt>, if the resources being
- referred to have not been moved to FHS-compliant locations.
- </p>
+ <p>
+ Packages that provide an X server that, directly or
+ 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
+ list. In a nutshell, X servers that interface
+ directly with the display and input hardware or via
+ 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>
- <em>Programs that require the non-DFSG-compliant OSF/Motif
- library</em> should be compiled against and tested with
- LessTif (a free re-implementation of Motif) instead. If the
- maintainer judges that the program or programs do not work
- sufficiently well with LessTif to be distributed and
- supported, but do so when compiled against Motif, then two
- versions of the package should be created; one linked
- 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 upon
- non-DFSG-compliant software and thus cannot be uploaded to
- the main distribution; if the software is itself
- DFSG-compliant it may be uploaded to the contrib
- distribution. While known existing versions of OSF/Motif
- permit unlimited redistribution of 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 OSF/Motif in
- his or her possession.
+ <sect1>
+ <heading>Packages providing a terminal emulator</heading>
+
+ <p>
+ Packages that provide a terminal emulator for the X Window
+ System which meet the criteria listed below should declare
+ in their control data that they provide the virtual
+ package <tt>x-terminal-emulator</tt>. They should also
+ register themselves as an alternative for
+ <tt>/usr/bin/x-terminal-emulator</tt>, with a priority of
+ 20.
+ </p>
+
+ <p>
+ To be an <tt>x-terminal-emulator</tt>, a program must:
+ <list compact="compact">
+ <item><p>
+ Be able to emulate a DEC VT100 terminal, or a
+ compatible terminal.
+ </p></item>
+
+ <item><p>
+ 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>
+
+ <item><p>
+ 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>
+ </list>
+ </p>
+ </sect1>
+
+ <sect1>
+ <heading>Packages providing a window manager</heading>
+
+ <p>
+ Packages that provide a window manager should declare in
+ their control data that they provide the virtual package
+ <tt>x-window-manager</tt>. They should also register
+ themselves as an alternative for
+ <tt>/usr/bin/x-window-manager</tt>, with a priority
+ calculated as follows:
+ <list compact="compact">
+ <item><p>Start with a priority of 20.</p></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
+ configuration files belonging to the system or user
+ have to be edited to activate the feature); if
+ configuration files must be modified, add only 10
+ points.
+ </p>
+ </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>
+ </sect1>
+
+ <sect1>
+ <heading>Packages providing fonts</heading>
+
+ <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
+ 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
+ configuration, and that they do not corrupt files used by
+ other font packages to register information about
+ themselves.
+ <enumlist>
+ <item>
+ <p>
+ Fonts of any type supported by the X Window System
+ must be 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
+ so packaged are necessary for proper operation of
+ the package with which they are associated the font
+ package may be Recommended; if the fonts merely
+ provide an enhancement, a Suggests relationship may
+ be used. Packages must not Depend on font
+ packages.<footnote>
+ <p>
+ This is because the X server may retrieve fonts
+ from the local filesystem or over the network
+ from an X font server; the Debian package system
+ is empowered to deal only with the local
+ filesystem.
+ </p>
+ </footnote>
+ </p>
+ </item>
+
+ <item>
+ <p>
+ BDF fonts must be converted to PCF fonts with the
+ <prgn>bdftopcf</prgn> utility (available in the
+ <tt>xutils</tt> package, <tt>gzip</tt>ped, and
+ placed in a directory that corresponds to their
+ resolution:
+ <list compact="compact">
+ <item><p>
+ 100 dpi fonts must be placed in
+ <tt>/usr/X11R6/lib/X11/fonts/100dpi/</tt>.
+ </p></item>
+
+ <item><p>
+ 75 dpi fonts must be placed in
+ <tt>/usr/X11R6/lib/X11/fonts/75dpi/</tt>.
+ </p></item>
+
+ <item><p>
+ Character-cell fonts, cursor fonts, and other
+ low-resolution fonts must be placed in
+ <tt>/usr/X11R6/lib/X11/fonts/misc/</tt>.
+ </p></item>
+ </list>
+ </p>
+ </item>
+
+ <item><p>
+ Speedo fonts must be placed in
+ <tt>/usr/X11R6/lib/X11/fonts/Speedo/</tt>.
+ </p></item>
+
+ <item><p>
+ Type 1 fonts must be placed in
+ <tt>/usr/X11R6/lib/X11/fonts/Type1/</tt>. If font
+ metric files are available, they must be placed here
+ as well.
+ </p></item>
+
+ <item>
+ <p>
+ Subdirectories of <tt>/usr/X11R6/lib/X11/fonts/</tt>
+ other than those listed above must be neither
+ created nor used. (The <tt>PEX</tt>, <tt>CID</tt>,
+ and <tt>cyrillic</tt> directories are excepted for
+ 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
+ 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 <tt>misc</tt> 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
+ <tt>fonts.dir</tt>, <tt>fonts.alias</tt>, or
+ <tt>fonts.scale</tt> in a font directory:
+ <list>
+ <item><p>
+ <tt>fonts.dir</tt> files must not be provided at all.
+ </p></item>
+
+ <item>
+ <p>
+ <tt>fonts.alias</tt> and <tt>fonts.scale</tt>
+ files, if needed, should be provided in the
+ directory
+ <tt>/etc/X11/fonts/<var>fontdir</var>/<var>package</var>.<var>extension</var></tt>,
+ where <var>fontdir</var> is the name of the
+ subdirectory of
+ <tt>/usr/X11R6/lib/X11/fonts/</tt> 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
+ that provides these fonts, and
+ <var>extension</var> is either <tt>scale</tt>
+ or <tt>alias</tt>, whichever corresponds to
+ the file contents.
+ </p>
+ </item>
+ </list>
+ </p>
+ </item>
+
+ <item>
+ <p>
+ Font packages must declare a dependency on
+ <tt>xutils (>> 4.0.3)</tt> in their control
+ data.
+ </p>
+ </item>
+
+ <item>
+ <p>
+ Font packages that provide one or more
+ <tt>fonts.scale</tt> files as described above must
+ invoke <prgn>update-fonts-scale</prgn> on each
+ directory into which they installed fonts
+ <em>before</em> invoking
+ <prgn>update-fonts-dir</prgn> on that directory.
+ 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 that provide one or more
+ <tt>fonts.alias</tt> files as described above must
+ invoke <prgn>update-fonts-alias</prgn> on each
+ directory into which they installed fonts. This
+ invocation must occur in both the
+ <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>
+ </sect1>
+
+ <sect1>
+ <heading>Application defaults files</heading>
+
+ <p>
+ Application defaults files must be installed in the
+ directory <tt>/etc/X11/app-defaults/</tt> (use of a
+ localized subdirectory of <tt>/etc/X11/</tt> as described
+ in the <em>X Toolkit Intrinsics - C Language
+ Interface</em> manual is also permitted). They must be
+ registered as <tt>conffile</tt>s or handled as
+ configuration files. Packages must not provide the
+ directory <tt>/usr/X11R6/lib/X11/app-defaults/</tt>.
+ </p>
+
+ <p>
+ Customization of programs' X resources may also be
+ supported with the provision of a file with the same name
+ as that of the package placed in the
+ <tt>/etc/X11/Xresources/</tt> directory, which must
+ registered as a <tt>conffile</tt> or handled as a
+ configuration file.<footnote>
+ <p>
+ Note that this mechanism is not the same as using
+ app-defaults; app-defaults are tied to the client
+ binary on the local filesystem, whereas X resources
+ are stored in the X server and affect all connecting
+ clients.
+ </p>
+ </footnote>
+ <em>Important:</em> packages that install files into the
+ <tt>/etc/X11/Xresources/</tt> directory must conflict with
+ <tt>xbase (<< 3.3.2.3a-2)</tt>; if this is not done
+ it is possible for the installing package to destroy a
+ previously-existing <tt>/etc/X11/Xresources</tt> file
+ which had been customized by the system administrator.
+ </p>
+ </sect1>
+
+ <sect1>
+ <heading>Installation directory issues</heading>
+
+ <p>
+ Packages using the X Window System should not be
+ configured to install files under the <tt>/usr/X11R6/</tt>
+ directory unless they use <prgn>imake</prgn>. The
+ <tt>/usr/X11R6/</tt> directory hierarchy should be
+ regarded as deprecated for all packages except the X
+ Window System itself, and those which use the
+ <prgn>imake</prgn> program it provides, in which case the
+ packages may transition out of the <tt>/usr/X11R6/</tt>
+ 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 <tt>/usr/X11R7/</tt>,
+ <tt>/usr/X12/</tt>, or just plain <tt>/usr/</tt>, all
+ that is required for these programs is a recompile
+ against the corresponding X Window System library
+ development packages.
+ </p>
+ </footnote>
+ Programs that use GNU <prgn>autoconf</prgn> and
+ <prgn>automake</prgn> are usually easily configured at
+ compile time to use <tt>/usr/</tt> instead of
+ <tt>/usr/X11R6/</tt>, and this should be done whenever
+ possible. Configuration files for window managers and
+ display managers should be placed in a subdirectory of
+ <tt>/etc/X11/</tt> corresponding to the package name due
+ to these programs' tight integration with the mechanisms
+ of the X Window System. Application-level programs should
+ use the <tt>/etc/</tt> directory unless otherwise mandated
+ by policy. The installation of files into subdirectories
+ of <tt>/usr/X11R6/include/X11/</tt> and
+ <tt>/usr/X11R6/lib/X11/</tt> is permitted but discouraged;
+ package maintainers should determine if subdirectories of
+ <tt>/usr/lib/</tt> and <tt>/usr/share/</tt> can be used
+ instead. (The use of symbolic links from the
+ <tt>X11R6</tt> directories to other FHS-compliant
+ locations is encouraged if the program is not easily
+ configured to look elsewhere for its files.) Packages
+ must not provide or install files into the directories
+ <tt>/usr/bin/X11/</tt>, <tt>/usr/include/X11/</tt> or
+ <tt>/usr/lib/X11/</tt>. Files within a package should,
+ however, make reference to these directories, rather than
+ their <tt>X11R6</tt>-named counterparts
+ <tt>/usr/X11R6/bin/</tt>, <tt>/usr/X11R6/include/X11/</tt>
+ and <tt>/usr/X11R6/lib/X11/</tt>, if the resources being
+ referred to have not been moved to other FHS-compliant
+ locations.
+ </p>
+ </sect1>
+
+ <sect1>
+ <heading>The OSF/Motif and OpenMotif libraries</heading>
+
+ <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
+ judges that the program or programs do not work
+ sufficiently well with LessTif to be distributed and
+ supported, but do so when compiled against Motif, then two
+ versions of the package should be created; one linked
+ 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
+ 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
+ the <em>contrib</em> distribution. While known existing
+ versions of Motif permit unlimited redistribution of
+ 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.
+ </p>
+ </sect1>
+ </sect>
+
+ <sect>
+ <heading>Perl programs and modules</heading>
+ <p>
+ Perl programs and modules should follow the current Perl
+ policy as defined in the file found on
+ <ftpsite>ftp.debian.org</ftpsite> in
+ <ftppath>/debian/doc/package-developer/perl-policy.txt.gz</ftppath>
+ or your local mirror. In addition, it is included in the
+ <tt>debian-policy</tt> package.
</p>
</sect>
-
-
+
<sect>
<heading>Emacs lisp programs</heading>
-
+
<p>
Please refer to the `Debian Emacs Policy' (documented in
<tt>debian-emacs-policy.gz</tt> of the
<prgn>emacsen-common</prgn> package) for details of how to
- package emacs lisp programs.</p></sect>
-
-
+ package emacs lisp programs.
+ </p>
+ </sect>
+
<sect>
<heading>Games</heading>
-
+
<p>
- The permissions on /var/games are 755
- <tt>root.root</tt>.</p>
-
+ The permissions on <tt>/var/games</tt> 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
important game data, and if they can get at the other
players' accounts at all it will take considerably more
effort.)</p>
-
+
<p>
Some packages, for example some fortune cookie programs, are
configured by the upstream authors to install with their
making the files unreadable also means that you don't have
to make so many programs set-id, which reduces the risk of a
security hole.</p>
-
+
<p>
As described in the FHS, binaries of games should be
installed in the directory <tt>/usr/games</tt>. This also
<tt>/usr/share/man/man6</tt>.</p>
</sect>
</chapt>
-
- <chapt><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 <tt>/usr/share/man</tt>. You
should only use sections 1 to 9 (see the FHS for more
details). You must not install a preformatted `cat
page'.</p>
-
+
<p>
Each program, utility, and function should have an
associated manpage included in the same package. It is
suggested that all configuration files also have a manual
page included as well.
</p>
-
+
<p>
If no manual page is available for a particular program,
- utility, function or configuration file and this is reported as a bug on
- debian-bugs, a symbolic link from the requested manual page
- to the <manref name="undocumented" section="7"> manual page
- may be provided. This symbolic link can be created from
+ 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
<tt>debian/rules</tt> like this:
- <example>
- ln -s ../man7/undocumented.7.gz \
- debian/tmp/usr/share/man/man[1-9]/the_requested_manpage.[1-9].gz
- </example>
+ <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>
-
+
<p>
You may forward a complaint about a missing manpage 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,
- we do--if they tell you that they don't consider it a bug
+ we do; if they tell you that they don't consider it a bug
you should leave the bug in our bug tracking system open
anyway.</p>
-
+
<p>
Manual pages should be installed compressed using <tt>gzip
-9</tt>.</p>
-
+
<p>
If one manpage needs to be accessible via several names it
is better to use a symbolic link than the <tt>.so</tt>
feature, but there is no need to fiddle with the relevant
parts of the upstream source to change from <tt>.so</tt> to
- symlinks--don't do it unless it's easy. You should not create hard
- links in the manual page directories, nor put
+ symlinks: don't do it unless it's easy. You should not
+ create hard links in the manual page directories, nor put
absolute filenames in <tt>.so</tt> directives. The filename
in a <tt>.so</tt> in a manpage should be relative to the
base of the manpage tree (usually
- <tt>/usr/share/man</tt>).</p></sect>
-
-
+ <tt>/usr/share/man</tt>). If you do not create any links
+ (whether symlinks, hard links, or <tt>.so</tt> directives)
+ in the filesystem to the alternate names of the manpage,
+ then you should not rely on <prgn>man</prgn> finding your
+ manpage under those names based solely on the information in
+ the manpage's header.<footnote>
+ <p>
+ Supporting this in <prgn>man</prgn> often requires
+ unreasonable processing time to find a manual page or to
+ report that none exists, and moves knowledge into man's
+ database that would be better left in the filesystem.
+ This support is therefore deprecated and will cease to
+ be present in the future.
+ </p>
+ </footnote>
+ </p>
+ </sect>
+
<sect>
<heading>Info documents</heading>
-
+
<p>
Info documents should be installed in <tt>/usr/share/info</tt>.
They should be compressed with <tt>gzip -9</tt>.</p>
-
+
<p>
- Your package should call <prgn>install-info</prgn> to update the Info
- <tt>dir</tt>
- file, in its post-installation script:
- <example>
- install-info --quiet --section Development Development \
- /usr/share/info/foobar.info
+ Your package should call <prgn>install-info</prgn> to update
+ the Info <tt>dir</tt> file in its <prgn>postinst</prgn>
+ script when called with a <tt>configure</tt> argument, for
+ example:
+ <example compact="compact">
+install-info --quiet --section Development Development \
+ /usr/share/info/foobar.info
</example></p>
-
+
<p>
It is a good idea to specify a section for the location of
your program; this is done with the <tt>--section</tt>
flag takes two arguments; the first is a regular expression
to match (case-insensitively) against an existing section,
the second is used when creating a new one.</p>
-
+
<p>
- You should remove the entries in the pre-removal script:
- <example>
- install-info --quiet --remove /usr/share/info/foobar.info
+ You should remove the entries in the <prgn>prerm</prgn>
+ script when called with a <tt>remove</tt> argument:
+ <example compact="compact">
+install-info --quiet --remove /usr/share/info/foobar.info
</example></p>
-
+
<p>
If <prgn>install-info</prgn> cannot find a description entry
in the Info file you must supply one. See <manref
- name="install-info" section="8"> for details.</p>
+ name="install-info" section="8"> for details.</p>
</sect>
-
+
<sect>
<heading>Additional documentation</heading>
-
+
<p>
Any additional documentation that comes with the package may
be installed at the discretion of the package maintainer.
- Text documentation should be installed in a directory
+ Text documentation should be installed in the directory
<tt>/usr/share/doc/<var>package</var></tt>, where
<var>package</var> is the name of the package, and
compressed with <tt>gzip -9</tt> unless it is small.</p>
-
+
<p>
If a package comes with large amounts of documentation which
many users of the package will not require you should create
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
(<tt>README</tt>s, changelogs, and so forth) that come with
delete them without causing any programs to break. Any files
that are referenced by programs but are also useful as
standalone documentation should be installed under
- <tt>/usr/share/<package$gt;/</tt> and symlinked in
- <tt>/usr/share/doc/<package$gt;/</tt>.
+ <tt>/usr/share/<var>package</var>/</tt> with symbolic links
+ from <tt>/usr/share/doc/<var>package</var>/</tt>.
</p>
</sect>
-
+
<sect id="usrdoc">
<heading>Accessing the documentation</heading>
it cannot be contained in the package itself due to problems
with <prgn>dpkg</prgn>. One reasonable way to accomplish
this is to put the following in the package's
- <prgn>postinst</prgn>:
- <example>
- if [ "$1" = "configure" ]; then
- if [ -d /usr/doc -a ! -e /usr/doc/#PACKAGE# \
- -a -d /usr/share/doc/#PACKAGE# ]; then
- ln -sf ../share/doc/#PACKAGE# /usr/doc/#PACKAGE#
- fi
- fi
+ <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>
- if [ \( "$1" = "upgrade" -o "$1" = "remove" \) \
- -a -L /usr/doc/#PACKAGE# ]; then
- rm -f /usr/doc/#PACKAGE#
- fi
+
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
- mark up format that can be converted to various other formats
+ markup format that can be converted to various other formats
you should if possible ship HTML versions in a binary
package, in the directory
- <tt>/usr/share/doc/<var>appropriate package</var></tt> or its
- subdirectories.
- <footnote>
- <p>The rationale: The important thing here is that HTML
+ <tt>/usr/share/doc/<var>appropriate-package</var></tt> or
+ its subdirectories.<footnote>
+ <p>
+ The rationale: The important thing here is that HTML
docs should be available in <em>some</em> package, not
- necessarily in the main binary package, though. </p>
+ necessarily in the main binary package.
+ </p>
</footnote>
</p>
-
+
<p>
- Other formats such as PostScript may be provided at your
- option.</p>
+ Other formats such as PostScript may be provided at the
+ package maintainer's discretion.
+ </p>
</sect>
-
+
<sect id="copyrightfile">
<heading>Copyright information</heading>
-
+
<p>
Every package must be accompanied by a verbatim copy of its
copyright and distribution license in the file
- /usr/share/doc/<package-name>/copyright. This file must
- neither be compressed nor be a symbolic link.</p>
-
+ <tt>/usr/share/doc/<var>package</var>/copyright</tt>. 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
<p>
A copy of the file which will be installed in
- <tt>/usr/share/doc/<var>package</var>/copyright</tt> should be
- in <tt>debian/copyright</tt>.</p>
-
-
+ <tt>/usr/share/doc/<var>package</var>/copyright</tt> should
+ be in <tt>debian/copyright</tt> in the source package.
+ </p>
+
<p>
- /usr/share/doc/<package-name> may be a symbolic link to a
- directory in /usr/share/doc only if two packages both come from
- the same source and the first package has a "Depends"
- relationship on the second. These rules are important
- because copyrights must be extractable by mechanical
- means.</p>
+ <tt>/usr/share/doc/<var>package</var></tt> may be a symbolic
+ link to another directory in <tt>/usr/share/doc</tt> only if
+ the two packages both come from the same source and the
+ first package Depends on the second. These rules are
+ important because copyrights must be extractable by
+ mechanical means.
+ </p>
<p>
Packages distributed under the UCB BSD license, the Artistic
license, the GNU GPL, and the GNU LGPL should refer to the
- files /usr/share/common-licenses/BSD,
- /usr/share/common-licenses/Artistic,
- /usr/share/common-licenses/GPL, and
- /usr/share/common-licenses/LGPL.
- <footnote>
- <p>
- Why "licenses" and not "copyright"? Because
- <tt>/usr/doc/copyright</tt> used to contain all the
- copyright files, plus the four common licenses GPL,
- LGPL, Artistic and BSD. Now individual copyright files
- for packages are no longer in a common directory. Once
- <tt>/usr/doc/copyright</tt> is almost empty it makes
- sense to rename "copyright" to "licenses"
- </p>
- <p>
- Why "common-licenses" and not "licenses"? Because if I
- put just "licenses" I'm sure I will receive a bug report
- saying "license foo is not included in the licenses
- directory. They are not all the licenses, just a few
- common ones. I could use /usr/share/doc/common-licenses
- but I think this is too long, and, after all, the GPL
- does not "document" anything, it is merely a license.
- </p>
- </footnote>
+ files <tt>/usr/share/common-licenses/BSD</tt>,
+ <tt>/usr/share/common-licenses/Artistic</tt>,
+ <tt>/usr/share/common-licenses/GPL</tt>, and
+ <tt>/usr/share/common-licenses/LGPL</tt> respectively,
+ rather than quoting them in the copyright file.
</p>
-
+
<p>
You should not use the copyright file as a general <tt>README</tt>
file. If your package has such a file it should be
installed in <tt>/usr/share/doc/<var>package</var>/README</tt> or
<tt>README.Debian</tt> or some other appropriate place.</p>
</sect>
-
+
<sect>
<heading>Examples</heading>
-
+
<p>
Any examples (configurations, source files, whatever),
should be installed in a directory
<tt>/usr/share/doc/<var>package</var>/examples</tt>. 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
+ 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
- <tt>/usr/lib/<var>package</var>/examples</tt>, and files in
- <tt>/usr/share/doc/<var>package</var>/examples</tt> symlink
- to files in it. Or the latter directory may be a symlink to
- the former.</p>
+ <tt>/usr/lib/<var>package</var>/examples</tt> with symbolic
+ links to them from
+ <tt>/usr/share/doc/<var>package</var>/examples</tt>, 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 copy of
- <tt>debian/changelog</tt> file from the Debian source tree
- in <tt>/usr/share/doc/<var>package</var></tt> as
- <tt>changelog.Debian.gz</tt>. If an upstream changelog is
+ Packages that are not Debian-native must contain a
+ compressed copy of the <tt>debian/changelog</tt> file from
+ the Debian source tree in
+ <tt>/usr/share/doc/<var>package</var></tt> with the name
+ <tt>changelog.Debian.gz</tt>. If an upstream changelog is
available, it should be accessible as
<tt>/usr/share/doc/<var>package</var>/changelog.gz</tt> in
- plain text. If the upstream changelog is distributed in
+ plain text. If the upstream changelog is distributed in
HTML, it should be made available in that form as
<tt>/usr/share/doc/<var>package</var>/changelog.html.gz</tt>
- and the <tt>changelog.gz</tt> should be generated using, eg,
- <tt>lynx -dump -nolist</tt>. If the upstream changelog files
- do not already conform to this naming convention, then this
- may be achieved either by renaming the files, or adding a
- symbolic link, at the maintainer's discretion.
- <footnote>
+ and a plain text <tt>changelog.gz</tt> should be generated
+ from it using, for example, <tt>lynx -dump -nolist</tt>. If
+ the upstream changelog files do not already conform to this
+ naming convention, then this may be achieved either by
+ renaming the files, or by adding a symbolic link, at the
+ maintainer's discretion.<footnote>
<p>
- Rationale: People should not have to look into two
- places for upstream changelogs merely because they are
- in HTML format.
+ Rationale: People should not have to look in places for
+ upstream changelogs merely because they are given
+ different names or are distributed in HTML format.
</p>
</footnote>
</p>
-
-
+
<p>
- All these files should be installed compressed using <tt>gzip -9</tt>,
- as they will become large with time even if they start out
- small.
+ All of these files should be installed compressed using
+ <tt>gzip -9</tt>, as they will become large with time even
+ if they start out small.
</p>
-
+
<p>
If the package has only one changelog which is used both as
the Debian changelog and the upstream one because there is
changelog, then the Debian changelog should still be called
<tt>changelog.Debian.gz</tt>.</p>
</sect>
- </chapt>
- </book>
-</debiandoc>
+ </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 (<tt>.deb</tt> 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
+ <tt>deb(5)</tt> manpage.
+ </p>
+
+
+ <sect id="pkg-bincreating"><heading>Creating package files -
+ <prgn>dpkg-deb</prgn>
+ </heading>
+
+ <p>
+ All manipulation of binary package files is done by
+ <prgn>dpkg-deb</prgn>; it's the only program that has
+ knowledge of the format. (<prgn>dpkg-deb</prgn> may be
+ invoked by calling <prgn>dpkg</prgn>, as <prgn>dpkg</prgn>
+ will spot that the options requested are appropriate to
+ <prgn>dpkg-deb</prgn> and invoke that instead with the same
+ arguments.)
+ </p>
+
+ <p>
+ In order to create a binary package you must make a
+ directory tree which contains all the files and directories
+ you want to have in the filesystem data part of the package.
+ In Debian-format source packages this directory is usually
+ <tt>debian/tmp</tt>, relative to the top of the package's
+ source tree.
+ </p>
+
+ <p>
+ They should have the locations (relative to the root of the
+ directory tree you're constructing) ownerships and
+ permissions which you want them to have on the system when
+ they are installed.
+ </p>
+
+ <p>
+ With current versions of <prgn>dpkg</prgn> the uid/username
+ and gid/groupname mappings for the users and groups being
+ used should be the same on the system where the package is
+ built and the one where it is installed.
+ </p>
+
+ <p>
+ You need to add one special directory to the root of the
+ miniature filesystem tree you're creating:
+ <prgn>DEBIAN</prgn>. It should contain the control
+ information files, notably the binary package control file
+ (see <ref id="pkg-controlfile">).
+ </p>
+
+ <p>
+ The <prgn>DEBIAN</prgn> directory will not appear in the
+ filesystem archive of the package, and so won't be installed
+ by <prgn>dpkg</prgn> when the package is installed.
+ </p>
+
+ <p>
+ When you've prepared the package, you should invoke:
+ <example>
+ dpkg --build <var>directory</var>
+ </example>
+ </p>
+
+ <p>
+ This will build the package in
+ <tt><var>directory</var>.deb</tt>. (<prgn>dpkg</prgn> knows
+ that <tt>--build</tt> is a <prgn>dpkg-deb</prgn> option, so
+ it invokes <prgn>dpkg-deb</prgn> with the same arguments to
+ build the package.)
+ </p>
+
+ <p>
+ See the manpage <manref name="dpkg-deb" section="8"> for details of how
+ to examine the contents of this newly-created file. You may find the
+ output of following commands enlightening:
+ <example>
+ dpkg-deb --info <var>filename</var>.deb
+ dpkg-deb --contents <var>filename</var>.deb
+ dpkg --contents <var>filename</var>.deb
+ </example>
+ To view the copyright file for a package you could use this command:
+ <example>
+ dpkg --fsys-tarfile <var>filename</var>.deb | tar xof usr/share/doc/<var>\*</var>copyright | less
+ </example>
+ </p>
+ </sect>
+
+ <sect id="pkg-controlarea">
+ <heading>
+ Package control information files
+ </heading>
+
+ <p>
+ The control information portion of a binary package is a
+ collection of files with names known to <prgn>dpkg</prgn>.
+ It will treat the contents of these files specially - some
+ of them contain information used by <prgn>dpkg</prgn> when
+ installing or removing the package; others are scripts which
+ the package maintainer wants <prgn>dpkg</prgn> to run.
+ </p>
+
+ <p>
+ It is possible to put other files in the package control
+ area, but this is not generally a good idea (though they
+ will largely be ignored).
+ </p>
+
+ <p>
+ Here is a brief list of the control info files supported by
+ <prgn>dpkg</prgn> and a summary of what they're used for.
+ </p>
+
+ <p>
+ <taglist>
+ <tag><tt>control</tt>
+ <item>
+
+ <p>
+ This is the key description file used by
+ <prgn>dpkg</prgn>. It specifies the package's name
+ and version, gives its description for the user,
+ states its relationships with other packages, and so
+ forth. See <ref id="pkg-controlfile">.
+ </p>
+
+ <p>
+ It is usually generated automatically from information
+ in the source package by the
+ <prgn>dpkg-gencontrol</prgn> program, and with
+ assistance from <prgn>dpkg-shlibdeps</prgn>. See <ref
+ id="pkg-sourcetools">.</p>
+ </item>
+
+ <tag><tt>postinst</tt>, <tt>preinst</tt>, <tt>postrm</tt>,
+ <tt>prerm</tt>
+ </tag>
+ <item>
+
+ <p>
+ These are exectuable files (usually scripts) which
+ <prgn>dpkg</prgn> runs during installation, upgrade
+ and removal of packages. They allow the package to
+ deal with matters which are particular to that package
+ or require more complicated processing than that
+ provided by <prgn>dpkg</prgn>. Details of when and
+ how they are called are in <ref
+ id="maintainerscripts">.
+ </p>
+
+ <p>
+ It is very important to make these scripts
+ idempotent.
+ <footnote>
+ <p>
+ That means that if it runs successfully or fails
+ and then you call it again it doesn't bomb out,
+ but just ensures that everything is the way it
+ ought to be.
+ </p>
+ </footnote> This is so that if an error occurs, the
+ user interrupts <prgn>dpkg</prgn> or some other
+ unforeseen circumstance happens you don't leave the
+ user with a badly-broken package.
+ </p>
+
+ <p>
+ The maintainer scripts are guaranteed to run with a
+ controlling terminal and can interact with the user.
+ If they need to prompt for passwords, do full-screen
+ interaction or something similar you should do these
+ things to and from <tt>/dev/tty</tt>, since
+ <prgn>dpkg</prgn> will at some point redirect scripts'
+ standard input and output so that it can log the
+ installation process. Likewise, because these scripts
+ may be executed with standard output redirected into a
+ pipe for logging purposes, Perl scripts should set
+ unbuffered output by setting <tt>$|=1</tt> so that the
+ output is printed immediately rather than being
+ buffered.
+ </p>
+
+ <p>
+ Each script should return a zero exit status for
+ success, or a nonzero one for failure.</p>
+ </item>
+
+ <tag><tt>conffiles</tt>
+ </tag>
+ <item>
+
+ <p>
+ This file contains a list of configuration files which
+ are to be handled automatically by <prgn>dpkg</prgn>
+ (see <ref id="pkg-conffiles">). Note that not necessarily
+ every configuration file should be listed here.</p>
+ </item>
+
+ <tag><tt>shlibs</tt>
+ </tag>
+ <item>
+
+ <p>
+ This file contains a list of the shared libraries
+ supplied by the package, with dependency details for
+ each. This is used by <prgn>dpkg-shlibdeps</prgn>
+ when it determines what dependencies are required in a
+ package control file. The <tt>shlibs</tt> file format
+ is described on <ref id="shlibs">.
+ </p>
+ </item>
+ </taglist>
+ </p>
+
+ <sect id="pkg-controlfile">
+ <heading>
+ The main control information file: <tt>control</tt>
+ </heading>
+ <p>
+ The most important control information file used by
+ <prgn>dpkg</prgn> when it installs a package is
+ <tt>control</tt>. It contains all the package's `vital
+ statistics'.
+ </p>
+
+ <p>
+ The binary package control files of packages built from
+ Debian sources are made by a special tool,
+ <prgn>dpkg-gencontrol</prgn>, which reads
+ <tt>debian/control</tt> and <tt>debian/changelog</tt> to
+ find the information it needs. See <ref id="pkg-sourcepkg"> for
+ more details.
+ </p>
+
+ <p>
+ The fields in binary package control files are:
+ <list compact="compact">
+ <item>
+ <p><qref id="pkg-f-Package"><tt>Package</tt></qref> (mandatory)</p>
+ </item>
+ <item>
+ <p><qref id="versions"><tt>Version</tt></qref> (mandatory)</p>
+ </item>
+ <item><p><qref id="pkg-f-Architecture"><tt>Architecture</tt></qref>
+ (mandatory)
+ <footnote>
+ <p>
+ This field should appear in all packages, though
+ <prgn>dpkg</prgn> doesn't require it yet so that
+ old packages can still be installed.
+ </p>
+ </footnote>
+ </p>
+ </item>
+ <item>
+ <p><qref id="relationships"><tt>Depends</tt>,
+ <tt>Provides</tt> et al.</qref></p>
+ </item>
+ <item>
+ <p><qref id="pkg-f-Essential"><tt>Essential</tt></qref></p>
+ </item>
+ <item>
+ <p><qref id="pkg-f-Maintainer"><tt>Maintainer</tt></qref></p>
+ </item>
+ <item>
+ <p><qref id="pkg-f-classification"><tt>Section</tt>,
+ <tt>Priority</tt></qref></p>
+ </item>
+ <item>
+ <p><qref id="pkg-f-Source"><tt>Source</tt></qref></p>
+ </item>
+ <item>
+ <p><qref id="descriptions"><tt>Description</tt></qref></p>
+ </item>
+ <item>
+ <p>
+ <qref id="pkg-f-Installed-Size"><tt>Installed-Size</tt></qref>
+ </p>
+ </item>
+ </list>
+
+ <p>
+ A description of the syntax of control files and the purpose
+ of these fields is available in <ref id="pkg-controlfields">.
+ </p>
+ </sect>
+
+ <sect>
+ <heading>Time Stamps</heading>
+ <p>
+ Maintainers are encouraged to preserve the modification
+ times of the upstream source files in a package, as far as
+ is reasonably possible.
+ <footnote>
+ <p>
+ The rationale is that there is some information conveyed
+ by knowing the age of the file, for example, you could
+ recognize that some documentation is very old by looking
+ at the modification time, so it would be nice if the
+ modification time of the upstream source would be
+ preserved.
+ </p>
+ </footnote>
+ </p>
+ </sect>
+ </appendix>
+ <appendix id="pkg-sourcepkg">
+ <heading>Source packages (from old Packaging Manual) </heading>
+ <p>
+ The Debian binary packages in the distribution are generated
+ from Debian sources, which are in a special format to assist
+ the easy and automatic building of binaries.
+ </p>
+ <p>
+ There was a previous version of the Debian source format,
+ which is now being phased out. Instructions for converting an
+ old-style package are given in the Debian policy manual.
+ </p>
+
+ <sect id="pkg-sourcetools">
+ <heading>Tools for processing source packages</heading>
+ <p>
+ Various tools are provided for manipulating source packages;
+ they pack and unpack sources and help build of binary
+ packages and help manage the distribution of new versions.
+ </p>
+ <p>
+ They are introduced and typical uses described here; see
+ <manref name="dpkg-source" section="1"> for full
+ documentation about their arguments and operation.
+ </p>
+ <p>
+ For examples of how to construct a Debian source package,
+ and how to use those utilities that are used by Debian
+ source packages, please see the <prgn>hello</prgn> example
+ package.
+ </p>
+
+ <sect1>
+ <heading>
+ <prgn>dpkg-source</prgn> - packs and unpacks Debian source
+ packages
+ </heading>
+
+ <p>
+ This program is frequently used by hand, and is also
+ called from package-independent automated building scripts
+ such as <prgn>dpkg-buildpackage</prgn>.
+ </p>
+
+ <p>
+ To unpack a package it is typically invoked with
+ <example>
+ dpkg-source -x <var>.../path/to/filename</var>.dsc
+ </example>
+ </p>
+
+ <p>
+ with the <tt><var>filename</var>.tar.gz</tt> and
+ <tt><var>filename</var>.diff.gz</tt> (if applicable) in
+ the same directory. It unpacks into
+ <tt><var>package</var>-<var>version</var></tt>, and if
+ applicable
+ <tt><var>package</var>-<var>version</var>.orig</tt>, in
+ the current directory.
+ </p>
+
+ <p>
+ To create a packed source archive it is typically invoked:
+ <example>
+ dpkg-source -b <var>package</var>-<var>version</var>
+ </example>
+ </p>
+
+ <p>
+ This will create the <tt>.dsc</tt>, <tt>.tar.gz</tt> and
+ <tt>.diff.gz</tt> (if appropriate) in the current
+ directory. <prgn>dpkg-source</prgn> does not clean the
+ source tree first - this must be done separately if it is
+ required.
+ </p>
+
+ <p>
+ See also <ref id="pkg-sourcearchives">.</p>
+ </sect1>
+
+
+ <sect1>
+ <heading>
+ <prgn>dpkg-buildpackage</prgn> - overall package-building
+ control script
+ </heading>
+
+ <p>
+ <prgn>dpkg-buildpackage</prgn> is a script which invokes
+ <prgn>dpkg-source</prgn>, the <tt>debian/rules</tt>
+ targets <tt>clean</tt>, <tt>build</tt> and
+ <tt>binary</tt>, <prgn>dpkg-genchanges</prgn> and
+ <prgn>pgp</prgn> to build a signed source and binary
+ package upload.
+ </p>
+
+ <p>
+ It is usually invoked by hand from the top level of the
+ built or unbuilt source directory. It may be invoked with
+ no arguments; useful arguments include:
+ <taglist compact="compact">
+ <tag><tt>-uc</tt>, <tt>-us</tt></tag>
+ <item>
+ <p>
+ Do not PGP-sign the <tt>.changes</tt> file or the
+ source package <tt>.dsc</tt> file, respectively.</p>
+ </item>
+ <tag><tt>-p<var>pgp-command</var></tt></tag>
+ <item>
+ <p>
+ Invoke <var>pgp-command</var> instead of finding
+ <tt>pgp</tt> on the <prgn>PATH</prgn>.
+ <var>pgp-command</var> must behave just like
+ <prgn>pgp</prgn>.</p>
+ </item>
+ <tag><tt>-r<var>root-command</var></tt></tag>
+ <item>
+ <p>
+ When root privilege is required, invoke the command
+ <var>root-command</var>. <var>root-command</var>
+ should invoke its first argument as a command, from
+ the <prgn>PATH</prgn> if necessary, and pass its
+ second and subsequent arguments to the command it
+ calls. If no <var>root-command</var> is supplied
+ then <var>dpkg-buildpackage</var> will take no
+ special action to gain root privilege, so that for
+ most packages it will have to be invoked as root to
+ start with.</p>
+ </item>
+ <tag><tt>-b</tt>, <tt>-B</tt></tag>
+ <item>
+ <p>
+ Two types of binary-only build and upload - see
+ <manref name="dpkg-source" section="1">.
+ </p>
+ </item>
+ </taglist>
+ </p>
+ </sect1>
+
+ <sect1>
+ <heading>
+ <prgn>dpkg-gencontrol</prgn> - generates binary package
+ control files
+ </heading>
+
+ <p>
+ This program is usually called from <tt>debian/rules</tt>
+ (see <ref id="pkg-sourcetree">) in the top level of the source
+ tree.
+ </p>
+
+ <p>
+ This is usually done just before the files and directories in the
+ temporary directory tree where the package is being built have their
+ permissions and ownerships set and the package is constructed using
+ <prgn>dpkg-deb/</prgn>
+ <footnote>
+ <p>
+ This is so that the control file which is produced has
+ the right permissions
+ </p>
+ </footnote>.
+ </p>
+
+ <p>
+ <prgn>dpkg-gencontrol</prgn> must be called after all the
+ files which are to go into the package have been placed in
+ the temporary build directory, so that its calculation of
+ the installed size of a package is correct.
+ </p>
+
+ <p>
+ It is also necessary for <prgn>dpkg-gencontrol</prgn> to
+ be run after <prgn>dpkg-shlibdeps</prgn> so that the
+ variable substitutions created by
+ <prgn>dpkg-shlibdeps</prgn> in <tt>debian/substvars</tt>
+ are available.
+ </p>
+
+ <p>
+ For a package which generates only one binary package, and
+ which builds it in <tt>debian/tmp</tt> relative to the top
+ of the source package, it is usually sufficient to call
+ <prgn>dpkg-gencontrol</prgn>.
+ </p>
+
+ <p>
+ Sources which build several binaries will typically need
+ something like:
+ <example>
+ dpkg-gencontrol -Pdebian/tmp-<var>pkg</var> -p<var>package</var>
+ </example> The <tt>-P</tt> tells
+ <prgn>dpkg-gencontrol</prgn> that the package is being
+ built in a non-default directory, and the <tt>-p</tt>
+ tells it which package's control file should be generated.
+ </p>
+
+ <p>
+ <prgn>dpkg-gencontrol</prgn> also adds information to the
+ list of files in <tt>debian/files</tt>, for the benefit of
+ (for example) a future invocation of
+ <prgn>dpkg-genchanges</prgn>.</p>
+ </sect1>
+
+ <sect1>
+ <heading>
+ <prgn>dpkg-shlibdeps</prgn> - calculates shared library
+ dependencies
+ </heading>
+
+ <p>
+ This program is usually called from <tt>debian/rules</tt>
+ just before <prgn>dpkg-gencontrol</prgn> (see <ref
+ id="pkg-sourcetree">), in the top level of the source tree.
+ </p>
+
+ <p>
+ Its arguments are executables.
+ <footnote>
+ <p>
+ In a forthcoming dpkg version,
+ <prgn>dpkg-shlibdeps</prgn> would be required to be
+ called on shared libraries as well.
+ </p>
+ <p>
+ They may be specified either in the locations in the
+ source tree where they are created or in the locations
+ in the temporary build tree where they are installed
+ prior to binary package creation.
+ </p>
+ </footnote> for which shared library dependencies should
+ be included in the binary package's control file.
+ </p>
+
+ <p>
+ If some of the found shared libraries should only
+ warrant a <tt>Recommends</tt> or <tt>Suggests</tt>, or if
+ some warrant a <tt>Pre-Depends</tt>, this can be achieved
+ by using the <tt>-d<var>dependency-field</var></tt> option
+ before those executable(s). (Each <tt>-d</tt> option
+ takes effect until the next <tt>-d</tt>.)
+ </p>
+
+ <p>
+ <prgn>dpkg-shlibdeps</prgn> does not directly cause the
+ output control file to be modified. Instead by default it
+ adds to the <tt>debian/substvars</tt> file variable
+ settings like <tt>shlibs:Depends</tt>. These variable
+ settings must be referenced in dependency fields in the
+ appropriate per-binary-package sections of the source
+ control file.
+ </p>
+
+ <p>
+ For example, the <prgn>procps</prgn> package generates two
+ kinds of binaries, simple C binaries like <prgn>ps</prgn>
+ which require a predependency and full-screen ncurses
+ binaries like <prgn>top</prgn> which require only a
+ recommendation. It can say in its <tt>debian/rules</tt>:
+ <example>
+ dpkg-shlibdeps -dPre-Depends ps -dRecommends top
+ </example>
+ and then in its main control file <tt>debian/control</tt>:
+ <example>
+ <var>...</var>
+ Package: procps
+ Pre-Depends: ${shlibs:Pre-Depends}
+ Recommends: ${shlibs:Recommends}
+ <var>...</var>
+ </example>
+ </p>
+
+ <p>
+ Sources which produce several binary packages with
+ different shared library dependency requirements can use
+ the <tt>-p<var>varnameprefix</var></tt> option to override
+ the default <tt>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
+ <tt>debian/files</tt>
+ </heading>
+
+ <p>
+ Some packages' uploads need to include files other than
+ the source and binary package files.
+ </p>
+
+ <p>
+ <prgn>dpkg-distaddfile</prgn> adds a file to the
+ <tt>debian/files</tt> file so that it will be included in
+ the <tt>.changes</tt> file when
+ <prgn>dpkg-genchanges</prgn> is run.
+ </p>
+
+ <p>
+ It is usually invoked from the <tt>binary</tt> target of
+ <tt>debian/rules</tt>:
+ <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 <tt>debian/rules</tt> target should put the
+ file there just before or just after calling
+ <prgn>dpkg-distaddfile</prgn>.
+ </p>
+
+ <p>
+ The <var>section</var> and <var>priority</var> are passed
+ unchanged into the resulting <tt>.changes</tt> file. See
+ <ref id="pkg-f-classification">.
+ </p>
+ </sect1>
+
+
+ <sect1><heading><prgn>dpkg-genchanges</prgn> - generates a <tt>.changes</tt> upload
+ control file
+ </heading>
+
+ <p>
+ This program is usually called by package-independent
+ automatic building scripts such as
+ <prgn>dpkg-buildpackage</prgn>, but it may also be called
+ by hand.
+ </p>
+
+ <p>
+ It is usually called in the top level of a built source
+ tree, and when invoked with no arguments will print out a
+ straightforward <tt>.changes</tt> file based on the
+ information in the source package's changelog and control
+ file and the binary and source packages which should have
+ been built.
+ </p>
+ </sect1>
+
+
+ <sect1><heading><prgn>dpkg-parsechangelog</prgn> - produces parsed representation of
+ a changelog
+ </heading>
+
+ <p>
+ This program is used internally by
+ <prgn>dpkg-source</prgn> et al. It may also occasionally
+ be useful in <tt>debian/rules</tt> and elsewhere. It
+ parses a changelog, <tt>debian/changelog</tt> 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 <tt>debian/rules</tt> to set
+ to set environment or make variables which specify the build and
+ host architecture for the package building process.
+ </p>
+ </sect1>
+ </sect>
+
+ <sect id="pkg-sourcetree"><heading>The Debianised source tree
+ </heading>
+
+ <p>
+ The source archive scheme described later is intended to
+ allow a Debianised source tree with some associated control
+ information to be reproduced and transported easily. The
+ Debianised source tree is a version of the original program
+ with certain files added for the benefit of the
+ Debianisation process, and with any other changes required
+ made to the rest of the source code and installation
+ scripts.
+ </p>
+
+ <p>
+ The extra files created for Debian are in the subdirectory
+ <tt>debian</tt> of the top level of the Debianised source
+ tree. They are described below.
+ </p>
+
+ <sect1 id="pkg-debianrules"><heading><tt>debian/rules</tt> - the main building
+ script
+ </heading>
+
+ <p>
+ This file is an executable makefile, and contains the
+ package-specific recipies for compiling the package and
+ building binary package(s) out of the source.
+ </p>
+
+ <p>
+ It must start with the line <tt>#!/usr/bin/make -f</tt>,
+ so that it can be invoked by saying its name rather than
+ invoking <prgn>make</prgn> explicitly.
+ </p>
+
+ <p>
+ Since an interactive <tt>debian/rules</tt> script makes it
+ impossible to autocompile that package and also makes it
+ hard for other people to reproduce the same binary
+ package, all <strong>required targets</strong> have to be
+ non-interactive. At a minimul, required targets are the
+ ones called by <prgn>dpkg-buildpackage</prgn>, namely,
+ <em>clean</em>, <em>binary</em>, <em>binary-arch</em>, and
+ <em>build</em>. It also follows that any target that these
+ targets depend on must also be non-interactive.
+ </p>
+
+ <p>
+ The targets which are required to be present are:
+ <taglist>
+ <tag><tt>build</tt></tag>
+ <item>
+ <p>
+ This should perform all non-interactive
+ configuration and compilation of the package. If a
+ package has an interactive pre-build configuration
+ routine, the Debianised source package should be
+ built after this has taken place, so that it can be
+ built without rerunning the configuration.
+ </p>
+
+ <p>
+ A package may also provide both of the targets
+ <tt>build-arch</tt> and <tt>build-indep</tt>. The
+ <tt>build-arch</tt> target, if provided, should
+ perform all non-interactive configuration and
+ compilation required for producing all
+ architecture-dependant binary packages (those packages
+ for which the body of the <tt>Architecture</tt> field
+ in <tt>debian/control</tt> is not <tt>all</tt>).
+ Similarly, the <tt>build-indep</tt> target, if
+ provided, should perform all non-interactive
+ configuration and compilation required for producing
+ all architecture-independent binary packages (those
+ packages for which the body of the
+ <tt>Architecture</tt> field in <tt>debian/control</tt>
+ is <tt>all</tt>). The <tt>build</tt> target should
+ depend on those of the targets <tt>build-arch</tt> and
+ <tt>build-indep</tt> that are provided in the rules
+ file.
+ </p>
+
+ <p>
+ If one or both of the targets <tt>build-arch</tt> and
+ <tt>build-indep</tt> are not provided, then invoking
+ <tt>debian/rules</tt> with one of the not-provided
+ targets as arguments should produce a exit status code
+ of 2. Usually this is provided automatically by make
+ if the target is missing.
+ </p>
+
+ <p>
+ For some packages, notably ones where the same
+ source tree is compiled in different ways to produce
+ two binary packages, the <tt>build</tt> target does
+ not make much sense. For these packages it is good
+ enough to provide two (or more) targets
+ (<tt>build-a</tt> and <tt>build-b</tt> or whatever)
+ for each of the ways of building the package, and a
+ <tt>build</tt> target that does nothing. The
+ <tt>binary</tt> target will have to build the
+ package in each of the possible ways and make the
+ binary package out of each.
+ </p>
+
+ <p>
+ The targets <tt>build</tt>, <tt>build-arch</tt>
+ and <tt>build-indep</tt> target must not do
+ anything that might require root privilege.
+ </p>
+
+ <p>
+ The <tt>build</tt> target may need to run
+ <tt>clean</tt> first - see below.
+ </p>
+
+ <p>
+ When a package has a configuration routine that takes
+ a long time, or when the makefiles are poorly
+ designed, or when <tt>build</tt> needs to run
+ <tt>clean</tt> first, it is a good idea to <tt>touch
+ build</tt> when the build process is complete. This
+ will ensure that if <tt>debian/rules build</tt> is run
+ again it will not rebuild the whole program.
+ </p>
+ </item>
+
+ <tag><tt>binary</tt>, <tt>binary-arch</tt>,
+ <tt>binary-indep</tt>
+ </tag>
+ <item>
+ <p>
+ The <tt>binary</tt> target should be all that is
+ necessary for the user to build the binary
+ package. All these targets are required to be
+ non-interactive. It is split into two parts:
+ <tt>binary-arch</tt> builds the packages' output
+ files which are specific to a particular
+ architecture, and <tt>binary-indep</tt> builds
+ those which are not.
+ </p>
+
+ <p>
+ <tt>binary</tt> should usually be a target with
+ no commands which simply depends on
+ <prgn>binary-arch</prgn> and
+ <prgn>binary-indep</prgn>.
+ </p>
+
+ <p>
+ Both <prgn>binary-*</prgn> targets should depend on
+ the <tt>build</tt> target, above, so that the
+ package is built if it has not been already. It
+ should then create the relevant binary package(s),
+ using <prgn>dpkg-gencontrol</prgn> to make their
+ control files and <prgn>dpkg-deb</prgn> to build
+ them and place them in the parent of the top level
+ directory.
+ </p>
+
+ <p>
+ If one of the <prgn>binary-*</prgn> targets has
+ nothing to do (this will be always be the case if
+ the source generates only a single binary package,
+ whether architecture-dependent or not) it
+ <em>must</em> still exist, but should always
+ succeed.
+ </p>
+
+ <p>
+ <ref id="pkg-binarypkg"> describes how to construct
+ binary packages.
+ </p>
+
+ <p>
+ The <tt>binary</tt> targets must be invoked as
+ root.
+ </p>
+ </item>
+
+ <tag><tt>clean</tt></tag>
+ <item>
+
+ <p>
+ This should undo any effects that the
+ <tt>build</tt> and <tt>binary</tt> targets
+ may have had, except that it should leave alone any
+ output files created in the parent directory by a
+ run of <tt>binary</tt>. This target is required
+ to be non-interactive.
+ </p>
+
+ <p>
+ If a <tt>build</tt> file is touched at the end
+ of the <tt>build</tt> target, as suggested
+ above, it must be removed as the first thing that
+ <tt>clean</tt> does, so that running
+ <tt>build</tt> again after an interrupted
+ <tt>clean</tt> doesn't think that everything is
+ already done.
+ </p>
+
+ <p>
+ The <tt>clean</tt> target must be invoked as
+ root if <tt>binary</tt> has been invoked since
+ the last <tt>clean</tt>, or if
+ <tt>build</tt> has been invoked as root (since
+ <tt>build</tt> may create directories, for
+ example).
+ </p>
+ </item>
+
+ <tag><tt>get-orig-source</tt> (optional)</tag>
+ <item>
+
+ <p>
+ This target fetches the most recent version of the
+ original source package from a canonical archive
+ site (via FTP or WWW, for example), does any
+ necessary rearrangement to turn it into the original
+ source tarfile format described below, and leaves it
+ in the current directory.
+ </p>
+
+ <p>
+ This target may be invoked in any directory, and
+ should take care to clean up any temporary files it
+ may have left.
+ </p>
+
+ <p>
+ This target is optional, but providing it if
+ possible is a good idea.
+ </p>
+ </item>
+ </taglist>
+
+ <p>
+ The <tt>build</tt>, <tt>binary</tt> and
+ <tt>clean</tt> targets must be invoked with a current
+ directory of the package's top-level directory.
+ </p>
+
+
+ <p>
+ Additional targets may exist in <tt>debian/rules</tt>,
+ either as published or undocumented interfaces or for the
+ package's internal use.
+ </p>
+
+ <p>
+ The architecture we build on and build for is determined by make
+ variables via dpkg-architecture (see <ref id="pkg-dpkgarch">). You can
+ get the Debian architecture and the GNU style architecture
+ specification string for the build machine as well as the host
+ machine. Here is a list of supported make variables:
+ <list compact="compact">
+ <item>
+ <p><tt>DEB_*_ARCH</tt> (the Debian architecture)</p>
+ </item>
+ <item>
+ <p><tt>DEB_*_GNU_TYPE</tt> (the GNU style architecture
+ specification string)</p>
+ </item>
+ <item>
+ <p><tt>DEB_*_GNU_CPU</tt> (the CPU part of DEB_*_GNU_TYPE)</p>
+ </item>
+ <item>
+ <p><tt>DEB_*_GNU_SYSTEM</tt> (the System part of
+ DEB_*_GNU_TYPE)</p>
+ </list>
+ </p>
+
+ <p>
+ where <tt>*</tt> is either <tt>BUILD</tt> for specification of
+ the build machine or <tt>HOST</tt> for specification of the machine
+ we build for.
+ </p>
+
+ <p>
+ Backward compatibility can be provided in the rules file
+ by setting the needed variables to suitable default
+ values, please refer to the documentation of
+ dpkg-architecture for details.
+ </p>
+
+ <p>
+ It is important to understand that the <tt>DEB_*_ARCH</tt>
+ string does only determine which Debian architecture we
+ build on resp. for. It should not be used to get the CPU
+ or System information, the GNU style variables should be
+ used for that.
+ </p>
+ </sect1>
+
+
+ <sect1><heading><tt>debian/control</tt>
+ </heading>
+
+ <p>
+ This file contains version-independent details about the
+ source package and about the binary packages it creates.
+ </p>
+
+ <p>
+ It is a series of sets of control fields, each
+ syntactically similar to a binary package control file.
+ The sets are separated by one or more blank lines. The
+ first set is information about the source package in
+ general; each subsequent set describes one binary package
+ that the source tree builds.
+ </p>
+
+ <p>
+ The syntax and semantics of the fields are described below
+ in <ref id="pkg-controlfields">.
+ </p>
+
+ <p>
+ The general (binary-package-independent) fields are:
+ <list compact="compact">
+ <item>
+ <p><qref id="pkg-f-Source"><tt>Source</tt></qref> (mandatory)</p>
+ </item>
+ <item>
+ <p><qref id="pkg-f-Maintainer"><tt>Maintainer</tt></qref></p>
+ </item>
+ <item>
+ <p>
+ <qref id="pkg-f-classification"><tt>Section</tt> and
+ <tt>Priority</tt></qref>
+ (classification, mandatory)
+ </p>
+ </item>
+ <item>
+ <p>
+ <qref id="relationships"><tt>Build-Depends</tt> et
+ al.</qref> (source package interrelationships)
+ </p>
+ </item>
+ <item>
+ <p>
+ <qref id="pkg-f-Standards-Version"><tt>Standards-Version</tt></qref>
+ </p>
+ </item>
+ </list>
+
+ <p>
+ The per-binary-package fields are:
+ <list compact="compact">
+ <item>
+ <p><qref id="pkg-f-Package"><tt>Package</tt></qref> (mandatory)</p>
+ </item>
+ <item>
+ <p>
+ <qref id="pkg-f-Architecture"><tt>Architecture</tt></qref>
+ (mandatory)</p>
+ </item>
+ <item>
+ <p><qref id="descriptions"><tt>Description</tt></qref></p>
+ </item>
+ <item>
+ <p>
+ <qref id="pkg-f-classification"><tt>Section</tt> and
+ <tt>Priority</tt></qref> (classification)</p>
+ </item>
+ <item>
+ <p><qref id="pkg-f-Essential"><tt>Essential</tt></qref></p>
+ </item>
+ <item>
+ <p>
+ <qref id="relationships"><tt>Depends</tt> et
+ al.</qref> (binary package interrelationships)
+ </p>
+ </item>
+ </list>
+
+ <p>
+ These fields are used by <prgn>dpkg-gencontrol</prgn> to
+ generate control files for binary packages (see below), by
+ <prgn>dpkg-genchanges</prgn> to generate the
+ <tt>.changes</tt> file to accompany the upload, and by
+ <prgn>dpkg-source</prgn> when it creates the <tt>.dsc</tt>
+ source control file as part of a source archive.
+ </p>
+
+ <p>
+ The fields here may contain variable references - their
+ values will be substituted by
+ <prgn>dpkg-gencontrol</prgn>, <prgn>dpkg-genchanges</prgn>
+ or <prgn>dpkg-source</prgn> when they generate output
+ control files. See <ref id="pkg-srcsubstvars"> for details.
+ </p>
+
+ <p> <sect2><heading>User-defined fields
+ </heading>
+
+ <p>
+ Additional user-defined fields may be added to the
+ source package control file. Such fields will be
+ ignored, and not copied to (for example) binary or
+ source package control files or upload control files.
+ </p>
+
+ <p>
+ If you wish to add additional unsupported fields to
+ these output files you should use the mechanism
+ described here.
+ </p>
+
+ <p>
+ Fields in the main source control information file with
+ names starting <tt>X</tt>, followed by one or more of
+ the letters <tt>BCS</tt> and a hyphen <tt>-</tt>, will
+ be copied to the output files. Only the part of the
+ field name after the hyphen will be used in the output
+ file. Where the letter <tt>B</tt> is used the field
+ will appear in binary package control files, where the
+ letter <tt>S</tt> is used in source package control
+ files and where <tt>C</tt> is used in upload control
+ (<tt>.changes</tt>) files.
+ </p>
+
+ <p>
+ For example, if the main source information control file
+ contains the field
+ <example>
+ XBS-Comment: I stand between the candle and the star.
+ </example>
+ then the binary and source package control files will contain the
+ field
+ <example>
+ Comment: I stand between the candle and the star.
+ </example>
+ </p>
+ </sect2>
+
+ </sect1>
+
+ <sect1 id="pkg-dpkgchangelog"><heading><tt>debian/changelog</tt>
+ </heading>
+
+ <p>
+ This file records the changes to the Debian-specific parts of the
+ package
+ <footnote>
+ <p>
+ Though there is nothing stopping an author who is also
+ the Debian maintainer from using it for all their
+ changes, it will have to be renamed if the Debian and
+ upstream maintainers become different
+ people.
+ </p>
+ </footnote>.
+ </p>
+
+ <p>
+ It has a special format which allows the package building
+ tools to discover which version of the package is being
+ built and find out other release-specific information.
+ </p>
+
+ <p>
+ That format is a series of entries like this:
+ <example>
+ <var>package</var> (<var>version</var>) <var>distribution(s)</var>; urgency=<var>urgency</var>
+
+ * <var>change details</var>
+ <var>more change details</var>
+ * <var>even more change details</var>
+
+ -- <var>maintainer name and email address</var> <var>date</var>
+ </example>
+ </p>
+
+ <p>
+ <var>package</var> and <var>version</var> are the source
+ package name and version number.
+ </p>
+
+ <p>
+ <var>distribution(s)</var> lists the distributions where
+ this version should be installed when it is uploaded - it
+ is copied to the <tt>Distribution</tt> field in the
+ <tt>.changes</tt> file. See <ref id="pkg-f-Distribution">.
+ </p>
+
+ <p>
+ <var>urgency</var> is the value for the <tt>Urgency</tt>
+ field in the <tt>.changes</tt> file for the upload. See
+ <ref id="pkg-f-Urgency">. It is not possible to specify an
+ urgency containing commas; commas are used to separate
+ <tt><var>keyword</var>=<var>value</var></tt> settings in
+ the <prgn>dpkg</prgn> changelog format (though there is
+ currently only one useful <var>keyword</var>,
+ <tt>urgency</tt>).
+ </p>
+
+ <p>
+ The change details may in fact be any series of lines
+ starting with at least two spaces, but conventionally each
+ change starts with an asterisk and a separating space and
+ continuation lines are indented so as to bring them in
+ line with the start of the text above. Blank lines may be
+ used here to separate groups of changes, if desired.
+ </p>
+
+ <p>
+ The maintainer name and email address should <em>not</em>
+ necessarily be those of the usual package maintainer.
+ They should be the details of the person doing
+ <em>this</em> version. The information here will be
+ copied to the <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 timezone specified
+ numerically, with the timezone name or abbreviation
+ optionally present as a comment.
+ </p>
+
+ <p>
+ The first `title' line with the package name should start
+ at the left hand margin; the `trailer' line with the
+ maintainer and date details should be preceded by exactly
+ one space. The maintainer details and the date must be
+ separated by exactly two spaces.
+ </p>
+
+ <p>
+ An Emacs mode for editing this format is available: it is
+ called <tt>debian-changelog-mode</tt>. You can have this
+ mode selected automatically when you edit a Debian
+ changelog by adding a local variables clause to the end of
+ the changelog.
+ </p>
+
+ <sect2><heading>Defining alternative changelog formats
+ </heading>
+
+ <p>
+ It is possible to use a different format to the standard
+ one, by providing a parser for the format you wish to
+ use.
+ </p>
+
+ <p>
+ In order to have <tt>dpkg-parsechangelog</tt> run your
+ parser, you must include a line within the last 40 lines
+ of your file matching the Perl regular expression:
+ <tt>\schangelog-format:\s+([0-9a-z]+)\W</tt> The part in
+ parentheses should be the name of the format. For
+ example, you might say:
+ <example>
+ @@@ changelog-format: joebloggs @@@
+ </example>
+ Changelog format names are non-empty strings of alphanumerics.
+ </p>
+
+ <p>
+ If such a line exists then <tt>dpkg-parsechangelog</tt>
+ will look for the parser as
+ <tt>/usr/lib/dpkg/parsechangelog/<var>format-name</var></tt>
+ or
+ <tt>/usr/local/lib/dpkg/parsechangelog/<var>format-name</var></tt>;
+ it is an error for it not to find it, or for it not to
+ be an executable program. The default changelog format
+ is <tt>dpkg</tt>, and a parser for it is provided with
+ the <tt>dpkg</tt> package.
+ </p>
+
+ <p>
+ The parser will be invoked with the changelog open on
+ standard input at the start of the file. It should read
+ the file (it may seek if it wishes) to determine the
+ information required and return the parsed information
+ to standard output in the form of a series of control
+ fields in the standard format. By default it should
+ return information about only the most recent version in
+ the changelog; it should accept a
+ <tt>-v<var>version</var></tt> option to return changes
+ information from all versions present <em>strictly
+ after</em> <var>version</var>, and it should then be an
+ error for <var>version</var> not to be present in the
+ changelog.
+ </p>
+
+ <p>
+ The fields are:
+ <list compact="compact">
+ <item>
+ <p><qref id="pkg-f-Source"><tt>Source</tt></qref></p>
+ </item>
+ <item>
+ <p><qref id="versions"><tt>Version</tt></qref> (mandatory)</p>
+ </item>
+ <item>
+ <p>
+ <qref id="pkg-f-Distribution"><tt>Distribution</tt></qref>
+ (mandatory)
+ </p>
+ </item>
+ <item>
+ <p><qref id="pkg-f-Urgency"><tt>Urgency</tt></qref> (mandatory)</p>
+ </item>
+ <item>
+ <p>
+ <qref id="pkg-f-Maintainer"><tt>Maintainer</tt></qref>
+ (mandatory)
+ </p>
+ </item>
+ <item>
+ <p><qref id="pkg-f-Date"><tt>Date</tt></qref></p>
+ </item>
+ <item>
+ <p>
+ <qref id="pkg-f-Changes"><tt>Changes</tt></qref>
+ (mandatory)
+ </p>
+ </item>
+ </list>
+
+ <p>
+ If several versions are being returned (due to the use
+ of <tt>-v</tt>), the urgency value should be of the
+ highest urgency code listed at the start of any of the
+ versions requested followed by the concatenated
+ (space-separated) comments from all the versions
+ requested; the maintainer, version, distribution and
+ date should always be from the most recent version.
+ </p>
+
+ <p>
+ For the format of the <tt>Changes</tt> field see <ref
+ id="pkg-f-Changes">.
+ </p>
+
+ <p>
+ If the changelog format which is being parsed always or
+ almost always leaves a blank line between individual
+ change notes these blank lines should be stripped out,
+ so as to make the resulting output compact.
+ </p>
+
+ <p>
+ If the changelog format does not contain date or package
+ name information this information should be omitted from
+ the output. The parser should not attempt to synthesise
+ it or find it from other sources.
+ </p>
+
+ <p>
+ If the changelog does not have the expected format the
+ parser should exit with a nonzero exit status, rather
+ than trying to muddle through and possibly generating
+ incorrect output.
+ </p>
+
+ <p>
+ A changelog parser may not interact with the user at
+ all.</p></sect2>
+ </sect1>
+
+ <sect1 id="pkg-srcsubstvars"><heading><tt>debian/substvars</tt>
+ and variable substitutions
+ </heading>
+
+ <p>
+ When <prgn>dpkg-gencontrol</prgn>,
+ <prgn>dpkg-genchanges</prgn> and <prgn>dpkg-source</prgn>
+ generate control files they do variable substitutions on
+ their output just before writing it. Variable
+ substitutions have the form
+ <tt>${<var>variable-name</var>}</tt>. The optional file
+ <tt>debian/substvars</tt> contains variable substitutions
+ to be used; variables can also be set directly from
+ <tt>debian/rules</tt> 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
+ <tt>debian/rules</tt> 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 <tt>debian/substvars</tt>.</p>
+ </sect1>
+
+ <sect1><heading><tt>debian/files</tt>
+ </heading>
+
+ <p>
+ This file is not a permanent part of the source tree; it
+ is used while building packages to record which files are
+ being generated. <prgn>dpkg-genchanges</prgn> uses it
+ when it generates a <tt>.changes</tt> file.
+ </p>
+
+ <p>
+ It should not exist in a shipped source package, and so it
+ (and any backup files or temporary files such as
+ <tt>files.new</tt>
+ <footnote>
+ <p>
+ <tt>files.new</tt> 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>
+ </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 <tt>.deb</tt> 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 <tt>debian/files</tt>.</p>
+ </sect1>
+
+ <sect1><heading><tt>debian/tmp</tt>
+ </heading>
+
+ <p>
+ This is the canonical temporary location for the
+ construction of binary packages by the <tt>binary</tt>
+ target. The directory <tt>tmp</tt> 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
+ <tt>debian/tmp<var>something</var></tt> directories, for
+ example <tt>tmp-a</tt> or <tt>tmp-doc</tt>.
+ </p>
+
+ <p>
+ Whatever <tt>tmp</tt> directories are created and used by
+ <tt>binary</tt> must of course be removed by the
+ <tt>clean</tt> target.</p></sect1>
+ </sect>
+
+
+ <sect id="pkg-sourcearchives"><heading>Source packages as archives
+ </heading>
+
+ <p>
+ As it exists on the FTP site, a Debian source package
+ consists of three related files. You must have the right
+ versions of all three to be able to use them.
+ </p>
+
+ <p>
+ <taglist>
+ <tag>Debian source control file - <tt>.dsc</tt></tag>
+ <item>
+
+ <p>
+ This file contains a series of fields, identified and
+ separated just like the fields in the control file of
+ a binary package. The fields are listed below; their
+ syntax is described above, in <ref id="pkg-controlfields">.
+ <list compact="compact">
+ <item>
+ <p><qref id="pkg-f-Source"><tt>Source</tt></qref></p>
+ </item>
+ <item>
+ <p><qref id="versions"><tt>Version</tt></qref></p>
+ </item>
+ <item>
+ <p><qref id="pkg-f-Maintainer"><tt>Maintainer</tt></qref></p>
+ </item>
+ <item>
+ <p><qref id="pkg-f-Binary"><tt>Binary</tt></qref></p>
+ </item>
+ <item>
+ <p><qref id="pkg-f-Architecture"><tt>Architecture</tt></qref></p>
+ </item>
+ <item>
+ <p>
+ <qref id="relationships"><tt>Build-Depends</tt> et
+ al.</qref> (source package interrelationships)
+ </p>
+ </item>
+ <item>
+ <p>
+ <qref id="pkg-f-Standards-Version"><tt>Standards-Version</tt></qref></p>
+ </item>
+ <item>
+ <p><qref id="pkg-f-Files"><tt>Files</tt></qref></p>
+ </item>
+ </list>
+
+ <p>
+ The source package control file is generated by
+ <prgn>dpkg-source</prgn> when it builds the source
+ archive, from other files in the source package,
+ described above. When unpacking it is checked against
+ the files and directories in the other parts of the
+ source package, as described below.</p>
+ </item>
+
+ <tag>
+ Original source archive -
+ <tt>
+ <var>package</var>_<var>upstream-version</var>.orig.tar.gz
+ </tt>
+ </tag>
+
+ <item>
+
+ <p>
+ This is a compressed (with <tt>gzip -9</tt>)
+ <prgn>tar</prgn> file containing the source code from
+ the upstream authors of the program. The tarfile
+ unpacks into a directory
+ <tt><var>package</var>-<var>upstream-version</var>.orig</tt>,
+ and does not contain files anywhere other than in
+ there or in its subdirectories.</p>
+ </item>
+
+ <tag>
+ Debianisation diff -
+ <tt>
+ <var>package</var>_<var>upstream_version-revision</var>.diff.gz
+ </tt>
+ </tag>
+ <item>
+
+ <p>
+ This is a unified context diff (<tt>diff -u</tt>)
+ giving the changes which are required to turn the
+ original source into the Debian source. These changes
+ may only include editing and creating plain files.
+ The permissions of files, the targets of symbolic
+ links and the characteristics of special files or
+ pipes may not be changed and no files may be removed
+ or renamed.
+ </p>
+
+ <p>
+ All the directories in the diff must exist, except the
+ <tt>debian</tt> subdirectory of the top of the source
+ tree, which will be created by
+ <prgn>dpkg-source</prgn> if necessary when unpacking.
+ </p>
+
+ <p>
+ The <prgn>dpkg-source</prgn> program will
+ automatically make the <tt>debian/rules</tt> 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
+ <tt><var>package</var>_<var>version</var>.tar.gz</tt> and
+ contains a directory
+ <tt><var>package</var>-<var>version</var></tt>.
+ </p>
+ </sect>
+
+ <sect><heading>Unpacking a Debian source package without
+ <prgn>dpkg-source</prgn>
+ </heading>
+
+ <p>
+ <tt>dpkg-source -x</tt> is the recommended way to unpack a
+ Debian source package. However, if it is not available it
+ is possible to unpack a Debian source archive as follows:
+ <enumlist compact="compact">
+ <item>
+ <p>
+ Untar the tarfile, which will create a <tt>.orig</tt>
+ directory.</p>
+ </item>
+ <item>
+ <p>Rename the <tt>.orig</tt> directory to
+ <tt><var>package</var>-<var>version</var></tt>.</p>
+ </item>
+ <item>
+ <p>
+ Create the subdirectory <tt>debian</tt> 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
+ <tt>.diff.gz</tt> file will not work.
+ </p>
+
+ <sect1><heading>Restrictions on objects in source packages
+ </heading>
+
+ <p>
+ The source package may not contain any hard links
+ <footnote>
+ <p>
+ This is not currently detected when building source
+ packages, but only when extracting
+ them.
+ </p>
+ </footnote>
+ <footnote>
+ <p>
+ Hard links may be permitted at some point in the
+ future, but would require a fair amount of
+ work.
+ </p>
+ </footnote>, device special files, sockets or setuid or
+ setgid files.
+ <footnote>
+ <p>
+ Setgid directories are allowed.
+ </p>
+ </footnote>
+ </p>
+
+ <p>
+ The source packaging tools manage the changes between the
+ original and Debianised source using <prgn>diff</prgn> and
+ <prgn>patch</prgn>. Turning the original source tree as
+ included in the <tt>.orig.tar.gz</tt> 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 <tt>debian</tt>.</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
+ <tt>debian/rules</tt>) and directories.</p></item>
+ </list>
+ </p>
+
+ <p>
+ The <tt>debian</tt> directory and <tt>debian/rules</tt>
+ are handled specially by <prgn>dpkg-source</prgn> - before
+ applying the changes it will create the <tt>debian</tt>
+ directory, and afterwards it will make
+ <tt>debian/rules</tt> 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 <tt>.changes</tt>
+ files which control the installation of uploaded files, and
+ <prgn>dpkg</prgn>'s internal databases are in a similar
+ format.
+ </p>
+
+ <sect><heading>Syntax of control files
+ </heading>
+
+ <p>
+ A file consists of one or more paragraphs of fields. The
+ paragraphs are separated by blank lines. Some control files
+ only allow one paragraph; others allow several, in which
+ case each paragraph often refers to a different package.
+ </p>
+
+ <p>
+ Each paragraph is a series of fields and values; each field
+ consists of a name, followed by a colon and the value. It
+ ends at the end of the line. Horizontal whitespace (spaces
+ and tabs) may occur before or after the value and is ignored
+ there; it is conventional to put a single space after the
+ colon.
+ </p>
+
+ <p>
+ Some fields' values may span several lines; in this case
+ each continuation line <em>must</em> start with a space or
+ tab. Any trailing spaces or tabs at the end of individual
+ lines of a field value are ignored.
+ </p>
+
+ <p>
+ Except where otherwise stated only a single line of data is
+ allowed and whitespace is not significant in a field body.
+ Whitespace may never appear inside names (of packages,
+ architectures, files or anything else), version numbers or
+ in between the characters of multi-character version
+ relationships.
+ </p>
+
+ <p>
+ Field names are not case-sensitive, but it is usual to
+ capitalise the field names using mixed case as shown below.
+ </p>
+
+ <p>
+ Blank lines, or lines consisting only of spaces and tabs,
+ are not allowed within field values or between fields - that
+ would mean a new paragraph.
+ </p>
+
+ <p>
+ It is important to note that there are several fields which
+ are optional as far as <prgn>dpkg</prgn> and the related
+ tools are concerned, but which must appear in every Debian
+ package, or whose omission may cause problems. 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>
+ The name of the binary package. Package names consist of
+ the alphanumerics and <tt>+</tt> <tt>-</tt> <tt>.</tt>
+ (plus, minus and full stop).
+ <footnote>
+ <p>
+ The characters <tt>@</tt> <tt>:</tt> <tt>=</tt>
+ <tt>%</tt> <tt>_</tt> (at, colon, equals, percent
+ and underscore) used to be legal and are still
+ accepted when found in a package file, but may not be
+ used in new packages
+ </p>
+ </footnote>
+ </p>
+
+ <p>
+ They must be at least two characters and must start with
+ an alphanumeric. In current versions of dpkg they are
+ sort of case-sensitive<footnote><p>This is a
+ bug.</p></footnote>; use lowercase package names unless
+ the package you're building (or referring to, in other
+ fields) is already using uppercase.</p>
+ </sect1>
+
+ <sect1 id="pkg-f-Version"><heading><tt>Version</tt>
+ </heading>
+
+ <p>
+ This lists the source or binary package's version number -
+ see <ref id="versions">.
+ </p>
+
+ </sect1>
+
+ <sect1 id="pkg-f-Architecture"><heading><tt>Architecture</tt>
+ </heading>
+
+ <p>
+ This is the architecture string; it is a single word for
+ the Debian architecture.
+ </p>
+
+ <p>
+ <prgn>dpkg</prgn> will check the declared architecture of
+ a binary package against its own compiled-in value before
+ it installs it.
+ </p>
+
+ <p>
+ The special value <tt>all</tt> indicates that the package
+ is architecture-independent.
+ </p>
+
+ <p>
+ In the main <tt>debian/control</tt> file in the source
+ package, or in the source package control file
+ <tt>.dsc</tt>, 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 <tt>.changes</tt> file the <tt>Architecture</tt>
+ field lists the architecture(s) of the package(s)
+ currently being uploaded. This will be a list; if the
+ source for the package is being uploaded too the special
+ entry <tt>source</tt> is also present.
+ </p>
+
+ <p>
+ See <ref id="pkg-debianrules"> for information how to get the
+ architecture for the build process.
+ </p>
+ </sect1>
+
+ <sect1 id="pkg-f-Maintainer"><heading><tt>Maintainer</tt>
+ </heading>
+
+ <p>
+ The package maintainer's name and email address. The name
+ should come first, then the email address inside angle
+ brackets <tt><></tt> (in RFC822 format).
+ </p>
+
+ <p>
+ If the maintainer's name contains a full stop then the
+ whole field will not work directly as an email address due
+ to a misfeature in the syntax specified in RFC822; a
+ program using this field as an address must check for this
+ and correct the problem if necessary (for example by
+ putting the name in round brackets and moving it to the
+ end, and bringing the email address forward).
+ </p>
+
+ <p>
+ In a <tt>.changes</tt> file or parsed changelog data this
+ contains the name and email address of the person
+ responsible for the particular version in question - this
+ may not be the package's usual maintainer.
+ </p>
+
+ <p>
+ This field is usually optional in as far as the
+ <prgn>dpkg</prgn> are concerned, but its absence when
+ building packages usually generates a warning.</p>
+ </sect1>
+
+ <sect1 id="pkg-f-Source"><heading><tt>Source</tt>
+ </heading>
+
+ <p>
+ This field identifies the source package name.
+ </p>
+
+ <p>
+ In a main source control information or a
+ <tt>.changes</tt> or <tt>.dsc</tt> file or parsed
+ changelog data this may contain only the name of the
+ source package.
+ </p>
+
+ <p>
+ In the control file of a binary package (or in a
+ <tt>Packages</tt> file) it may be followed by a version
+ number in parentheses.
+ <footnote>
+ <p>
+ It is usual to leave a space after the package name if
+ a version number is specified.
+ </p>
+ </footnote> This version number may be omitted (and is, by
+ <prgn>dpkg-gencontrol</prgn>) if it has the same value as
+ the <tt>Version</tt> field of the binary package in
+ question. The field itself may be omitted from a binary
+ package control file when the source package has the same
+ name and version as the binary package.
+ </p>
+ </sect1>
+
+ <sect1><heading>Package interrelationship fields:
+ <tt>Depends</tt>, <tt>Pre-Depends</tt>,
+ <tt>Recommends</tt> <tt>Suggests</tt>, <tt>Conflicts</tt>,
+ <tt>Provides</tt>, <tt>Replaces</tt>
+ </heading>
+
+ <p>
+ These fields describe the package's relationships with
+ other packages. Their syntax and semantics are described
+ in <ref id="relationships">.</p>
+ </sect1>
+
+ <sect1 id="pkg-f-Description"><heading><tt>Description</tt>
+ </heading>
+
+ <p>
+ In a binary package <tt>Packages</tt> file or main source
+ control file this field contains a description of the
+ binary package, in a special format. See <ref
+ id="descriptions"> for details.
+ </p>
+
+ <p>
+ In a <tt>.changes</tt> file it contains a summary of the
+ descriptions for the packages being uploaded. The part of
+ the field before the first newline is empty; thereafter
+ each line has the name of a binary package and the summary
+ description line from that binary package. Each line is
+ indented by one space.</p>
+ </sect1>
+
+ <sect1 id="pkg-f-Essential"><heading><tt>Essential</tt>
+ </heading>
+
+ <p>
+ This is a boolean field which may occur only in the
+ control file of a binary package (or in the
+ <tt>Packages</tt> file) or in a per-package fields
+ paragraph of a main source control data file.
+ </p>
+
+ <p>
+ If set to <tt>yes</tt> then <prgn>dpkg</prgn> and
+ <prgn>dselect</prgn> will refuse to remove the package
+ (though it can be upgraded and/or replaced). The other
+ possible value is <tt>no</tt>, which is the same as not
+ having the field at all.</p>
+ </sect1>
+
+ <sect1 id="pkg-f-classification"><heading><tt>Section</tt> and
+ <tt>Priority</tt>
+ </heading>
+
+ <p>
+ These two fields classify the package. The
+ <tt>Priority</tt> represents how important that it is that
+ the user have it installed; the <tt>Section</tt>
+ represents an application area into which the package has
+ been classified.
+ </p>
+
+ <p>
+ When they appear in the <tt>debian/control</tt> file these
+ fields give values for the section and priority subfields
+ of the <tt>Files</tt> field of the <tt>.changes</tt> 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
+ <tt>.changes</tt> file. The section value in a
+ <tt>.changes</tt> 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
+ <tt>Packages</tt> files are missing the information.
+ <prgn>dpkg</prgn> and <prgn>dselect</prgn> will only use
+ the value from a <tt>.deb</tt> file if they have no other
+ information; a value listed in a <tt>Packages</tt> file
+ will always take precedence. By default
+ <prgn>dpkg-gencontrol</prgn> does not include the section
+ and priority in the control file of a binary package - use
+ the <tt>-isp</tt>, <tt>-is</tt> or <tt>-ip</tt> options to
+ achieve this effect.</p>
+ </sect1>
+
+ <sect1 id="pkg-f-Binary"><heading><tt>Binary</tt>
+ </heading>
+
+ <p>
+ This field is a list of binary packages.
+ </p>
+
+ <p>
+ When it appears in the <tt>.dsc</tt> file it is the list
+ of binary packages which a source package can produce. It
+ does not necessarily produce all of these binary packages
+ for every architecture. The source control file doesn't
+ contain details of which architectures are appropriate for
+ which of the binary packages.
+ </p>
+
+ <p>
+ When it appears in a <tt>.changes</tt> file it lists the
+ names of the binary packages actually being uploaded.
+ </p>
+
+ <p>
+ The syntax is a list of binary packages separated by
+ commas.
+ <footnote>
+ <p>
+ A space after each comma is conventional.
+ </p>
+ </footnote> Currently the packages must be separated using
+ only spaces in the <tt>.changes</tt> 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 <tt>Packages</tt> files. It gives
+ the total amount of disk space required to install the
+ named package.
+ </p>
+
+ <p>
+ The disk space is represented in kilobytes as a simple
+ decimal number.</p>
+ </sect1>
+
+ <sect1 id="pkg-f-Files"><heading><tt>Files</tt>
+ </heading>
+
+ <p>
+ This field contains a list of files with information about
+ each one. The exact information and syntax varies with
+ the context. In all cases the the part of the field
+ contents on the same line as the field name is empty. The
+ remainder of the field is one line per file, each line
+ being indented by one space and containing a number of
+ sub-fields separated by spaces.
+ </p>
+
+ <p>
+ In the <tt>.dsc</tt> (Debian source control) file each
+ line contains the MD5 checksum, size and filename of the
+ tarfile and (if applicable) diff file which make up the
+ remainder of the source package.
+ <footnote>
+ <p>
+ That is, the parts which are not the
+ <tt>.dsc</tt>.
+ </p>
+ </footnote> The exact forms of the filenames are described
+ in <ref id="pkg-sourcearchives">.
+ </p>
+
+ <p>
+ In the <tt>.changes</tt> file this contains one line per
+ file being uploaded. Each line contains the MD5 checksum,
+ size, section and priority and the filename. The section
+ and priority are the values of the corresponding fields in
+ the main source control file - see <ref
+ id="pkg-f-classification">. If no section or priority is
+ specified then <tt>-</tt> should be used, though section
+ and priority values must be specified for new packages to
+ be installed properly.
+ </p>
+
+ <p>
+ The special value <tt>byhand</tt> for the section in a
+ <tt>.changes</tt> file indicates that the file in question
+ is not an ordinary package file and must by installed by
+ hand by the distribution maintainers. If the section is
+ <tt>byhand</tt> the priority should be <tt>-</tt>.
+ </p>
+
+ <p>
+ If a new Debian revision of a package is being shipped and
+ no new original source archive is being distributed the
+ <tt>.dsc</tt> must still contain the <tt>Files</tt> field
+ entry for the original source archive
+ <tt><var>package</var>-<var>upstream-version</var>.orig.tar.gz</tt>,
+ but the <tt>.changes</tt> 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
+ <tt>.dsc</tt> 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>
+
+ <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 <tt>.changes</tt> file or parsed changelog output
+ this contains the (space-separated) name(s) of the
+ distribution(s) where this version of the package should
+ be or was installed. Distribution names follow the rules
+ for package names. (See <ref id="pkg-f-Package">).
+ </p>
+
+ <p>
+ Current distribution values are:
+ <taglist>
+ <tag><em>stable</em></tag>
+ <item>
+ <p>
+ This is the current `released' version of Debian
+ GNU/Linux. A new version is released approximately
+ every 3 months after the <em>development</em> code has
+ been <em>frozen</em> for a month of testing. Once the
+ distribution is <em>stable</em> only major bug fixes
+ are allowed. When changes are made to this
+ distribution, the release number is increased
+ (for example: 1.2r1 becomes 1.2r2 then 1.2r3, etc).
+ </p>
+ </item>
+
+ <tag><em>unstable</em></tag>
+ <item>
+ <p>
+ This distribution value refers to the
+ <em>developmental</em> part of the Debian distribution
+ tree. New packages, new upstream versions of packages
+ and bug fixes go into the <em>unstable</em> directory
+ tree. Download from this distribution at your own
+ risk.</p>
+ </item>
+
+ <tag><em>contrib</em></tag>
+ <item>
+ <p>
+ The packages with this distribution value do not meet
+ the criteria for inclusion in the main Debian
+ distribution as defined by the Policy Manual, but meet
+ the criteria for the <em>contrib</em>
+ Distribution. There is currently no distinction
+ between stable and unstable packages in the
+ <em>contrib</em> or <em>non-free</em>
+ distributions. Use your best judgement in downloading
+ from this Distribution.</p>
+ </item>
+
+ <tag><em>non-free</em></tag>
+ <item>
+ <p>
+ Like the packages in the <em>contrib</em> seciton,
+ the packages in <em>non-free</em> do not meet the
+ criteria for inclusion in the main Debian distribution
+ as defined by the Policy Manual. Again, use your best
+ judgement in downloading from this Distribution.</p>
+
+ <tag><em>experimental</em></tag>
+ <item>
+ <p>
+ The packages with this distribution value are deemed
+ by their maintainers to be high risk. Oftentimes they
+ represent early beta or developmental packages from
+ various sources that the maintainers want people to
+ try, but are not ready to be a part of the other parts
+ of the Debian distribution tree. Download at your own
+ risk.</p>
+ </item>
+
+ <tag><em>frozen</em></tag>
+ <item>
+ <p>
+ From time to time, (currently, every 3 months) the
+ <em>unstable</em> distribution enters a state of
+ `code-freeze' in anticipation of release as a
+ <em>stable</em> version. During this period of testing
+ (usually 4 weeks) only fixes for existing or
+ newly-discovered bugs will be allowed.
+ </p>
+ </item>
+ </taglist> You should list <em>all</em> distributions that
+ the package should be installed into. Except in unusual
+ circumstances, installations to <em>stable</em> should also
+ go into <em>frozen</em> (if it exists) and
+ <em>unstable</em>. Likewise, installations into
+ <em>frozen</em> should also go into <em>unstable</em>.</p>
+ </sect1>
+
+ <sect1 id="pkg-f-Urgency"><heading><tt>Urgency</tt>
+ </heading>
+
+ <p>
+ This is a description of how important it is to upgrade to
+ this version from previous ones. It consists of a single
+ keyword usually taking one of the values <tt>LOW</tt>,
+ <tt>MEDIUM</tt> or <tt>HIGH</tt>) followed by an optional
+ commentary (separated by a space) which is usually in
+ parentheses. For example:
+ <example>
+ Urgency: LOW (HIGH for diversions users)
+ </example>
+ </p>
+
+ <p>
+ This field appears in the <tt>.changes</tt> file and in
+ parsed changelogs; its value appears as the value of the
+ <tt>urgency</tt> attribute in a <prgn>dpkg</prgn>-style
+ changelog (see <ref id="pkg-dpkgchangelog">).
+ </p>
+
+ <p>
+ Urgency keywords are not case-sensitive.</p>
+ </sect1>
+
+ <sect1 id="pkg-f-Date"><heading><tt>Date</tt>
+ </heading>
+
+ <p>
+ In <tt>.changes</tt> files and parsed changelogs, this
+ gives the date the package was built or last edited.</p>
+ </sect1>
+
+ <sect1 id="pkg-f-Format"><heading><tt>Format</tt>
+ </heading>
+
+ <p>
+ This field occurs in <tt>.changes</tt> files, and
+ specifies a format revision for the file. The format
+ described here is version <tt>1.5</tt>. The syntax of the
+ format value is the same as that of a package version
+ number except that no epoch or Debian revision is allowed
+ - see <ref id="versions">.</p>
+ </sect1>
+
+ <sect1 id="pkg-f-Changes"><heading><tt>Changes</tt>
+ </heading>
+
+ <p>
+ In a <tt>.changes</tt> file or parsed changelog this field
+ contains the human-readable changes data, describing the
+ differences between the last version and the current one.
+ </p>
+
+ <p>
+ There should be nothing in this field before the first
+ newline; all the subsequent lines must be indented by at
+ least one space; blank lines must be represented by a line
+ consiting only of a space and a full stop.
+ </p>
+
+ <p>
+ Each version's change information should be preceded by a
+ `title' line giving at least the version, distribution(s)
+ and urgency, in a human-readable way.
+ </p>
+
+ <p>
+ If data from several versions is being returned the entry
+ for the most recent version should be returned first, and
+ entries should be separated by the representation of a
+ blank line (the `title' line may also be followed by the
+ representation of blank line).</p>
+ </sect1>
+
+ <sect1 id="pkg-f-Filename"><heading><tt>Filename</tt> and
+ <tt>MSDOS-Filename</tt>
+ </heading>
+
+ <p>
+ These fields in <tt>Packages</tt> files give the
+ filename(s) of (the parts of) a package in the
+ distribution directories, relative to the root of the
+ Debian hierarchy. If the package has been split into
+ several parts the parts are all listed in order, separated
+ by spaces.</p>
+ </sect1>
+
+ <sect1 id="pkg-f-Size"><heading><tt>Size</tt> and <tt>MD5sum</tt>
+ </heading>
+
+ <p>
+ These fields in <tt>Packages</tt> files give the size (in
+ bytes, expressed in decimal) and MD5 checksum of the
+ file(s) which make(s) up a binary package in the
+ distribution. If the package is split into several parts
+ the values for the parts are listed in order, separated by
+ spaces.</p>
+ </sect1>
+
+ <sect1 id="pkg-f-Status"><heading><tt>Status</tt>
+ </heading>
+
+ <p>
+ This field in <prgn>dpkg</prgn>'s status file records
+ whether the user wants a package installed, removed or
+ left alone, whether it is broken (requiring
+ reinstallation) or not and what its current state on the
+ system is. Each of these pieces of information is a
+ single word.</p>
+ </sect1>
+
+ <sect1 id="pkg-f-Config-Version"><heading><tt>Config-Version</tt>
+ </heading>
+
+ <p>
+ If a package is not installed or not configured, this
+ field in <prgn>dpkg</prgn>'s status file records the last
+ version of the package which was successfully
+ configured.</p>
+ </sect1>
+
+ <sect1 id="pkg-f-Conffiles"><heading><tt>Conffiles</tt>
+ </heading>
+
+ <p>
+ This field in <prgn>dpkg</prgn>'s status file contains
+ information about the automatically-managed configuration
+ files held by a package. This field should <em>not</em>
+ appear anywhere in a package!</p>
+ </sect1>
+
+ <sect1><heading>Obsolete fields
+ </heading>
+
+ <p>
+ These are still recognised by <prgn>dpkg</prgn> but should
+ not appear anywhere any more.
+ <taglist compact="compact">
+
+ <tag><tt>Revision</tt></tag>
+ <tag><tt>Package-Revision</tt></tag>
+ <tag><tt>Package_Revision</tt></tag>
+ <item>
+ <p>
+ The Debian revision part of the package version was
+ at one point in a separate control file field. This
+ field went through several names.</p>
+ </item>
+
+ <tag><tt>Recommended</tt></tag>
+ <item><p>Old name for <tt>Recommends</tt></p>
+ </item>
+
+ <tag><tt>Optional</tt></tag>
+ <item><p>Old name for <tt>Suggests</tt>.</p>
+ </item>
+ <tag><tt>Class</tt></tag>
+ <item><p>Old name for <tt>Priority</tt>.</p>
+ </item>
+ </taglist>
+ </p>
+ </sect1>
+ </sect>
+ </appendix>
+
+ <appendix id="pkg-conffiles"><heading>Configuration file handling
+ (from old Packaging Manual)
+ </heading>
+
+ <p>
+ <prgn>dpkg</prgn> can do a certain amount of automatic
+ handling of package configuration files.
+ </p>
+
+ <p>
+ Whether this mechanism is appropriate depends on a number of
+ factors, but basically there are two approaches to any
+ particular configuration file.
+ </p>
+
+ <p>
+ The easy method is to ship a best-effort configuration in the
+ package, and use <prgn>dpkg</prgn>'s conffile mechanism to
+ handle updates. If the user is unlikely to want to edit the
+ file, but you need them to be able to without losing their
+ changes, and a new package with a changed version of the file
+ is only released infrequently, this is a good approach.
+ </p>
+
+ <p>
+ The hard method is to build the configuration file from
+ scratch in the <prgn>postinst</prgn> script, and to take the
+ responsibility for fixing any mistakes made in earlier
+ versions of the package automatically. This will be
+ appropriate if the file is likely to need to be different on
+ each system.
+ </p>
+
+ <sect><heading>Automatic handling of configuration files by
+ <prgn>dpkg</prgn>
+ </heading>
+
+ <p>
+ A package may contain a control area file called
+ <tt>conffiles</tt>. This file should be a list of filenames
+ of configuration files needing automatic handling, separated
+ by newlines. The filenames should be absolute pathnames,
+ and the files referred to should actually exist in the
+ package.
+ </p>
+
+ <p>
+ When a package is upgraded <prgn>dpkg</prgn> will process
+ the configuration files during the configuration stage,
+ shortly before it runs the package's <prgn>postinst</prgn>
+ script,
+ </p>
+
+ <p>
+ For each file it checks to see whether the version of the
+ file included in the package is the same as the one that was
+ included in the last version of the package (the one that is
+ being upgraded from); it also compares the version currently
+ installed on the system with the one shipped with the last
+ version.
+ </p>
+
+ <p>
+ If neither the user nor the package maintainer has changed
+ the file, it is left alone. If one or the other has changed
+ their version, then the changed version is preferred - i.e.,
+ if the user edits their file, but the package maintainer
+ doesn't ship a different version, the user's changes will
+ stay, silently, but if the maintainer ships a new version
+ and the user hasn't edited it the new version will be
+ installed (with an informative message). If both have
+ changed their version the user is prompted about the problem
+ and must resolve the differences themselves.
+ </p>
+
+ <p>
+ The comparisons are done by calculating the MD5 message
+ digests of the files, and storing the MD5 of the file as it
+ was included in the most recent version of the package.
+ </p>
+
+ <p>
+ When a package is installed for the first time
+ <prgn>dpkg</prgn> will install the file that comes with it,
+ unless that would mean overwriting a file already on the
+ filesystem.
+ </p>
+
+ <p>
+ However, note that <prgn>dpkg</prgn> will <em>not</em>
+ replace a conffile that was removed by the user (or by a
+ script). This is necessary because with some programs a
+ missing file produces an effect hard or impossible to
+ achieve in another way, so that a missing file needs to be
+ kept that way if the user did it.
+ </p>
+
+ <p>
+ Note that a package should <em>not</em> modify a
+ <prgn>dpkg</prgn>-handled conffile in its maintainer
+ scripts. Doing this will lead to <prgn>dpkg</prgn> giving
+ the user confusing and possibly dangerous options for
+ conffile update when the package is upgraded.</p>
+ </sect>
+
+ <sect><heading>Fully-featured maintainer script configuration
+ handling
+ </heading>
+
+ <p>
+ For files which contain site-specific information such as
+ the hostname and networking details and so forth, it is
+ better to create the file in the package's
+ <prgn>postinst</prgn> script.
+ </p>
+
+ <p>
+ This will typically involve examining the state of the rest
+ of the system to determine values and other information, and
+ may involve prompting the user for some information which
+ can't be obtained some other way.
+ </p>
+
+ <p>
+ When using this method there are a couple of important
+ issues which should be considered:
+ </p>
+
+ <p>
+ If you discover a bug in the program which generates the
+ configuration file, or if the format of the file changes
+ from one version to the next, you will have to arrange for
+ the postinst script to do something sensible - usually this
+ will mean editing the installed configuration file to remove
+ the problem or change the syntax. You will have to do this
+ very carefully, since the user may have changed the file,
+ perhaps to fix the very problem that your script is trying
+ to deal with - you will have to detect these situations and
+ deal with them correctly.
+ </p>
+
+ <p>
+ If you do go down this route it's probably a good idea to
+ make the program that generates the configuration file(s) a
+ separate program in <tt>/usr/sbin</tt>, by convention called
+ <tt><var>package</var>config</tt> and then run that if
+ appropriate from the post-installation script. The
+ <tt><var>package</var>config</tt> program should not
+ unquestioningly overwrite an existing configuration - if its
+ mode of operation is geared towards setting up a package for
+ the first time (rather than any arbitrary reconfiguration
+ later) you should have it check whether the configuration
+ already exists, and require a <tt>--force</tt> flag to
+ overwrite it.</p></sect>
+ </appendix>
+
+ <appendix id="pkg-alternatives"><heading>Alternative versions of
+ an interface - <prgn>update-alternatives</prgn> (from old
+ Packaging Manual)
+ </heading>
+
+ <p>
+ When several packages all provide different versions of the
+ same program or file it is useful to have the system select a
+ default, but to allow the system administrator to change it
+ and have their decisions respected.
+ </p>
+
+ <p>
+ For example, there are several versions of the <prgn>vi</prgn>
+ editor, and there is no reason to prevent all of them from
+ being installed at once, each under their own name
+ (<prgn>nvi</prgn>, <prgn>vim</prgn> or whatever).
+ Nevertheless it is desirable to have the name <tt>vi</tt>
+ refer to something, at least by default.
+ </p>
+
+ <p>
+ If all the packages involved cooperate, this can be done with
+ <prgn>update-alternatives</prgn>.
+ </p>
+
+ <p>
+ Each package provides its own version under its own name, and
+ calls <prgn>update-alternatives</prgn> in its postinst to
+ register its version (and again in its prerm to deregister
+ it).
+ </p>
+
+ <p>
+ See the manpage <manref name="update-alternatives"
+ section="8"> for details.
+ </p>
+
+ <p>
+ If <prgn>update-alternatives</prgn> does not seem appropriate
+ you may wish to consider using diversions instead.</p>
+ </appendix>
+
+ <appendix id="pkg-diversions"><heading>Diversions - overriding a
+ package's version of a file (from old Packaging Manual)
+ </heading>
+
+ <p>
+ It is possible to have <prgn>dpkg</prgn> not overwrite a file
+ when it reinstalls the package it belongs to, and to have it
+ put the file from the package somewhere else instead.
+ </p>
+
+ <p>
+ This can be used locally to override a package's version of a
+ file, or by one package to override another's version (or
+ provide a wrapper for it).
+ </p>
+
+ <p>
+ Before deciding to use a diversion, read <ref
+ id="pkg-alternatives"> to see if you really want a diversion
+ rather than several alternative versions of a program.
+ </p>
+
+ <p>
+ There is a diversion list, which is read by <prgn>dpkg</prgn>,
+ and updated by a special program <prgn>dpkg-divert</prgn>.
+ Please see <manref name="dpkg-divert" section="8"> for full
+ details of its operation.
+ </p>
+
+ <p>
+ When a package wishes to divert a file from another, it should
+ call <prgn>dpkg-divert</prgn> in its preinst to add the
+ diversion and rename the existing file. For example,
+ supposing that a <prgn>smailwrapper</prgn> package wishes to
+ install a wrapper around <tt>/usr/sbin/smail</tt>:
+ <example>
+ if [ install = "$1" -o upgrade = "$1" ]; then
+ dpkg-divert --package smailwrapper --add --rename \
+ --divert /usr/sbin/smail.real /usr/sbin/smail
+ fi
+ </example> Testing <tt>$1</tt> is necessary so that the script
+ doesn't try to add the diversion again when
+ <prgn>smailwrapper</prgn> is upgraded. The <tt>--package
+ smailwrapper</tt> ensures that <prgn>smailwrapper</prgn>'s
+ copy of <tt>/usr/sbin/smail</tt> can bypass the diversion and
+ get installed as the true version.
+ </p>
+
+ <p>
+ The postrm has to do the reverse:
+ <example>
+ if [ remove = "$1" ]; then
+ dpkg-divert --package smailwrapper --remove --rename \
+ --divert /usr/sbin/smail.real /usr/sbin/smail
+ fi
+ </example>
+ </p>
+
+ <p>
+ Do not attempt to divert a file which is vitally important for
+ the system's operation - when using <prgn>dpkg-divert</prgn>
+ there is a time, after it has been diverted but before
+ <prgn>dpkg</prgn> has installed the new version, when the file
+ does not exist.</p>
+ </appendix>
+
+ </book>
+</debiandoc>
projects / debian / debian-policy.git / blobdiff