<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
<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
+ 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>
<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 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>
</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>
+ In addition, the packages in <em>contrib</em> and
+ <em>non-US/contrib</em>
+ <list compact="compact">
+ <item>
+ <p>
+ must not be so buggy that we refuse to support them,
+ and
+ </p>
+ </item>
+ <item>
+ <p>
+ must meet all policy requirements presented in this
+ manual.
+ </p>
+ </item>
+ </list>
+ </p>
+
+ <p>
+ Furthermore, packages in <em>contrib</em> must not require
+ a package in a <em>non-US</em> section for compilation or
+ execution.
</p>
<p>
- Examples of packages which would be included in "contrib"
- or "non-US/contrib" are
+ Examples of packages which would be included in
+ <em>contrib</em> or <em>non-US/contrib</em> are:
<list compact="compact">
<item>
<p>
- free packages which require "contrib", "non-free"
- packages or packages which are not in our
- archive at all for compilation or execution,
+ free packages which require <em>contrib</em>,
+ <em>non-free</em> packages or packages which are not
+ in our archive at all for compilation or execution,
+ and
</p>
</item>
<item>
<p>
wrapper packages or other sorts of free accessories for
- non-free programs,
+ non-free programs.
</p>
</item>
</list>
</p>
</sect1>
<sect1>
- <heading>The non-free section and non-US/non-free </heading>
+ <heading>The non-free section</heading>
+ <p>
+ Packages must be placed in <em>non-free</em> or
+ <em>non-US/non-free</em> if they are not compliant with
+ the DFSG or are encumbered by patents or other legal
+ issues that make their distribution problematic.
+ </p>
<p>
- Packages must be placed in "non-free" or "non-US/non-free"
- if they are not compliant with the DFSG or are encumbered
- by patents or other legal issues that make their
- distribution problematic.
+ In addition, the packages in <em>non-free</em> and
+ <em>non-US/non-free</em>
+ <list compact="compact">
+ <item>
+ <p>
+ must not be so buggy that we refuse to support them,
+ and
+ </p>
+ </item>
+ <item>
+ <p>
+ must meet all policy requirements presented in this
+ manual that it is possible for them to meet.
+ <footnote>
+ <p>
+ It is possible that there are policy
+ requirements which the package is unable to
+ meet, for example, if the source is
+ unavailable. These situations will need to be
+ handled on a case-by-case basis.
+ </p>
+ </footnote>
+ </p>
+ </item>
+ </list>
</p>
</sect1>
+
<sect1>
<heading>The non-US sections</heading>
<p>
- Some programs with cryptographic program code need to be stored
- on the "non-US" server because of export restrictions of the
- U.S. Such programs must be distributed in the appropriate
- non-US section, either non-US/main, non-US/contrib or
- non-US/non-free. </p>
+ Some programs with cryptographic program code need to be
+ stored on the <em>non-US</em> server because of United
+ States export restrictions. Such programs must be
+ distributed in the appropriate <em>non-US</em> section,
+ either <em>non-US/main</em>, <em>non-US/contrib</em> or
+ <em>non-US/non-free</em>.
+ </p>
<p>
This applies only to packages which contain cryptographic
- code. A package containing a program with an interface to a
- cryptographic program or a program that's dynamically linked
- against a cryptographic library should not be distributed
- via the non-us server if it is capable of running without the
- cryptography library or program.
+ code. A package containing a program with an interface to
+ a cryptographic program or a program that's dynamically
+ linked against a cryptographic library should not be
+ distributed via the <em>non-US</em> server if it is
+ capable of running without the cryptographic library or
+ program.
</p>
</sect1>
<sect1>
<heading>Further copyright considerations</heading>
<p>
- Every package must be accompanied by a verbatim copy of its
- copyright and distribution license in the file
- /usr/share/doc/<package-name>/copyright (see
- <ref id="copyrightfile"> for details).</p>
+ Every package must be accompanied by a verbatim copy of
+ its copyright and distribution license in the file
+ <tt>/usr/share/doc/<ital><package-name></ital>/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>
+ <ital>subsection</ital> if the package is in the
+ <em>main</em> section,
+ </p>
+ </item>
+ <item>
+ <p>
+ <ital>section/subsection</ital> 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>
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>
<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>
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
files itself when building a package.
</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
respectively.
</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
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>
<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>
<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,
projects / debian / debian-policy.git / blobdiff