<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
+ 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
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
+ <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 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.
+ 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>
<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.
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>
</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>
<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>
+ <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.
<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>
- Examples of packages which would be included in "contrib"
- or "non-US/contrib" are
+ In addition, the packages in <em>contrib</em> and
+ <em>non-US/contrib</em>
<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,
+ must not be so buggy that we refuse to support them,
+ and
+ </p>
+ </item>
+ <item>
+ <p>
+ must meet all policy requirements presented in this
+ manual.
+ </p>
+ </item>
+ </list>
+ </p>
+
+ <p>
+ Furthermore, packages in <em>contrib</em> must not require
+ a package in a <em>non-US</em> section for compilation or
+ execution.
+ </p>
+
+ <p>
+ Examples of packages which would be included in
+ <em>contrib</em> or <em>non-US/contrib</em> are:
+ <list compact="compact">
+ <item>
+ <p>
+ free packages which require <em>contrib</em>,
+ <em>non-free</em> packages or packages which are not
+ in our archive at all for compilation or execution,
+ and
</p>
</item>
<item>
<p>
wrapper packages or other sorts of free accessories for
- non-free programs,
+ 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/<em><package></em>/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>
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
+ limited character-mode system. This is what will be
+ installed by default if the user doesn't select anything
else. It doesn't include many large applications, but
it does include Emacs (this is more of a piece of
infrastructure than an application) and a reasonable
- subset of TeX and LaTeX (if this is possible without
- X).</p>
+ subset of TeX and LaTeX.</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
+ (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>
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>
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 (a-z),
+ digits (0-9), plus (+) and minus (-) signs, and periods
+ (.). 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
<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>.
+ <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>
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>
<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>
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>
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>
-
+ mailing list and a consensus about doing that has been
+ reached.
+ </p>
+ </sect1>
<sect1>
<heading>Maintainer scripts</heading>
</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>
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).
+ 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
+ higher. These are included in the
<file>debconf_specification</file> files in the
- <package>debian-policy</package> package.)
+ <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.
+ 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">;
+ 2.5% of Debian packages [see <url
+ id="http://kitenet.net/programs/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">;
they include preconfiguration, (mostly)
noninteractive installation, elimination of
redundant prompting, consistency of user interface,
</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>
specification may contain an additional
<file>config</file> script and a <file>templates</file>
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.
+ script might be run before the <prgn>preinst</prgn>
+ script, and before the package is unpacked or any of its
+ dependancies or pre-dependancies are satisfied.
+ 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>
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>
<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 must specify the most recent version number of
+ this policy document with which your package complies.
+ 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
+ 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.
+ 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>
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>
<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 install
- 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
+ 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>
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
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>
+ 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>
<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
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
+ <prgn><stdarg.h></prgn> and <tt>ncurses</tt>
+ instead.
+ </p>
</sect1>
</sect>
</chapt>
<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>
+ <sect id="controlsyntax"><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.
+ 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.
+ 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>
+ Package: libc6
+ </example>
+ the field name is <tt>Package</tt> and the field value
+ <tt>libc6</tt>.
</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>
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. Most fields
- are dealt with elsewhere in this document and in the
- packaging manual.
+ are dealt with elsewhere in this document.
</p>
<sect1 id="f-Package"><heading><tt>Package</tt>
</heading>
<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>
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>
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>
+ be installed. Valid distributions are determined by the
+ archive maintainers.
<footnote>
- Current distribution values are:
+ Current distribution names are:
<taglist>
<tag><em>stable</em></tag>
<item>
<p>
This is the current `released' version of Debian
- GNU/Linux. Once the
- distribution is <em>stable</em> only 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>
</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>frozen</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>main</em></tag>
- <item>
- <p>
- The packages in this section are those in the
- main Debian distribution. They are all free
- (according to the Debian free software
- guidelines) and meet any other criteria for
- inclusion described in this manual.</p>
- </item>
-
- <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 this 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.
+ Every package has a version number recorded in its
+ <tt>Version</tt> control file field.
</p>
<p>
<p>
The version number format is:
- &lsqb<var>epoch</var><tt>:</tt>]<var>upstream-version</var>[<tt>-</tt><var>debian-revision</var>]
+ &lsqb<var>epoch</var><tt>:</tt>]<var>upstream_version</var>[<tt>-</tt><var>debian_revision</var>]
</p>
<p>
<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>
</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>
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;
+ 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>
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>
It is conventional to restart the
- <var>debian-revision</var> at <tt>1</tt> each time the
- <var>upstream-version</var> is increased.
+ <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).
- </p>
-
- <p>
- The <var>debian-revision</var> may contain only
- alphanumerics and the characters <tt>+</tt> and
- <tt>.</tt> (plus and full stop).
+ 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>
+ 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>
- These two steps are repeated (chopping initial non-digit
- strings and initial digit strings off from the start) until a
+ These two steps (comparing and removing initial non-digit
+ strings and initial digit strings) are repeated until a
difference is found or both strings are exhausted.
</p>
<p>
Note that the purpose of epochs is to allow us to leave behind
mistakes in version numbering, and to cope with situations
- where the version numbering 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>
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>
<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.
+ 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
</sect>
<sect id="debianrules"><heading><tt>debian/rules</tt> - the
- main building script </heading>
+ main building script</heading>
<p>
This file must be an executable makefile, and contains the
package-specific recipes for compiling the package and
- building binary package(s) out of the source.
+ building binary package(s) from the source.
</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>,
</p>
<p>
- The targets which must be present are:
+ The required and optional targets are as follows:
<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.
+ This should perform all non-interactive configuration
+ and compilation of the package. If a package has an
+ interactive pre-build configuration routine, the
+ Debianized source package must either be built after
+ this has taken place (so that the binary package can
+ be built without rerunning the configuration) or the
+ configuration routine modified to become
+ non-interactive. (The latter is preferable if there
+ are architecture-specific features detected by the
+ configuration routine.)
</p>
<p>
</p>
<p>
- The <prgn>build</prgn> target may need to run
- <prgn>clean</prgn> first - see below.
+ The <prgn>build</prgn> target may need to run the
+ <prgn>clean</prgn> 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
+ When a package has a configuration and build routine
+ which takes a long time, or when the makefiles are
+ poorly designed, or when <prgn>build</prgn> needs to
+
run <prgn>clean</prgn> first, it is a good idea to
<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 <prgn>build</prgn>
+ to depend on <prgn>build-stamp</prgn> and to do
+ nothing else, and for the <prgn>build-stamp</prgn>
+ target to do the building and to <tt>touch
+ build-stamp</tt> on completion. This is
+ especially useful if the build routine creates a
+ file or directory called <tt>build</tt>; in such a
+ case, <prgn>build</prgn> will need to be listed as
+ 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>
<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
+ necessary for the user to build the binary package(s)
+ produced from this source package. All of these
+ targets are required to be non-interactive. It is
+ split into two parts: <prgn>binary-arch</prgn> builds
+ the binary packages which are specific to a particular
architecture, and <prgn>binary-indep</prgn> builds
those which are not.
</p>
</p>
<p>
- Both <prgn>binary-*</prgn> targets should depend on
+ Each <prgn>binary-*</prgn> target should depend on
the <prgn>build</prgn> target, above, so that the
package is built if it has not been already. It
should then create the relevant binary package(s),
</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.
+ Both the <prgn>binary-arch</prgn> and
+ <prgn>binary-indep</prgn> 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.
+ <footnote>
+ <p>
+ The <prgn>fakeroot</prgn> package often allows one
+ to build a package correctly even without being
+ root.
+ </p>
+ </footnote>
</p>
</item>
<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 <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 a <prgn>binary</prgn>
+ 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
+ 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 action that
+ <prgn>clean</prgn> performs, so that running
<prgn>build</prgn> again after an interrupted
<prgn>clean</prgn> doesn't think that everything is
already done.
<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.
+ <prgn>clean</prgn> targets must be invoked with the current
+ directory being the package's top-level directory.
</p>
</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>
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>
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>
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>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>change details</var>
+ <var>more change details</var>
+ * <var>even more change details</var>
- -- <var>maintainer name and email address</var> <var>date</var>
+ -- <var>maintainer name and email address</var> <var>date</var>
</example>
</p>
<prgn>dpkg</prgn> changelog format (though there is
currently only one useful <var>keyword</var>,
<tt>urgency</tt>).
+ <footnote>
+ <p>
+ Usual urgency values are <tt>low</tt>, <tt>medium</tt>,
+ <tt>high</tt> and <tt>critical</tt>. They have an
+ effect on how quickly a package will be considered for
+ inclusion into the <tt>testing</tt> distribution, and
+ give an indication of the importance of any fixes
+ included in this upload.
+ </p>
+ </footnote>
</p>
<p>
</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.
+ 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:
+ <tt>/closes:\s*(?:bug)?\#?\s?\d+(?:,\s*(?:bug)?\#?\s?\d+)*/i</tt>
+ Then all of the bug numbers listed will be closed by the
+ archive maintenance script (<prgn>katie</prgn>), or in
+ the case of an NMU, marked as fixed.
+ </p>
+ </footnote>
+ </p>
+
+ <p>
+ The maintainer name and email address used in the changelog
+ should be the details of the person uploading <em>this</em>
+ version. They are <em>not</em> necessarily those of the
+ usual package maintainer. The information here will be
+ copied to the <tt>Changed-By</tt> field in the
+ <tt>.changes</tt> file, and then later used to send an
+ acknowledgement when the upload has been installed.
</p>
<p>
</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>
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
+ generate control files they perform 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/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.
+ 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.
+ The <tt>debian/substvars</tt> file is usually generated and
+ modified dynamically by <tt>debian/rules</tt> targets; in
+ this case it must be removed by the <prgn>clean</prgn>
+ target.
</p>
<p>
</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>.
+ 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 <prgn>dpkg-deb
+ --build</prgn> is run for that binary package. So for most
+ packages all that needs to be done with this file is to
+ delete it in the <prgn>clean</prgn> target.
</p>
<p>
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
</p>
<p>
- These scripts should be the files <tt>preinst</tt>,
+ These scripts are the files <tt>preinst</tt>,
<tt>postinst</tt>, <tt>prerm</tt> and <tt>postrm</tt> 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>
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>
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>
before (a version of) a package is removed and the
<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>
</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>
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>
<example>
<var>new-preinst</var> install
</example>
- Error unwind versions, respectively:
+ Error unwind actions, respectively:
<example>
<var>new-postrm</var> abort-upgrade <var>old-version</var>
<var>new-postrm</var> abort-install <var>old-version</var>
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>
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>
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
</p>
<p>
- A directory will never be replaced by a symbolic links
+ 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
<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:
<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>
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:
+ update any <tt>conffile</tt>s and then call:
<example>
<var>postinst</var> configure <var>most-recently-configured-version</var>
</example>
</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>
</example></p>
</item>
<item>
- <p>All the maintainer scripts except the postrm are removed.
+ <p>
+ All the maintainer scripts except the <tt>postrm</tt>
+ are removed.
</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 <tt>postrm</tt> 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>
</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>
Packages can declare in their control file that they have
</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.
+ 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>
<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>
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 symbols <tt>|</tt> (pipe symbols). In such
- a case, the presence of any one of the alternative packages
- is installed, that part of the dependency is considered to
- be satisfied.
+ 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 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
+ 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>
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>
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:
+ For example, a list of dependencies might appear as:
<example>
- Package: metamail
- Version: 2.7-3
- Depends: libc5 (>= 5.2.18-4), mime-support, csh | tcsh
+ Package: mutt
+ Version: 1.3.17-1
+ Depends: libc6 (>= 2.2.1), exim | mail-transport-agent
</example>
</p>
(<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>
</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.
+ 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>
<p>
- Thus <tt>Depends</tt> allows package maintainers to impose
- an order in which packages should be configured.
+ 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>
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>
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>
- <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.
+ 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 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.
+ 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>
- 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.
+ <tt>Pre-Depends</tt> should be used sparingly,
+ preferably only by packages whose premature upgrade or
+ installation would hamper the ability of the system to
+ continue with any upgrade that might be in progress.
</p>
+
+ <p>
+ <tt>Pre-Depends</tt> are also required if the
+ <prgn>preinst</prgn> script depends on the named
+ package. It is best to avoid this situation if
+ possible.
</item>
</taglist>
</p>
</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>
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>
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>
A package will not cause a conflict merely because its
configuration files are still installed; it must be at least
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>
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
+ 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
packages which provide it. This is so that, for example,
supposing we have
<example>
- Package: vm
- Depends: emacs
+ Package: foo
+ Depends: bar
</example>
- and someone else releases an xemacs package they can say
+ and someone else releases an enhanced version of the
+ <tt>bar</tt> package (for example, a non-US variant), 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).
+ 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>
<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.
+ 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>
+ <sect id="replaces"><heading>Overwriting files and replacing
+ packages - <tt>Replaces</tt></heading>
<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.
+ 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>
+ <sect1><heading>Overwriting files in other packages</heading>
<p>
Firstly, as mentioned before, it is usually an error for a
package to contain files which are on the system in
- another package, though currently the
- <tt>--force-overwrite</tt> flag is enabled by default,
- downgrading the error to a warning,
+ 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.
+ However, if the overwriting package declares that it
+ <tt>Replaces</tt> the one containing the file being
+ overwritten, then <prgn>dpkg</prgn> will replace the file
+ from the old package with that from the new. The file
+ will no longer be listed as `owned' by the old package.
</p>
<p>
If a package is completely replaced in this way, so that
<prgn>dpkg</prgn> does not know of any files it still
- contains, it is considered to have disappeared. It will
+ 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>
+ 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>
- In the future <prgn>dpkg</prgn> will discard files which
- would overwrite those from an already installed package
- which declares that it replaces the package being
- installed. This is so that you can install an older
- version of a package without problems.
+ 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>
- 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>
+ Furthermore, this usage of <tt>Replaces</tt> only takes
+ effect when both packages are at least partially on the
+ system at once, so that it can only happen if they do not
+ conflict or if the conflict has been overridden.
+ </p>
+
</sect1>
<sect1><heading>Replacing whole packages, forcing their
- removal
- </heading>
+ removal</heading>
<p>
Secondly, <tt>Replaces</tt> allows the packaging system to
resolve which package should be removed when there is a
conflict - see <ref id="conflicts">. This usage only
takes effect when the two packages <em>do</em> conflict,
- so that the two 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>
+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 are 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>
</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.
+ This chapter has been superseded by <ref id="config files">.
</p>
- <chapt id="sharedlibs"><heading>Shared libraries
- </heading>
+ <chapt id="sharedlibs"><heading>Shared libraries</heading>
<p>
Packages containing shared libraries must be constructed with
a little care to make sure that the shared library is always
available. This is especially important for packages whose
- shared libraries are vitally important, such as the 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
+ 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
+ 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.
+ 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
- installing them and will make the shared library links point
- to them, just before <prgn>dpkg</prgn> continues the
- installation and removes the links!
+ Any package installing shared libraries in a directory that is
+ listed in <tt>/etc/ld.so.conf</tt> or in one of the default
+ library directories of the dynamic linker (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 installing
+ them and will make the shared library links point to them,
+ just before <prgn>dpkg</prgn> continues the installation and
+ removes the links!
</p>
- <!--
- moved from section 2.2 , DMorris
- -->
-
<sect id="shlibs"><heading>The <tt>shlibs</tt> File Format
</heading>
<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>
<footnote>
<p>
It used to do this by calling <prgn>ldd</prgn>, but it
- now calls <prgn>objdump</prgn> to to this. This
+ now calls <prgn>objdump</prgn> to do this. This
requires a couple of changes in the way that packages
are built.
</p>
permissions 2775 (group-writable and set-group-id) and be
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>
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
+ <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
<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>
+ <ftppath>/debian/doc/package-developer/menu-policy.txt.gz</ftppath>
or your local mirror. In addition, it is included in the
<tt>debian-policy</tt> package.
</p>
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>
+ <ftppath>/debian/doc/package-developer/mime-policy.txt.gz</ftppath>
or your local mirror. In addition, it is included in the
<tt>debian-policy</tt> 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>
+ Manual</em> (or other documentation of the Debian
+ packaging tools) 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>
<p>
Shared libraries should not be installed
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
have to do any configuration other than that done
(semi-)automatically by the <tt>postinst</tt> 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
- 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>
+ <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
+ 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/<package></tt> or
+ <tt>/usr/lib/<package></tt> with a symbolic link
+ from <tt>/usr/share/doc/<package>/examples</tt>
+ if they are examples, and should be
+ perfectly ordinary <prgn>dpkg</prgn>-handled files
+ (<em>not</em> <tt>conffiles</tt>).
+ </p>
<p>
These two styles of configuration file handling must
</sect>
</chapt>
- <chapt>
+ <chapt id="customized-programs">
<heading>Customized programs</heading>
<sect id="arch-spec">
</enumlist></p></sect>
- <sect>
+ <sect id="mail-transport-agents">
<heading>Mail transport, delivery and user agents</heading>
<p>
serious brain damage!</p>
<p>
- The mail spool is <tt>/var/spool/mail</tt> and the interface
+ 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). The mail spool is part of the base system
- and not part of the MTA package.</p>
+ per the FHS). On older systems, the mail spool may be
+ physically located in /var/spool/mail, but all access to the
+ mail spool should be via the /var/mail 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
<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
+ <tt>xutils</tt> package), <tt>gzip</tt>ped, and
placed in a directory that corresponds to their
resolution:
<list>
<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>
+ 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
+ <em>conffile</em>s or handled as configuration files. For
+ programs that are not linked against the X Toolkit (Xt)
+ library, 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 <em>conffile</em> or handled as a
+ configuration file. <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> file which
+ had been customized by the system administrator.
</p>
-
<p>
<em>Packages using the X Window System should abide by the FHS
standard whenever possible</em>; they should install binaries,
</p>
</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>
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
+ /usr/share/doc/<package>/copyright. This file must
neither be compressed nor be a symbolic link.</p>
<p>
<p>
- /usr/share/doc/<package-name> may be a symbolic link to a
+ /usr/share/doc/<package> 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
projects / debian / debian-policy.git / blobdiff