<book>
<titlepag>
<title>Debian Policy Manual</title>
- <author><ref id="authors"></author>
+ <author><qref id="authors">The Debian Policy Mailing List</qref></author>
<version>version &version;, &date;</version>
<abstract>
distribution.
</p>
-
<p>
This manual also describes Debian policy as it relates to
creating Debian packages. It is not a tutorial on how to build
the behavior of the packaging system. Instead, this manual
attempts to define the interface to the package management
system that the developers have to be conversant with.<footnote>
- <p>
Informally, the criteria used for inclusion is that the
material meet one of the following requirements:
<taglist compact="compact">
<tag>Standard interfaces</tag>
<item>
- <p>
The material presented represents an interface to
the packaging system that is mandated for use, and
is used by, a significant number of packages, and
compatibility with these interface
definitions. (Control file and changelog file
formats are examples.)
- </p>
</item>
<tag>Chosen Convention</tag>
<item>
- <p>
If there are a number of technically viable choices
that can be made, but one needs to select one of
these options for inter-operability. The version
number format is one example.
- </p>
</item>
</taglist>
Please note that these are not mutually exclusive;
selected conventions often become parts of standard
interfaces.
- </p>
</footnote>
</p>
</p>
<p>
- In this manual, the words <em>must</em>, <em>should</em> and
+ The appendices to this manual are not necessarily normative,
+ either. Please see <ref id="pkg-scope"> for more information.
+ </p>
+
+ <p>
+ In the normative part of this manual,
+ the words <em>must</em>, <em>should</em> and
<em>may</em>, and the adjectives <em>required</em>,
<em>recommended</em> and <em>optional</em>, are used to
distinguish the significance of the various guidelines in
<em>may</em> (or <em>optional</em>) are truly optional and
adherence is left to the maintainer's discretion.
</p>
+
<p>
These classifications are roughly equivalent to the bug
severities <em>serious</em> (for <em>must</em> or
<em>normal</em> or <em>important</em>
(for <em>should</em> or <em>recommended</em> directive
violations) and <em>wishlist</em> (for <em>optional</em>
- items).<footnote>
- <p>Compare RFC 2119. Note, however, that these words are
- used in a different way in this document.</p>
+ items).
+ <footnote>
+ Compare RFC 2119. Note, however, that these words are
+ used in a different way in this document.
</footnote>
</p>
+
<p>
Much of the information presented in this manual will be
useful even when building a package which is to be
<sect>
<heading>New versions of this document</heading>
+
<p>
- The current version of this document is always accessible
- from the Debian FTP server <ftpsite>ftp.debian.org</ftpsite>
- as
- <ftppath>/debian/doc/package-developer/policy.txt.gz</ftppath>
- (also available from the same directory are several other
- formats: <file>policy.html.tar.gz</file>, <file>policy.pdf.gz</file>
- and <file>policy.ps.gz</file>) or from the <url
- id="http://www.debian.org/doc/debian-policy/" name="Debian
- Policy Manual"> webpage.</p>
+ This manual is distributed via the Debian package
+ <package>debian-policy</package>.
+ </p>
<p>
- In addition, this manual is distributed via the Debian package
- <file>debian-policy</file>.
+ The current version of this document is also available from
+ the Debian web mirrors at
+ <tt><url name="/doc/debian-policy/"
+ id="http://www.debian.org/doc/debian-policy/"></tt>
+ and from the Debian archive mirrors at
+ <tt><url name="/doc/package-developer/policy.txt.gz"
+ id="http://ftp.debian.org/debian/doc/package-developer/policy.txt.gz"></tt>.
+ Also available from the same directory are several other
+ formats: <file>policy.html.tar.gz</file>, <file>policy.pdf.gz</file>
+ and <file>policy.ps.gz</file>.
</p>
<p>
- The <tt>debian-policy</tt> package also includes the file
+ The <package>debian-policy</package> package also includes the file
<file>upgrading-checklist.txt</file> which indicates policy
changes between versions of this document.
</p>
<p>
Since September 1998, the responsibility for the contents of
- this document lies on the debian-policy mailing list. Proposals
+ this document lies on the <url name="debian-policy mailing list"
+ id="mailto:debian-policy@lists.debian.org">. Proposals
are discussed there and inserted into policy after a certain
consensus is established.
<!-- insert shameless policy-process plug here eventually -->
of the Policy Manual regarding changes to the Policy.
</p>
</sect>
+
+ <sect id="related">
+ <heading>Related documents</heading>
+
+ <p>
+ There are several other documents other than this Policy Manual
+ that are necessary to fully understand some Debian policies and
+ procedures.
+ </p>
+
+ <p>
+ The external "sub-policy" documents are referred to in:
+ <list compact="compact">
+ <item><ref id="fhs"></item>
+ <item><ref id="virtual_pkg"></item>
+ <item><ref id="menus"></item>
+ <item><ref id="mime"></item>
+ <item><ref id="perl"></item>
+ <item><ref id="maintscriptprompt"></item>
+ <item><ref id="emacs"></item>
+ </list>
+ </p>
+
+ <p>
+ In addition to those, which carry the weight of policy, there
+ is the Debian Developer's Reference. This document describes
+ procedures and resources for Debian developers, but it is
+ <em>not</em> normative; rather, it includes things that don't
+ belong into the Policy, such as best practices for developers.
+ </p>
+
+ <p>
+ The Developer's Reference is available in the
+ <package>developers-reference</package> package.
+ It's also available from the Debian web mirrors at
+ <tt><url name="/doc/developers-reference/"
+ id="http://www.debian.org/doc/developers-reference/"></tt>.
+ </p>
+ </sect>
+
</chapt>
+
<chapt id="archive">
<heading>The Debian Archive</heading>
+
<p>
The Debian GNU/Linux system is maintained and distributed as a
collection of <em>packages</em>. Since there are so many of
<em>sections</em> and given <em>priorities</em> to simplify
the handling of them.
</p>
+
<p>
The effort of the Debian project is to build a free operating
system, but not every package we want to make accessible is
<list compact="compact">
<item>
- <p>to allow us to make as much software available as we
- can,</p>
+ to allow us to make as much software available as we can,
</item>
<item>
- <p>to allow us to encourage everyone to write free
- software, and</p>
+ to allow us to encourage everyone to write free software, and
</item>
<item>
- <p>to allow us to make it easy for people to produce
+ to allow us to make it easy for people to produce
CD-ROMs of our system without violating any licenses,
- import/export restrictions, or any other laws.</p>
+ import/export restrictions, or any other laws.
</item>
</list>
</p>
<tag>Free Redistribution
</tag>
<item>
- <p>
The license of a Debian component may not restrict any
party from selling or giving away the software as a
component of an aggregate software distribution
containing programs from several different
sources. The license may not require a royalty or
other fee for such sale.
- </p>
</item>
<tag>Source Code
</tag>
<item>
- <p>
The program must include source code, and must allow
distribution in source code as well as compiled form.
- </p>
</item>
<tag>Derived Works
</tag>
<item>
- <p>
The license must allow modifications and derived
works, and must allow them to be distributed under the
same terms as the license of the original software.
- </p>
</item>
<tag>Integrity of The Author's Source Code
</tag>
<item>
- <p>
The license may restrict source-code from being
distributed in modified form <em>only</em> if the
license allows the distribution of "patch files"
original software. (This is a compromise. The Debian
Project encourages all authors to not restrict any
files, source or binary, from being modified.)
- </p>
</item>
<tag>No Discrimination Against Persons or Groups
</tag>
<item>
- <p>
The license must not discriminate against any person
or group of persons.
- </p>
</item>
<tag>No Discrimination Against Fields of Endeavor
</tag>
<item>
- <p>
The license must not restrict anyone from making use
of the program in a specific field of endeavor. For
example, it may not restrict the program from being
used in a business, or from being used for genetic
research.
- </p>
</item>
<tag>Distribution of License
</tag>
<item>
- <p>
The rights attached to the program must apply to all
to whom the program is redistributed without the need
for execution of an additional license by those
parties.
- </p>
</item>
<tag>License Must Not Be Specific to Debian
</tag>
<item>
- <p>
The rights attached to the program must not depend on
the program's being part of a Debian system. If the
program is extracted from Debian and used or
the program is redistributed must have the same
rights as those that are granted in conjunction with
the Debian system.
- </p>
</item>
<tag>License Must Not Contaminate Other Software
</tag>
<item>
- <p>
The license must not place restrictions on other
software that is distributed along with the licensed
software. For example, the license must not insist
that all other programs distributed on the same medium
must be free software.
- </p>
</item>
<tag>Example Licenses
</tag>
<item>
- <p>
The "GPL," "BSD," and "Artistic" licenses are examples of
licenses that we consider <em>free</em>.
- </p>
</item>
</taglist>
</p>
<p>
Every package in <em>main</em> and <em>non-US/main</em>
must comply with the DFSG (Debian Free Software
- Guidelines).</p>
+ Guidelines).
+ </p>
<p>
In addition, the packages in <em>main</em>
<list compact="compact">
<item>
- <p>
must not require a package outside of <em>main</em>
for compilation or execution (thus, the package must
not declare a "Depends", "Recommends", or
"Build-Depends" relationship on a non-<em>main</em>
package),
- </p>
</item>
<item>
- <p>
must not be so buggy that we refuse to support them,
and
- </p>
</item>
<item>
- <p>
must meet all policy requirements presented in this
manual.
- </p>
</item>
</list>
</p>
+
<p>
Similarly, the packages in <em>non-US/main</em>
<list compact="compact">
<item>
- <p>
must not require a package outside of <em>main</em>
or <em>non-US/main</em> for compilation or
execution,
- </p>
</item>
<item>
- <p>
must not be so buggy that we refuse to support them,
- </p>
</item>
<item>
- <p>
must meet all policy requirements presented in this
manual.
- </p>
</item>
</list>
</p>
+
</sect1>
- <sect1>
+
+ <sect1 id="contrib">
<heading>The contrib section</heading>
+
<p>
Every package in <em>contrib</em> and
<em>non-US/contrib</em> must comply with the DFSG.
<em>non-US/contrib</em>
<list compact="compact">
<item>
- <p>
must not be so buggy that we refuse to support them,
and
- </p>
</item>
<item>
- <p>
must meet all policy requirements presented in this
manual.
- </p>
</item>
</list>
</p>
<em>contrib</em> or <em>non-US/contrib</em> are:
<list compact="compact">
<item>
- <p>
free packages which require <em>contrib</em>,
<em>non-free</em> packages or packages which are not
in our archive at all for compilation or execution,
and
- </p>
</item>
<item>
- <p>
wrapper packages or other sorts of free accessories for
non-free programs.
- </p>
</item>
</list>
</p>
</sect1>
- <sect1>
+
+ <sect1 id="non-free">
<heading>The non-free section</heading>
+
<p>
Packages must be placed in <em>non-free</em> or
<em>non-US/non-free</em> if they are not compliant with
the DFSG or are encumbered by patents or other legal
issues that make their distribution problematic.
</p>
+
<p>
In addition, the packages in <em>non-free</em> and
<em>non-US/non-free</em>
<list compact="compact">
<item>
- <p>
must not be so buggy that we refuse to support them,
and
- </p>
</item>
<item>
- <p>
must meet all policy requirements presented in this
- manual that it is possible for them to meet.<footnote>
- <p>
+ manual that it is possible for them to meet.
+ <footnote>
It is possible that there are policy
requirements which the package is unable to
meet, for example, if the source is
unavailable. These situations will need to be
handled on a case-by-case basis.
- </p>
</footnote>
- </p>
</item>
</list>
</p>
</sect1>
- <sect1>
+ <sect1 id="non-US">
<heading>The non-US sections</heading>
+
<p>
Non-free programs with cryptographic program code need to
be stored on the <em>non-us</em> server because of export
restrictions of the U.S.
</p>
+
<p>
Programs which use patented algorithms that have a
restrictied license also need to be stored on "non-us",
since that is located in a country where it is not allowed
to patent algorithms.
</p>
+
<p>
A package depends on another package which is distributed
via the non-us server has to be stored on the non-us
anywhere in our archives if
<list compact="compact">
<item>
- <p>
their use or distribution would break a law,
- </p>
</item>
<item>
- <p>
there is an ethical conflict in their distribution or
use,
- </p>
</item>
<item>
- <p>
we would have to sign a license for them, or
- </p>
</item>
<item>
- <p>
their distribution would conflict with other project
policies.
- </p>
</item>
</list>
</p>
should be of the form:
<list compact="compact">
<item>
- <p>
<em>subsection</em> if the package is in the
<em>main</em> section,
- </p>
</item>
<item>
- <p>
<em>section/subsection</em> if the package is in
the <em>contrib</em> or <em>non-free</em> section,
and
- </p>
</item>
<item>
- <p>
<tt>non-US</tt>, <tt>non-US/contrib</tt> or
<tt>non-US/non-free</tt> if the package is in
<em>non-US/main</em>, <em>non-US/contrib</em> or
<em>non-US/non-free</em> respectively.
- </p>
</item>
</list>
</p>
<taglist>
<tag><tt>required</tt></tag>
<item>
- <p>
Packages which are necessary for the proper
functioning of the system. You must not remove these
packages or your system may become totally broken and
put things back. Systems with only the
<tt>required</tt> packages are probably unusable, but
they do have enough functionality to allow the
- sysadmin to boot and install more software.</p>
+ sysadmin to boot and install more software.
</item>
<tag><tt>important</tt></tag>
<item>
- <p>
Important programs, including those which one would
expect to find on any Unix-like system. If the
expectation is that an experienced Unix person who
found it missing would say "What on earth is going on,
where is <prgn>foo</prgn>?", it must be an
<tt>important</tt> package.<footnote>
- <p>
This is an important criterion because we are
trying to produce, amongst other things, a free
Unix.
- </p>
</footnote>
Other packages without which the system will not run
well or be usable must also have priority
<em>not</em> include Emacs, the X Window System, TeX
or any other large applications. The
<tt>important</tt> packages are just a bare minimum of
- commonly-expected and necessary tools.</p>
+ commonly-expected and necessary tools.
</item>
<tag><tt>standard</tt></tag>
<item>
- <p>
These packages provide a reasonably small but not too
limited character-mode system. This is what will be
installed by default if the user doesn't select anything
- else. It doesn't include many large applications.</p>
+ else. It doesn't include many large applications.
</item>
<tag><tt>optional</tt></tag>
<item>
- <p>
(In a sense everything that isn't required is
optional, but that's not what is meant here.) This is
all the software that you might reasonably want to
and includes the X Window System, a full TeX
distribution, and many applications. Note that
optional packages should not conflict with each other.
- </p>
</item>
<tag><tt>extra</tt></tag>
<item>
- <p>
This contains all packages that conflict with others
with required, important, standard or optional
priorities, or are only likely to be useful if you
already know what they are or have specialised
requirements.
- </p>
</item>
- </taglist></p>
+ </taglist>
+ </p>
<p>
Packages must not depend on packages with lower priority
archive.</p>
<p>
- Package names must consist of lower case letters
+ Package names must consist only of lower case letters
(<tt>a-z</tt>), digits (<tt>0-9</tt>), plus (<tt>+</tt>)
and minus (<tt>-</tt>) signs, and periods (<tt>.</tt>).
They must be at least two characters long and must start
maintainership of the package until someone else
volunteers for that task. These packages are called
<em>orphaned packages</em>.<footnote>
- <p>
The detailed procedure for doing this gracefully can
- be found in the Debian Developer's Reference, either
- in the <tt>developers-reference</tt> package, or on
- the Debian FTP server
- <ftpsite>ftp.debian.org</ftpsite> as
- <ftppath>/debian/doc/package-developer/developers-reference.txt.gz</ftppath>
- or from the <url
- id="http://www.debian.org/doc/packaging-manuals/developers-reference/"
- name="Debian Developer's Reference"> webpage.
- </p>
+ be found in the Debian Developer's Reference,
+ see <ref id="related">.
</footnote>
</p>
</sect1>
doing that has been reached.</p></sect1>
- <sect1 id="virtual_pkg_sect">
+ <sect1 id="virtual_pkg">
<heading>Virtual packages</heading>
<p>
<p>
The latest version of the authoritative list of virtual
- package names can be found on
- <ftpsite>ftp.debian.org</ftpsite> in
- <ftppath>/debian/doc/package-developer/virtual-package-names-list.txt</ftppath>
- or your local mirror. In addition, it is included in the
- <tt>debian-policy</tt> package. The procedure for updating
- the list is described at the top of the file.</p></sect1>
+ package names can be found in the <tt>debian-policy</tt> package.
+ It's also available from the Debian web mirrors at
+ <tt><url name="/doc/packaging-manuals/virtual-package-names-list.txt"
+ id="http://www.debian.org/doc/packaging-manuals/virtual-package-names-list.txt"></tt>
+ and from the Debian archive mirrors at
+ <tt><url name="/doc/package-developer/virtual-package-names-list.txt"
+ id="http://ftp.debian.org/debian/doc/package-developer/virtual-package-names-list.txt"></tt>.
+ </p>
+
+ <p>
+ The procedure for updating the list is described in the preface
+ to the list.
+ </p>
+ </sect1>
<sect1>
<heading>Base system</heading>
</p>
- <sect2>
+ <sect2 id="maintscriptprompt">
<heading>Prompting in maintainer scripts</heading>
<p>
Package maintainer scripts may prompt the user if
- necessary. Prompting may be accomplished by hand, or by
- communicating with a program, such as
- <prgn>debconf</prgn>, which conforms to the Debian
- Configuration management specification, version 2 or
- higher. These are included in the
- <file>debconf_specification</file> files in the
- <package>debian-policy</package> package.
- You may also find this file on the FTP site
- <ftpsite>ftp.debian.org</ftpsite> in
- <ftppath>/debian/doc/package-developer/debconf_specification.txt.gz</ftppath>
- or on your local mirror.<footnote>
+ necessary. Prompting may be accomplished by
+ hand<footnote>
+ From the Jargon file: by hand 2. By extension,
+ writing code which does something in an explicit or
+ low-level way for which a presupplied library
+ (<em>debconf, in this instance</em>) routine ought
+ to have been available.
+ </footnote> (but this is deprecated), or by communicating
+ through a program which conforms to the Debian Configuration
+ management specification, version 2 or higher, such as
+ <prgn>debconf</prgn><footnote>
<p>
- 4% of Debian packages [see <url
- id="http://kitenet.net/programs/debconf/stats/"
+ 6% of Debian packages [see <url
+ id="http://auric.debian.org/%7Ejoeyh/debconf-stats/data/"
name="Debconf stats">] currently use
<package>debconf</package> to prompt the user at
install time, and this number is growing daily. The
installation, elimination of redundant prompting,
consistency of user interface, etc.
</p>
+
<p>
With this increasing number of packages using
<package>debconf</package>, plus the existance of a
of the protocol these things use, the time has
finally come to reflect the use of these things in
policy.
-
</p>
- </footnote>
+ </footnote>.
+ </p>
+
+ <p>
+ The Debian Configuration management specification is included
+ in the <file>debconf_specification</file> files in the
+ <package>debian-policy</package> package.
+ It is also available from the Debian web mirrors at
+ <tt><url name="/doc/packaging-manuals/debconf_specification.html"
+ id="http://www.debian.org/doc/packaging-manuals/debconf_specification.html"></tt>
+ and from the Debian archive mirrors at
+ <tt><url name="/doc/package-developer/debconf_specification.txt.gz"
+ id="http://ftp.debian.org/debian/doc/package-developer/debconf_specification.txt.gz"></tt>.
</p>
+
<p>
Packages which use the Debian Configuration management
specification may contain an additional
dependencies or pre-dependancies are satisfied.
Therefore it must work using only the tools present in
<em>essential</em> packages.<footnote>
- <p>
<package>Debconf</package> or another tool that
implements the Debian Configuration management
specification will also be installed, and any
versioned dependencies on it will be satisfied
before preconfiguration begins.
- </p>
</footnote>
</p>
are significant in the <em>Standards-Version</em> control
field, and so either these three components or the all
four components may be specified.<footnote>
- <p>
In the past, people specified the full version number
in the Standards-Version field, for example "2.3.0.0".
- Since minor patch-level changes don"t introduce new
+ 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>
package complies with the new standards you should update the
<tt>Standards-Version</tt> source package field and
release it.<footnote>
- <p>
See the file <file>upgrading-checklist</file> for
information about policy which has changed between
different versions of this document.
- </p>
</footnote>
</p>
</sect1>
<file>/usr/share/doc/build-essential/list</file> (which is
contained in the <tt>build-essential</tt>
package).<footnote>
- <p>Rationale:
+ Rationale:
<list compact="compact">
<item>
- <p>This allows maintaining the list separately
+ This allows maintaining the list separately
from the policy documents (the list does not
need the kind of control that the policy
documents do).
- </p>
</item>
<item>
- <p>
Having a separate package allows one to install
the build-essential packages on a machine, as
well as allowing other packages such as tasks to
require installation of the build-essential
packages using the depends relation.
- </p>
</item>
<item>
- <p>
The separate package allows bug reports against
the list to be categorized separately from
the policy management process in the BTS.
- </p>
</item>
</list>
- </p>
-
</footnote>
</p>
build. It is not necessary to list packages which are
required merely because some other package in the list of
build-time dependencies depends on them.<footnote>
- <p>
The reason for this is that dependencies change, and
you should list all those packages, and <em>only</em>
those packages that <em>you</em> need directly. What
them: installation of <package>libimlib2-dev</package>
will automatically ensure that all of its run-time
dependencies are satisfied.
- </p>
</footnote>
</p>
<taglist compact="compact">
<tag><em>stable</em></tag>
<item>
- <p>
This is the current "released" version of Debian
GNU/Linux. Once the distribution is
<em>stable</em> only security fixes and other
made to this distribution, the release number is
increased (for example: 2.2r1 becomes 2.2r2 then
2.2r3, etc).
- </p>
</item>
<tag><em>unstable</em></tag>
<item>
- <p>
This distribution value refers to the
<em>developmental</em> part of the Debian
distribution tree. New packages, new upstream
versions of packages and bug fixes go into the
<em>unstable</em> directory tree. Download from
this distribution at your own risk.
- </p>
</item>
<tag><em>testing</em></tag>
<item>
- <p>
This distribution value refers to the
<em>testing</em> part of the Debian distribution
tree. It receives its packages from the
than unstable, but still risky. It is not
possible to upload packages directly to
<em>testing</em>.
- </p>
</item>
<tag><em>frozen</em></tag>
<item>
- <p>
From time to time, the <em>testing</em>
distribution enters a state of "code-freeze" in
anticipation of release as a <em>stable</em>
fixes for existing or newly-discovered bugs will
be allowed. The exact details of this stage are
determined by the Release Manager.
- </p>
</item>
<tag><em>experimental</em></tag>
<item>
- <p>
The packages with this distribution value are
deemed by their maintainers to be high
risk. Oftentimes they represent early beta or
ready to be a part of the other parts of the
Debian distribution tree. Download at your own
risk.
- </p>
</item>
</taglist>
</p>
</sect1>
-
</sect>
+
</chapt>
+
<chapt id="versions"><heading>Version numbering</heading>
<p>
<p>
The version number format is:
- [<var>epoch</var><tt>:</tt>]<var>upstream_version</var>[<tt>-</tt><var>debian_revision</var>]
+ [<var>epoch</var><tt>:</tt>]<var>upstream_version</var>[<tt>-</tt><var>debian_revision</var>]
</p>
<p>
<p>
The <var>upstream_version</var> may contain only
alphanumerics<footnote>
- <p>Alphanumerics are <tt>A-Za-z0-9</tt> only.</p>
+ Alphanumerics are <tt>A-Za-z0-9</tt> only.
</footnote>
and the characters <tt>.</tt> <tt>+</tt> <tt>-</tt>
<tt>:</tt> (full stop, plus, hyphen, colon) and should
Maintainers should preserve the modification times of the
upstream source files in a package, as far as is reasonably
possible.<footnote>
- <p>
The rationale is that there is some information conveyed
by knowing the age of the file, for example, you could
recognize that some documentation is very old by looking
at the modification time, so it would be nice if the
modification time of the upstream source would be
preserved.
- </p>
</footnote>
</p>
</sect>
complete. This will ensure that if <tt>debian/rules
build</tt> is run again it will not rebuild the whole
program.<footnote>
- <p>
Another common way to do this is for <tt>build</tt>
to depend on <prgn>build-stamp</prgn> and to do
nothing else, and for the <prgn>build-stamp</prgn>
<tt>.PHONY</tt> target). See the documentation of
<prgn>make</prgn> for more information on phony
targets.
- </p>
</footnote>
</p>
</item>
<p>
The <tt>binary</tt> targets must be invoked as
root.<footnote>
- <p>
The <prgn>fakeroot</prgn> package often allows one
to build a package correctly even without being
root.
- </p>
</footnote>
</p>
</item>
<p>
The architectures we build on and build for are determined
by <prgn>make</prgn> variables using the utility
- <prgn>dpkg-architecture</prgn>. You can determine the
+ <qref id="pkg-dpkgarch"><prgn>dpkg-architecture</prgn></qref>.
+ You can determine the
Debian architecture and the GNU style architecture
specification string for the build machine (the machine type
we are building on) as well as for the host machine (the
supported <prgn>make</prgn> variables:
<list compact="compact">
<item>
- <p><tt>DEB_*_ARCH</tt> (the Debian architecture)</p>
+ <tt>DEB_*_ARCH</tt> (the Debian architecture)
</item>
<item>
- <p><tt>DEB_*_GNU_TYPE</tt> (the GNU style architecture
- specification string)</p>
+ <tt>DEB_*_GNU_TYPE</tt> (the GNU style architecture
+ specification string)
</item>
<item>
- <p><tt>DEB_*_GNU_CPU</tt> (the CPU part of
- <tt>DEB_*_GNU_TYPE</tt>)</p>
+ <tt>DEB_*_GNU_CPU</tt> (the CPU part of
+ <tt>DEB_*_GNU_TYPE</tt>)
</item>
<item>
- <p><tt>DEB_*_GNU_SYSTEM</tt> (the System part of
- <tt>DEB_*_GNU_TYPE</tt>)</p>
+ <tt>DEB_*_GNU_SYSTEM</tt> (the System part of
+ <tt>DEB_*_GNU_TYPE</tt>)
</list>
where <tt>*</tt> is either <tt>BUILD</tt> for specification of
the build machine or <tt>HOST</tt> for specification of the
<p>
This file records the changes to the Debian-specific parts of the
package<footnote>
- <p>
Though there is nothing stopping an author who is also
the Debian maintainer from using it for all their
changes, it will have to be renamed if the Debian and
upstream maintainers become different people. In such a
case, however, it might be better to maintain the
package as a non-native package.
- </p>
</footnote>.
</p>
<prgn>dpkg</prgn> changelog format (though there is
currently only one useful <var>keyword</var>,
<tt>urgency</tt>).<footnote>
- <p>
Recognised urgency values are <tt>low</tt>,
<tt>medium</tt>, <tt>high</tt> and <tt>emergency</tt>.
They have an effect on how quickly a package will be
considered for inclusion into the <tt>testing</tt>
distribution, and give an indication of the importance
of any fixes included in this upload.
- </p>
</footnote>
</p>
inclusion of this package into the Debian archive by
including the string: <tt>closes: Bug#<var>nnnnn</var></tt>
in the change details.<footnote>
- <p>
To be precise, the string should match the following
Perl regular expression:
<example>
Then all of the bug numbers listed will be closed by the
archive maintenance script (<prgn>katie</prgn>), or in
the case of an NMU, marked as fixed.
- </p>
</footnote>
</p>
<p>
The <var>date</var> should be in RFC822 format<footnote>
- <p>
This is generated by the <prgn>822-date</prgn>
program.
- </p>
</footnote>; it should include the time zone specified
numerically, with the time zone name or abbreviation
optionally present as a comment in parentheses.
It should not exist in a shipped source package, and so it
(and any backup files or temporary files such as
<file>files.new</file><footnote>
- <p>
<file>files.new</file> is used as a temporary file by
<prgn>dpkg-gencontrol</prgn> and
<prgn>dpkg-distaddfile</prgn> - they write a new
version of <tt>files</tt> here before renaming it,
to avoid leaving a corrupted copy if an error
- occurs
- </p>
+ occurs.
</footnote>) should be removed by the
<tt>clean</tt> target. It may also be wise to
ensure a fresh start by emptying or removing it at the
</p>
</footnote>, device special files, sockets or setuid or
setgid files.<footnote>
- <p>
Setgid directories are allowed.
- </p>
</footnote>
</p>
</sect>
should merely do the things that were left undone the first
time, if any, and exit with a success status if everything
is OK.<footnote>
- <p>
This is so that if an error occurs, the user interrupts
<prgn>dpkg</prgn> or some other unforeseen circumstance
happens you don't leave the user with a badly-broken
package when <prgn>dpkg</prgn> attempts to repeat the
action.
- </p>
</footnote>
</p>
</sect>
<p>
<list compact="compact">
<item>
- <p><var>new-preinst</var> <tt>install</tt></p>
+ <var>new-preinst</var> <tt>install</tt>
</item>
<item>
- <p><var>new-preinst</var> <tt>install</tt>
- <var>old-version</var></p>
+ <var>new-preinst</var> <tt>install</tt> <var>old-version</var>
</item>
<item>
- <p><var>new-preinst</var> <tt>upgrade</tt>
- <var>old-version</var></p>
+ <var>new-preinst</var> <tt>upgrade</tt> <var>old-version</var>
</item>
<item>
- <p><var>old-preinst</var> <tt>abort-upgrade</tt>
+ <var>old-preinst</var> <tt>abort-upgrade</tt>
<var>new-version</var>
- </p>
</item>
</list>
<p>
<list compact="compact">
<item>
- <p><var>postinst</var> <tt>configure</tt>
- <var>most-recently-configured-version</var></p>
+ <var>postinst</var> <tt>configure</tt>
+ <var>most-recently-configured-version</var>
</item>
<item>
- <p><var>old-postinst</var> <tt>abort-upgrade</tt>
- <var>new-version</var></p>
+ <var>old-postinst</var> <tt>abort-upgrade</tt>
+ <var>new-version</var>
</item>
<item>
- <p><var>conflictor's-postinst</var> <tt>abort-remove</tt>
+ <var>conflictor's-postinst</var> <tt>abort-remove</tt>
<tt>in-favour</tt> <var>package</var>
- <var>new-version</var></p>
+ <var>new-version</var>
</item>
<item>
- <p>
<var>deconfigured's-postinst</var>
<tt>abort-deconfigure</tt> <tt>in-favour</tt>
<var>failed-install-package</var> <var>version</var>
<tt>removing</tt> <var>conflicting-package</var>
<var>version</var>
- </p>
</item>
</list>
<p>
<list compact="compact">
<item>
- <p><var>prerm</var> <tt>remove</tt></p>
+ <var>prerm</var> <tt>remove</tt>
</item>
<item>
- <p><var>old-prerm</var> <tt>upgrade</tt>
- <var>new-version</var></p>
+ <var>old-prerm</var> <tt>upgrade</tt>
+ <var>new-version</var>
</item>
<item>
- <p><var>new-prerm</var> <tt>failed-upgrade</tt>
- <var>old-version</var></p>
+ <var>new-prerm</var> <tt>failed-upgrade</tt>
+ <var>old-version</var>
</item>
<item>
- <p><var>conflictor's-prerm</var> <tt>remove</tt>
+ <var>conflictor's-prerm</var> <tt>remove</tt>
<tt>in-favour</tt> <var>package</var>
- <var>new-version</var></p>
+ <var>new-version</var>
</item>
<item>
- <p>
<var>deconfigured's-prerm</var> <tt>deconfigure</tt>
<tt>in-favour</tt> <var>package-being-installed</var>
<var>version</var> <tt>removing</tt>
<var>conflicting-package</var>
<var>version</var>
- </p>
</item>
</list>
<p>
<list compact="compact">
<item>
- <p><var>postrm</var> <tt>remove</tt></p>
+ <var>postrm</var> <tt>remove</tt>
</item>
<item>
- <p><var>postrm</var> <tt>purge</tt></p>
+ <var>postrm</var> <tt>purge</tt>
</item>
<item>
- <p>
<var>old-postrm</var> <tt>upgrade</tt>
- <var>new-version</var></p>
+ <var>new-version</var>
</item>
<item>
- <p><var>new-postrm</var> <tt>failed-upgrade</tt>
- <var>old-version</var></p>
+ <var>new-postrm</var> <tt>failed-upgrade</tt>
+ <var>old-version</var>
</item>
<item>
- <p><var>new-postrm</var> <tt>abort-install</tt></p>
+ <var>new-postrm</var> <tt>abort-install</tt>
</item>
<item>
- <p><var>new-postrm</var> <tt>abort-install</tt>
- <var>old-version</var></p>
+ <var>new-postrm</var> <tt>abort-install</tt>
+ <var>old-version</var>
</item>
<item>
- <p><var>new-postrm</var> <tt>abort-upgrade</tt>
- <var>old-version</var></p>
+ <var>new-postrm</var> <tt>abort-upgrade</tt>
+ <var>old-version</var>
</item>
<item>
- <p>
<var>disappearer's-postrm</var> <tt>disappear</tt>
<var>overwriter</var>
- <var>overwriter-version</var></p></item>
+ <var>overwriter-version</var>
+ </item>
</list>
</p>
- <sect id="unpackphase"><heading>Details of unpack phase of
- installation or upgrade
- </heading>
+ <sect id="unpackphase">
+ <heading>Details of unpack phase of installation or upgrade</heading>
<p>
The procedure on installation/upgrade/overwrite/disappear
<enumlist>
<item>
- <p>
<enumlist>
<item>
- <p>If a version of the package is already
- installed, call
+ If a version of the package is already installed, call
<example compact="compact">
<var>old-prerm</var> upgrade <var>new-version</var>
- </example></p>
+ </example>
</item>
<item>
- <p>
If the script runs but exits with a non-zero
exit status, <prgn>dpkg</prgn> will attempt:
<example compact="compact">
<example compact="compact">
<var>old-postinst</var> abort-upgrade <var>new-version</var>
</example>
- </p>
</item>
</enumlist>
- </p>
</item>
+
<item>
- <p>If a "conflicting" package is being removed at the same time:
+ If a "conflicting" package is being removed at the same time:
<enumlist>
<item>
- <p>
If any packages depended on that conflicting
package and <tt>--auto-deconfigure</tt> is
specified, call, for each such package:
The deconfigured packages are marked as
requiring configuration, so that if
<tt>--install</tt> is used they will be
- configured again if possible.</p>
+ configured again if possible.
</item>
<item>
- <p>To prepare for removal of the conflicting package, call:
+ To prepare for removal of the conflicting package, call:
<example compact="compact">
<var>conflictor's-prerm</var> remove \
in-favour <var>package</var> <var>new-version</var>
<var>conflictor's-postinst</var> abort-remove \
in-favour <var>package</var> <var>new-version</var>
</example>
- </p>
</item>
</enumlist>
- </p>
</item>
+
<item>
- <p>
<enumlist>
<item>
- <p>If the package is being upgraded, call:
+ If the package is being upgraded, call:
<example compact="compact">
<var>new-preinst</var> upgrade <var>old-version</var>
- </example></p>
+ </example>
</item>
<item>
- <p>
Otherwise, if the package had some configuration
files from a previous version installed (i.e., it
is in the "configuration files only" state):
<example compact="compact">
<var>new-preinst</var> install <var>old-version</var>
- </example></p>
-
+ </example>
+ </item>
<item>
- <p>Otherwise (i.e., the package was completely purged):
+ Otherwise (i.e., the package was completely purged):
<example compact="compact">
<var>new-preinst</var> install
</example>
<var>new-postrm</var> abort-install <var>old-version</var>
<var>new-postrm</var> abort-install
</example>
- </p>
</item>
</enumlist>
- </p>
</item>
+
<item>
<p>
The new package's files are unpacked, overwriting any
lead to "missing" programs if, for example, a package
is installed which overwrites a file from another
package, and is then removed again.<footnote>
- <p>
Part of the problem is due to what is arguably a
bug in <prgn>dpkg</prgn>.
- </p>
</footnote>
</p>
to a directory or vice versa; instead, the existing
state (symlink or not) will be left alone and
<prgn>dpkg</prgn> will follow the symlink if there is
- one.</p>
+ one.
+ </p>
</item>
<item>
<p>
<enumlist>
<item>
- <p>If the package is being upgraded, call
+ If the package is being upgraded, call
<example compact="compact">
<var>old-postrm</var> upgrade <var>new-version</var>
</example>
- </p>
</item>
<item>
-
<p>If this fails, <prgn>dpkg</prgn> will attempt:
+
If this fails, <prgn>dpkg</prgn> will attempt:
<example compact="compact">
<var>new-postrm</var> failed-upgrade <var>old-version</var>
</example>
<example compact="compact">
<var>old-preinst</var> abort-upgrade <var>new-version</var>
</example>
- </p>
</item>
</enumlist>
</p>
+
<p>
This is the point of no return - if
<prgn>dpkg</prgn> gets this far, it won't back off
things that are irreversible.
</p>
</item>
+
<item>
- <p>
Any files which were in the old version of the package
- but not in the new are removed.</p>
+ but not in the new are removed.
</item>
+
<item>
- <p>The new file list replaces the old.</p>
+ The new file list replaces the old.
</item>
+
<item>
- <p>The new maintainer scripts replace the old.</p>
+ The new maintainer scripts replace the old.
</item>
<item>
- <p>Any packages all of whose files have been overwritten during the
- installation, and which aren't required for
+ Any packages all of whose files have been overwritten
+ during the installation, and which aren't required for
dependencies, are considered to have been removed.
For each such package
<enumlist>
<item>
-
<p><prgn>dpkg</prgn> calls:
+
<prgn>dpkg</prgn> calls:
<example compact="compact">
<var>disappearer's-postrm</var> disappear \
<var>overwriter</var> <var>overwriter-version</var>
</example>
- </p>
</item>
<item>
- <p>The package's maintainer scripts are removed.
- </p>
+ The package's maintainer scripts are removed.
</item>
<item>
- <p>
It is noted in the status database as being in a
sane state, namely not installed (any conffiles
it may have are ignored, rather than being
called, because <prgn>dpkg</prgn> doesn't know
in advance that the package is going to
vanish.
- </p>
</item>
</enumlist>
- </p>
</item>
+
<item>
- <p>
Any files in the package we're unpacking that are also
listed in the file lists of other packages are removed
from those lists. (This will lobotomize the file list
of the "conflicting" package if there is one.)
- </p>
</item>
+
<item>
- <p>
The backup files made during installation, above, are
deleted.
- </p>
</item>
<item>
</item>
<item>
- <p>
If there was a conflicting package we go and do the
removal actions (described below), starting with the
removal of the conflicting package's files (any that
are also in the package being installed have already
been removed from the conflicting package's file list,
and so do not get removed now).
- </p>
</item>
</enumlist>
</p>
<p>
<enumlist>
<item>
- <p>
<example compact="compact">
<var>prerm</var> remove
</example>
- </p>
</item>
<item>
- <p>
The package's files are removed (except <tt>conffile</tt>s).
- </p>
</item>
<item>
- <p>
<example compact="compact">
<var>postrm</var> remove
</example>
- </p>
</item>
<item>
<p>
that packages which have no <prgn>postrm</prgn> and no
<tt>conffile</tt>s are automatically purged when
removed, as there is no difference except for the
- <prgn>dpkg</prgn> status.</p>
+ <prgn>dpkg</prgn> status.
+ </p>
</item>
<item>
- <p>
The <tt>conffile</tt>s and any backup files
(<tt>~</tt>-files, <tt>#*#</tt> files,
<tt>%</tt>-files, <tt>.dpkg-{old,new,tmp}</tt>, etc.)
- are removed.</p>
+ are removed.
</item>
<item>
- <p>
<example compact="compact">
<var>postrm</var> purge
</example>
- </p>
</item>
<item>
- <p>The package's file list is removed.</p>
+ The package's file list is removed.
</item>
</enumlist>
+
No attempt is made to unwind after errors during
removal.
</p>
</chapt>
- <chapt id="relationships"><heading>Declaring relationships between
- packages</heading>
+ <chapt id="relationships">
+ <heading>Declaring relationships between packages</heading>
- <sect id="depsyntax"><heading>Syntax of relationship fields
- </heading>
+ <sect id="depsyntax">
+ <heading>Syntax of relationship fields</heading>
<p>
These fields all have a uniform syntax. They are a list of
package to provide a significant amount of
functionality.
</p>
+
<p>
The <tt>Depends</tt> field should also be used if the
<prgn>postinst</prgn>, <prgn>prerm</prgn> or
<tag><tt>Recommends</tt></tag>
<item>
- <p>This declares a strong, but not absolute, dependency.
+ <p>
+ This declares a strong, but not absolute, dependency.
</p>
<p>
The <tt>Recommends</tt> field should list packages
that would be found together with this one in all but
- unusual installations.</p>
+ unusual installations.
+ </p>
</item>
<tag><tt>Suggests</tt></tag>
<item>
- <p>
This is used to declare that one package may be more
useful with one or more others. Using this field
tells the packaging system and the user that the
listed packages are related to this one and can
perhaps enhance its usefulness, but that installing
this one without them is perfectly reasonable.
- </p>
</item>
<tag><tt>Enhances</tt></tag>
<item>
- <p>
This field is similar to Suggests but works in the
opposite direction. It is used to declare that a
package can enhance the functionality of another
package.
- </p>
</item>
<tag><tt>Pre-Depends</tt></tag>
<prgn>preinst</prgn> script depends on the named
package. It is best to avoid this situation if
possible.
+ </p>
</item>
</taglist>
</p>
+
<p>
When selecting which level of dependency to use you should
consider how important the depended-on package is to the
Recommendations, as appropriate to the components' relative
importance.
</p>
+ </sect>
-
- <sect id="conflicts"><heading>Conflicting binary packages -
- <tt>Conflicts</tt></heading>
+ <sect id="conflicts">
+ <heading>Conflicting binary packages - <tt>Conflicts</tt></heading>
<p>
When one binary package declares a conflict with another
The effect is as if the package(s) which provide a
particular virtual package name had been listed by name
everywhere the virtual package name appears. (See also <ref
- id="virtual_pkg_sect">)
+ id="virtual_pkg">)
</p>
<p>
<taglist>
<tag><tt>Build-Depends</tt>, <tt>Build-Conflicts</tt></tag>
<item>
- <p>
The <tt>Build-Depends</tt> and
<tt>Build-Conflicts</tt> fields must be satisfied when
any of the following targets is invoked:
<tt>build</tt>, <tt>clean</tt>, <tt>binary</tt>,
<tt>binary-arch</tt>, <tt>build-arch</tt>,
<tt>build-indep</tt> and <tt>binary-indep</tt>.
- </p>
</item>
<tag><tt>Build-Depends-Indep</tt>,
<tt>Build-Conflicts-Indep</tt></tag>
<item>
- <p>
The <tt>Build-Depends-Indep</tt> and
<tt>Build-Conflicts-Indep</tt> fields must be
satisfied when any of the following targets is
invoked: <tt>build</tt>, <tt>clean</tt>,
<tt>build-indep</tt>, <tt>binary</tt> and
<tt>binary-indep</tt>.
- </p>
</item>
</taglist>
</p>
</sect>
+
</chapt>
- <chapt id="conffiles"><heading>Configuration file handling
- </heading>
+ <chapt id="conffiles">
+ <heading>Configuration file handling</heading>
<p>
This chapter has been superseded by <ref id="config-files">.
</p>
+ </chapt>
<chapt id="sharedlibs"><heading>Shared libraries</heading>
<package><var>libraryname</var><var>soversion</var></package>, where
<file><var>soversion</var></file> is the version number in the
soname of the shared library<footnote>
- <p>
The soname is the shared object name: it's the thing
that has to match exactly between building an executable
and running it for the dynamic linker to be able run the
program. For example, if the soname of the library is
<file>libfoo.so.6</file>, the library package would be
called <file>libfoo6</file>.
- </p>
</footnote>.
Alternatively, if it would be confusing to directly append
<var>soversion</var> to <var>libraryname</var> (e.g. because
time that <prgn>dpkg</prgn> installs it and the time that
<prgn>ldconfig</prgn> is run in the <prgn>postinst</prgn>
script.<footnote>
- <p>
The package management system requires the library to be
placed before the symbolic link pointing to it in the
<file>.deb</file> file. This is so that when
reorders the files itself as necessary when building a
package. Thus it is no longer important to concern
oneself with the order of file creation.
- </p>
</footnote>
</p>
- <sect1 id="ldconfig">
- <heading><tt>ldconfig</tt></heading>
+ <sect1 id="ldconfig">
+ <heading><tt>ldconfig</tt></heading>
- <p>
- Any package installing shared libraries in one of the default
- library directories of the dynamic linker (which are currently
- <file>/usr/lib</file> and <file>/lib</file>) or a directory that is
- listed in <file>/etc/ld.so.conf</file><footnote>
- <p>
+ <p>
+ Any package installing shared libraries in one of the default
+ library directories of the dynamic linker (which are currently
+ <file>/usr/lib</file> and <file>/lib</file>) or a directory that is
+ listed in <file>/etc/ld.so.conf</file><footnote>
These are currently
<list compact="compact">
- <item><p>/usr/X11R6/lib/Xaw3d</p></item>
- <item><p>/usr/local/lib</p></item>
- <item><p>/usr/lib/libc5-compat</p></item>
- <item><p>/lib/libc5-compat</p></item>
- <item><p>/usr/X11R6/lib</p></item>
+ <item>/usr/X11R6/lib/Xaw3d</item>
+ <item>/usr/local/lib</item>
+ <item>/usr/lib/libc5-compat</item>
+ <item>/lib/libc5-compat</item>
+ <item>/usr/X11R6/lib</item>
</list>
- </p>
- </footnote>
- must use <prgn>ldconfig</prgn> to update the shared library
- system.
- </p>
+ </footnote>
+ must use <prgn>ldconfig</prgn> to update the shared library
+ system.
+ </p>
- <p>
- The package must call <prgn>ldconfig</prgn> in the
- <prgn>postinst</prgn> script if the first argument is
- <tt>configure</tt>; the <prgn>postinst</prgn> script may
- optionally invoke <prgn>ldconfig</prgn> at other times. The
- package should call <prgn>ldconfig</prgn> in the
- <prgn>postrm</prgn> script if the first argument is
- <tt>remove</tt>. The maintainer scripts must not invoke
- <prgn>ldconfig</prgn> under any circumstances other than those
- described in this paragraph.<footnote>
- <p>During install or upgrade, the preinst is called before
- the new files are installed, so calling "ldconfig" is
- pointless. The preinst of an existing package can also be
- called if an upgrade fails. However, this happens during
- the critical time when a shared libs may exist on-disk
- under a temporary name. Thus, it is dangerous and
- forbidden by current policy to call "ldconfig" at this
- time.
- </p>
- <p>When a package is installed or upgraded, "postinst
- configure" runs after the new files are safely on-disk.
- Since it is perfectly safe to invoke ldconfig
- unconditionally in a postinst, it is OK for a package to
- simply put ldconfig in its postinst without checking the
- argument. The postinst can also be called to recover from
- a failed upgrade. This happens before any new files are
- unpacked, so there is no reason to call "ldconfig" at this
- point.
- </p>
- <p>For a package that is being removed, prerm is
- called with all the files intact, so calling ldconfig is
- useless. The other calls to "prerm" happen in the case of
- upgrade at a time when all the files of the old package
- are on-disk, so again calling "ldconfig" is pointless.
- </p>
- <p>postrm, on the other hand, is called with the "remove"
- argument just after the files are removed, so this is the
- proper time to call "ldconfig" to notify the system of the
- fact shared libraries from the package are removed.
- The postrm can be called at several other times. At the
- time of "postrm purge", "postrm abort-install", or "postrm
- abort-upgrade", calling "ldconfig" is useless because the
- shared lib files are not on-disk. However, when "postrm"
- is invoked with arguments "upgrade", "failed-upgrade", or
- "disappear", a shared lib may exist on-disk under a
- temporary filename.
- </p>
- </footnote>
- </p>
- </sect1>
+ <p>
+ The package must call <prgn>ldconfig</prgn> in the
+ <prgn>postinst</prgn> script if the first argument is
+ <tt>configure</tt>; the <prgn>postinst</prgn> script may
+ optionally invoke <prgn>ldconfig</prgn> at other times. The
+ package should call <prgn>ldconfig</prgn> in the
+ <prgn>postrm</prgn> script if the first argument is
+ <tt>remove</tt>. The maintainer scripts must not invoke
+ <prgn>ldconfig</prgn> under any circumstances other than those
+ described in this paragraph.<footnote>
+ <p>
+ During install or upgrade, the preinst is called before
+ the new files are installed, so calling "ldconfig" is
+ pointless. The preinst of an existing package can also be
+ called if an upgrade fails. However, this happens during
+ the critical time when a shared libs may exist on-disk
+ under a temporary name. Thus, it is dangerous and
+ forbidden by current policy to call "ldconfig" at this
+ time.
+ </p>
+
+ <p>
+ When a package is installed or upgraded, "postinst
+ configure" runs after the new files are safely on-disk.
+ Since it is perfectly safe to invoke ldconfig
+ unconditionally in a postinst, it is OK for a package to
+ simply put ldconfig in its postinst without checking the
+ argument. The postinst can also be called to recover from
+ a failed upgrade. This happens before any new files are
+ unpacked, so there is no reason to call "ldconfig" at this
+ point.
+ </p>
+
+ <p>
+ For a package that is being removed, prerm is
+ called with all the files intact, so calling ldconfig is
+ useless. The other calls to "prerm" happen in the case of
+ upgrade at a time when all the files of the old package
+ are on-disk, so again calling "ldconfig" is pointless.
+ </p>
+
+ <p>
+ postrm, on the other hand, is called with the "remove"
+ argument just after the files are removed, so this is the
+ proper time to call "ldconfig" to notify the system of the
+ fact shared libraries from the package are removed.
+ The postrm can be called at several other times. At the
+ time of "postrm purge", "postrm abort-install", or "postrm
+ abort-upgrade", calling "ldconfig" is useless because the
+ shared lib files are not on-disk. However, when "postrm"
+ is invoked with arguments "upgrade", "failed-upgrade", or
+ "disappear", a shared lib may exist on-disk under a
+ temporary filename.
+ </p>
+ </footnote>
+ </p>
+ </sect1>
</sect>
<heading>Dependencies between the packages of the same library</heading>
<p>
- Typically the development version should also have an exact
+ Typically the development version should have an exact
version dependency on the runtime library, to make sure that
compilation and linking happens correctly. The
<tt>${Source-Version}</tt> substitution variable can be
useful for this purpose.
</p>
-
- <p>
- Packages which use the shared library should have a
- dependency on the name of the shared library package,
- <file><var>libraryname</var><var>soversion</var></file>. When
- the soname changes you can have both versions of the library
- installed while migrating from the old library to the new.
- </p>
</sect>
<sect id="sharedlibs-shlibdeps">
<list>
<item>
<p><file>debian/shlibs.local</file></p>
+
<p>
This lists overrides for this package. Its use is
described below (see <ref id="shlibslocal">).
<item>
<p><file>/etc/dpkg/shlibs.override</file></p>
+
<p>
This lists global overrides. This list is normally
empty. It is maintained by the local system
<item>
<p><file>DEBIAN/shlibs</file> files in the "build directory"</p>
+
<p>
When packages are being built, any
<file>debian/shlibs</file> files are copied into the
given the name <file>shlibs</file>. These files give
details of any shared libraries included in the
package.<footnote>
- <p>
An example may help here. Let us say that the
source package <tt>foo</tt> generates two binary
packages, <tt>libfoo2</tt> and
all of the individual binary packages'
<tt>shlibs</tt> files have been installed into the
build directory.
- </p>
</footnote>
</p>
</item>
<item>
<p><file>/var/lib/dpkg/info/*.shlibs</file></p>
+
<p>
These are the <file>shlibs</file> files corresponding to
all of the packages installed on the system, and are
<item>
<p><file>/etc/dpkg/shlibs.default</file></p>
+
<p>
This file lists any shared libraries whose packages
have failed to provide correct <file>shlibs</file> files.
</example>
Otherwise, you will need to explicitly list the compiled
binaries and libraries.<footnote>
- <p>
If you are using <tt>debhelper</tt>, the
<prgn>dh_shlibdeps</prgn> program will do this work for
you. It will also correctly handle multi-binary
packages.
- </p>
</footnote>
</p>
dynamic linker, and is usually of the form
<tt><var>name</var>.so.<var>major-version</var></tt>, in our
example, <tt>libz.so.1</tt>.<footnote>
- <p>
This can be determined using the command
<example compact="compact">
objdump -p /usr/lib/libz.so.1.1.3 | grep SONAME
</example>
- </p>
</footnote>
The version part is the part which comes after
<tt>.so.</tt>, so in our case, it is <tt>1</tt>.
<file>shlibs</file> file in the control area directly from
<file>debian/rules</file> without using a <file>debian/shlibs</file>
file at all,<footnote>
- <p>
This is what <prgn>dh_makeshlibs</prgn> in the
<tt>debhelper</tt> suite does.
- </p>
</footnote>
since the <file>debian/shlibs</file> file itself is ignored by
<prgn>dpkg-shlibdeps</prgn>.
<heading>Filesystem hierarchy</heading>
- <sect1>
+ <sect1 id="fhs">
<heading>Filesystem Structure</heading>
<p>
<taglist>
<tag><tt>start</tt></tag>
- <item><p>start the service,</p></item>
+ <item>start the service,</item>
<tag><tt>stop</tt></tag>
- <item><p>stop the service,</p></item>
+ <item>stop the service,</item>
<tag><tt>restart</tt></tag>
- <item><p>stop and restart the service if it's already
- running, otherwise start the service</p></item>
+ <item>stop and restart the service if it's already running,
+ otherwise start the service</item>
<tag><tt>reload</tt></tag>
<item><p>cause the configuration of the service to be
reloaded without actually stopping and restarting
- the service,</p></item>
+ the service,</item>
<tag><tt>force-reload</tt></tag>
- <item><p>cause the configuration to be reloaded if the
+ <item>cause the configuration to be reloaded if the
service supports this, otherwise restart the
- service.</p></item>
+ service.</item>
</taglist>
The <tt>start</tt>, <tt>stop</tt>, <tt>restart</tt>, and
<tt>force-reload</tt> options should be supported by all
scripts in <file>/etc/init.d</file>, the <tt>reload</tt>
- option is optional.</p>
+ option is optional.
+ </p>
<p>
The <file>init.d</file> scripts should ensure that they will
service is already running, or with <tt>stop</tt> when it
isn't, and that they don't kill unfortunately-named user
processes. The best way to achieve this is usually to use
- <prgn>start-stop-daemon</prgn>.</p>
+ <prgn>start-stop-daemon</prgn>.
+ </p>
<p>
If a service reloads its configuration automatically (as
in the case of <prgn>cron</prgn>, for example), the
<tt>reload</tt> option of the <file>init.d</file> script
should behave as if the configuration has been reloaded
- successfully.</p>
+ successfully.
+ </p>
<p>
The <file>/etc/init.d</file> scripts must be treated as
scripts such as <prgn>postinst</prgn>, <prgn>prerm</prgn>
and <prgn>postrm</prgn>.
</p>
+
<p>
Directly managing the /etc/rc?.d links and directly
invoking the <file>/etc/init.d/</file> initscripts should
be done only by packages providing the initscript
subsystem (such as <prgn>sysvinit</prgn> and
<prgn>file-rc</prgn>).
-
</p>
<sect2>
removal of <file>/etc/rc<var>n</var>.d</file> symbolic links,
or their functional equivalent if another method is being
used. This may be used by maintainers in their packages'
- <prgn>postinst</prgn> and <prgn>postrm</prgn> scripts.</p>
+ <prgn>postinst</prgn> and <prgn>postrm</prgn> scripts.
+ </p>
<p>
You must not include any <file>/etc/rc<var>n</var>.d</file>
</example>. Note that if your package changes runlevels
or priority, you may have to remove and recreate the links,
since otherwise the old links may persist. Refer to the
- documentation of <prgn>update-rc.d</prgn></p>
+ documentation of <prgn>update-rc.d</prgn>.
+ </p>
<p>
This will use a default sequence number of 20. If it does
stop and otherwise manage services. This program may be
used by maintainers in their packages' scripts.
</p>
+
<p>
The use of <prgn>invoke-rc.d</prgn> to invoke the
<file>/etc/init.d/*</file> initscripts is strongly
recommended<footnote>
- <p>
In the future, the use of invoke-rc.d to invoke
initscripts shall be made mandatory. Maintainers are
advised to switch to invoke-rc.d as soon as
- possible.</p>
+ possible.
</footnote>, instead of calling them directly.
</p>
to start or restart a service out of its intended
runlevels.
</p>
+
<p>
Most packages will simply need to change:
<example compact="compact">/etc/init.d/<package>
else
/etc/init.d/<var>package</var> <action>
fi
- </example></p>
+ </example>
+ </p>
+
<p>
A package should register its initscript services using
<prgn>update-rc.d</prgn> before it tries to invoke them
using <prgn>invoke-rc.d</prgn>. Invocation of
unregistered services may fail.
</p>
+
<p>
For more information about using
<prgn>invoke-rc.d</prgn>, please consult its manpage
</sect2>
</sect1>
-
<sect1>
<heading>Boot-time initialization</heading>
boot. This has been deprecated in favour of links from
<file>/etc/rcS.d</file> to files in <file>/etc/init.d</file> as
described in <ref id="/etc/init.d">. Packages must not
- place files in <file>/etc/rc.boot</file>.</p>
+ place files in <file>/etc/rc.boot</file>.
+ </p>
+ </sect1>
<sect1>
<heading>Example</heading>
<p>
<list>
<item>
- <p>
Every message should fit in one line (fewer than 80
characters), start with a capital letter and end with
a period (<tt>.</tt>) and line feed (<tt>"\n"</tt>).
- </p>
</item>
<item>
- <p>
If you want to express that the computer is working on
something (that is, performing a specific task, not
starting or stopping a program), we use an "ellipsis"
(three dots: <tt>...</tt>). Note that we don't insert
spaces before or after the dots. If the task has been
completed we write <tt>done.</tt> and a line feed.
- </p>
</item>
<item>
- <p>
Design your messages as if the computer is telling you
what he is doing (let him be polite :-), but don't
mention "him" directly. For example, if you think of
<example compact="compact">
Starting network daemons: nfsd mountd.
</example>
- </p>
</item>
</list>
</p>
are kept on the system in this situation.</p>
</sect>
- <sect>
+ <sect id="menus">
<heading>Menus</heading>
- <p>
- Menu entries should follow the current menu policy found in
- the <tt>menu-policy</tt> files in the <tt>debian-policy</tt>
- package. It may also be found on the Debian FTP site
- <ftpsite>ftp.debian.org</ftpsite> as the file
- <ftppath>/debian/doc/package-developer/menu-policy.txt.gz</ftppath>,
- or in the equivalent location on your local mirror.
- </p>
-
<p>
The Debian <tt>menu</tt> package provides a standard
interface between packages providing applications and
operation should register a menu entry for those
applications, so that users of the <tt>menu</tt> package
will automatically get menu entries in their window
- managers, as well in shells like <tt>pdmenu</tt>.</p>
+ managers, as well in shells like <tt>pdmenu</tt>.
+ </p>
+
+ <p>
+ Menu entries should follow the current menu policy.
+ </p>
+
+ <p>
+ The menu policy can be found in the <tt>menu-policy</tt>
+ files in the <tt>debian-policy</tt> package.
+ They are also available from the Debian web mirrors at
+ <tt><url name="/doc/packaging-manuals/menu-policy/"
+ id="http://www.debian.org/doc/packaging-manuals/menu-policy/"></tt>
+ and from the Debian archive mirrors at
+ <tt><url name="/doc/package-developer/menu-policy.txt.gz"
+ id="http://ftp.debian.org/debian/doc/package-developer/menu-policy.txt.gz"></tt>.
+ </p>
<p>
Please also refer to the <em>Debian Menu System</em>
</p>
</sect>
- <sect>
+ <sect id="mime">
<heading>Multimedia handlers</heading>
- <p>
- Packages which provide the ability to view/show/play,
- compose, edit or print MIME types should register themselves
- as such following the current MIME support policy found in
- the <tt>mime-policy</tt> files in the <tt>debian-policy</tt>
- package. It may also be found on the Debian FTP site
- <ftpsite>ftp.debian.org</ftpsite> as the file
- <ftppath>/debian/doc/package-developer/mime-policy.txt.gz</ftppath>,
- or in the equivalent location on your local mirror.
- </p>
-
<p>
MIME (Multipurpose Internet Mail Extensions, RFCs 2045-2049)
is a mechanism for encoding files and data streams and
view, edit or display MIME types they don't support
directly.
</p>
+
+ <p>
+ Packages which provide the ability to view/show/play,
+ compose, edit or print MIME types should register themselves
+ as such following the current MIME support policy.
+ </p>
+
+ <p>
+ The MIME support policy can be found in the <tt>mime-policy</tt>
+ files in the <tt>debian-policy</tt> package.
+ They are also available from the Debian web mirrors at
+ <tt><url name="/doc/packaging-manuals/mime-policy/"
+ id="http://www.debian.org/doc/packaging-manuals/mime-policy/"></tt>
+ and from the Debian archive mirrors at
+ <tt><url name="/doc/package-developer/mime-policy.txt.gz"
+ id="http://ftp.debian.org/debian/doc/package-developer/mime-policy.txt.gz"></tt>.
+ </p>
+
</sect>
<sect>
<taglist>
<tag><tt><--</tt></tag>
- <item><p>delete the character to the left of the cursor</p></item>
+ <item>delete the character to the left of the cursor</item>
<tag><tt>Delete</tt></tag>
- <item><p>delete the character to the right of the cursor</p></item>
+ <item>delete the character to the right of the cursor</item>
<tag><tt>Control+H</tt></tag>
- <item><p>emacs: the help prefix</p></item>
+ <item>emacs: the help prefix</item>
</taglist>
The interpretation of any keyboard events should be
<p>
<list>
- <item><p><tt><--</tt> generates <tt>KB_BackSpace</tt>
- in X.</p></item>
+ <item>
+ <tt><--</tt> generates <tt>KB_BackSpace</tt> in X.
+ </item>
- <item><p><tt>Delete</tt> generates <tt>KB_Delete</tt> in
- X.</p></item>
+ <item>
+ <tt>Delete</tt> generates <tt>KB_Delete</tt> in X.
+ </item>
<item>
- <p>
X translations are set up to make
<tt>KB_Backspace</tt> generate ASCII DEL, and to make
<tt>KB_Delete</tt> generate <tt>ESC [ 3 ~</tt> (this
using <prgn>xrdb</prgn> on all local X displays, not
using the application defaults, so that the
translation resources used correspond to the
- <prgn>xmodmap</prgn> settings.</p></item>
+ <prgn>xmodmap</prgn> settings.
+ </item>
<item>
- <p>
The Linux console is configured to make
<tt><--</tt> generate DEL, and <tt>Delete</tt>
- generate <tt>ESC [ 3 ~</tt>.</p></item>
+ generate <tt>ESC [ 3 ~</tt>.
+ </item>
<item>
- <p>
X applications are configured so that <tt><</tt>
deletes left, and <tt>Delete</tt> deletes right. Motif
- applications already work like this.</p></item>
+ applications already work like this.
+ </item>
- <item><p>Terminals should have <tt>stty erase ^?</tt> .</p></item>
+ <item>
+ Terminals should have <tt>stty erase ^?</tt> .
+ </item>
<item>
- <p>
The <tt>xterm</tt> terminfo entry should have <tt>ESC
[ 3 ~</tt> for <tt>kdch1</tt>, just as for
- <tt>TERM=linux</tt> and <tt>TERM=vt220</tt>.</p></item>
+ <tt>TERM=linux</tt> and <tt>TERM=vt220</tt>.
+ </item>
<item>
- <p>
Emacs is programmed to map <tt>KB_Backspace</tt> or
the <tt>stty erase</tt> character to
<tt>delete-backward-char</tt>, and <tt>KB_Delete</tt>
or <tt>kdch1</tt> to <tt>delete-forward-char</tt>, and
- <tt>^H</tt> to <tt>help</tt> as always.</p></item>
+ <tt>^H</tt> to <tt>help</tt> as always.
+ </item>
<item>
- <p>
Other applications use the <tt>stty erase</tt>
character and <tt>kdch1</tt> for the two delete keys,
with ASCII DEL being "delete previous character" and
<tt>kdch1</tt> being "delete character under
- cursor".</p></item>
+ cursor".
+ </item>
</list>
</p>
<p>
<list>
<item>
- <p>
Some terminals have a <tt><--</tt> key that cannot
be made to produce anything except <tt>^H</tt>. On
these terminals Emacs help will be unavailable on
<tt>^H</tt> (assuming that the <tt>stty erase</tt>
character takes precedence in Emacs, and has been set
correctly). <tt>M-x help</tt> or <tt>F1</tt> (if
- available) can be used instead.</p></item>
+ available) can be used instead.
+ </item>
<item>
- <p>
Some operating systems use <tt>^H</tt> for <tt>stty
erase</tt>. However, modern telnet versions and all
rlogin versions propagate <tt>stty</tt> settings, and
almost all UNIX versions honour <tt>stty erase</tt>.
Where the <tt>stty</tt> settings are not propagated
correctly, things can be made to work by using
- <tt>stty</tt> manually.</p></item>
+ <tt>stty</tt> manually.
+ </item>
<item>
- <p>
Some systems (including previous Debian versions) use
<prgn>xmodmap</prgn> to arrange for both
<tt><--</tt> and <tt>Delete</tt> to generate
using their resources when things are the other way
around. On displays configured like this
<tt>Delete</tt> will not work, but <tt><--</tt>
- will.</p></item>
+ will.
+ </item>
<item>
- <p>
Some operating systems have different <tt>kdch1</tt>
settings in their <tt>terminfo</tt> database for
<tt>xterm</tt> and others. On these systems the
<tt>Delete</tt> key will not work correctly when you
log in from a system conforming to our policy, but
- <tt><--</tt> will.</p></item>
+ <tt><--</tt> will.
+ </item>
</list>
</p>
</sect>
reasonable defaults. (That's because these environment
variables would have to be set in a system-wide
configuration file like <file>/etc/profile</file>, which is not
- supported by all shells.)</p>
+ supported by all shells.)
+ </p>
<p>
If a program usually depends on environment variables for its
(e.g., if the source code of a non-free program is not
available), the program must be replaced by a small
"wrapper" shell script which sets the environment variables
- if they are not already defined, and calls the original program.</p>
+ if they are not already defined, and calls the original program.
+ </p>
<p>
Here is an example of a wrapper script for this purpose:
Furthermore, as <file>/etc/profile</file> is a configuration
file of the <prgn>base-files</prgn> package, other packages must not
put any environment variables or other commands into that
- file.</p>
+ file.
+ </p>
</sect>
+
</chapt>
+
<chapt id="files">
<heading>Files</heading>
<prgn>install</prgn>, or by calling <prgn>strip</prgn> on
the binaries after they have been copied into
<file>debian/tmp</file> but before the tree is made into a
- package.</p>
+ package.
+ </p>
<p>
Although binaries in the build tree should be compiled with
contain several flags to change how a package is compiled
and built.
</p>
+
<p>
<taglist>
<tag>noopt</tag>
<item>
- <p>
The presence of this string means that the package
should be complied with a minimum of optimization.
For C programs, it is best to add <tt>-O0</tt>
default). Some programs might fail to build or run at
this level of optimization; it may be necessary to
use <tt>-O1</tt>, for example.
- </p>
</item>
<tag>nostrip</tag>
<item>
- <p>
This string means that the debugging symbols should
not be stripped from the binary during installation,
so that debugging information may be included in the package.
- </p>
</item>
</taglist>
</p>
+
<p>
The following makefile snippet is an example of how one may
implement the build options; you will probably have to
will need to be compiled twice.
</p>
-
<p>
You must specify the gcc option <tt>-D_REENTRANT</tt>
when building a library (either static or shared) to make
function perfectly well when stripped, since the symbols for
dynamic linking are in a separate part of the ELF object
file.<footnote>
- <p>
You might also want to use the options
<tt>--remove-section=.comment</tt> and
<tt>--remove-section=.note</tt> on both shared libraries
and executables, and <tt>--strip-debug</tt> on static
libraries.
- </p>
</footnote>
</p>
rules that govern ordinary shared libraries, except that
they must not be installed executable and should be
stripped.<footnote>
- <p>
A common example are the so-called "plug-ins",
internal shared objects that are dynamically loaded by
programs using <manref name="dlopen" section="3">.
- </p>
</footnote>
</p>
a library (such as library dependency information for static
linking). Also, they're <em>essential</em> for programs
using <tt>libltdl</tt>.<footnote>
- <p>
Although <prgn>libtool</prgn> is fully capable of
linking against shared libraries which don't have
<tt>.la</tt> files, as it is a mere shell script it can
<file>.la</file> files also store information about
inter-library dependencies which cannot necessarily be
derived after the <file>.la</file> file is deleted.
- </p>
</footnote>
</p>
All command scripts, including the package maintainer
scripts inside the package and used by <prgn>dpkg</prgn>,
should have a <tt>#!</tt> line naming the shell to be used
- to interpret them.</p>
+ to interpret them.
+ </p>
<p>
In the case of Perl scripts this should be
- <tt>#!/usr/bin/perl</tt>.</p>
+ <tt>#!/usr/bin/perl</tt>.
+ </p>
<p>
Shell scripts (<prgn>sh</prgn> and <prgn>bash</prgn>)
should almost certainly start with <tt>set -e</tt> so that
errors are detected. Every script should use
<tt>set -e</tt> or check the exit status of <em>every</em>
- command.</p>
+ command.
+ </p>
<p>
The standard shell interpreter <file>/bin/sh</file> can be a
symbolic link to any POSIX compatible shell, if <tt>echo
-n</tt> does not generate a newline.<footnote>
- <p>
Debian policy specifies POSIX behavior for
<file>/bin/sh</file>, but <tt>echo -n</tt> has widespread
use in the Linux community (in particular including this
required under POSIX, hence this explicit addition.
Also, rumour has it that this shall be mandated under
the LSB anyway.
- </p>
</footnote>
Thus, shell scripts specifying <file>/bin/sh</file> as
interpreter should only use POSIX features. If a script
Harmful</em>, one of the <tt>comp.unix.*</tt> FAQs, which
can be found at <url
id="http://language.perl.com/versus/csh.whynot">.<footnote>
- <p>
It can also be found on
<url id="http://www.cpan.org/doc/FMTEYEWTK/versus/csh.whynot">
or on the ftp site <ftpsite>ftp.cpan.org</ftpsite> as
<ftppath>/pub/perl/CPAN/doc/FMTEYEWTK/versus/csh.whynot</ftppath>.
- </p>
</footnote>
If an upstream package comes with <prgn>csh</prgn> scripts
then you must make sure that they start with
Any scripts which create files in world-writeable
directories (e.g., in <file>/tmp</file>) must use a
mechanism which will fail if a file with the same name
- already exists.</p>
+ already exists.
+ </p>
<p>
The Debian base system provides the <prgn>tempfile</prgn>
and <prgn>mktemp</prgn> utilities for use by scripts for
- this purpose.</p></sect>
+ this purpose.
+ </p>
+ </sect>
<sect>
should be relative, and symbolic links pointing from one
top-level directory into another should be absolute. (A
top-level directory is a sub-directory of the root
- directory <file>/</file>.)</p>
+ directory <file>/</file>.)
+ </p>
<p>
In addition, symbolic links should be specified as short as
possible, i.e., link targets like <file>foo/../bar</file> are
- deprecated.</p>
+ deprecated.
+ </p>
<p>
Note that when creating a relative link using
Simply include the string that should appear as the target
of the link (this will be a pathname relative to the
directory in which the link resides) as the first argument
- to <prgn>ln</prgn>.</p>
+ to <prgn>ln</prgn>.
+ </p>
<p>
For example, in your <prgn>Makefile</prgn> or
ln -fs gcc debian/tmp/usr/bin/cc
ln -fs ../sbin/sendmail $(prefix)/bin/runq
ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
- </example></p>
+ </example>
+ </p>
<p>
A symbolic link pointing to a compressed file should always
<p>
Packages must not include device files in the package file
- tree.</p>
+ tree.
+ </p>
<p>
If a package needs any special device files that are not
included in the base system, it must call
<prgn>MAKEDEV</prgn> in the <prgn>postinst</prgn> script,
after notifying the user<footnote>
- <p>
This notification could be done via a (low-priority)
debconf message, or an echo (printf) statement.
- </p>
- </footnote>
- .</p>
+ </footnote>.
+ </p>
<p>
Packages must not remove any device files in the
<prgn>postrm</prgn> or any other script. This is left to the
- system administrator.</p>
+ system administrator.
+ </p>
<p>
Debian uses the serial devices
<file>/dev/ttyS*</file>. Programs using the old
<file>/dev/cu*</file> devices should be changed to use
- <file>/dev/ttyS*</file>.</p>
+ <file>/dev/ttyS*</file>.
+ </p>
</sect>
<sect id="config-files">
<heading>Configuration files</heading>
+
<sect1>
<heading>Definitions</heading>
+
<p>
<taglist>
<tag>configuration file</tag>
<item>
- <p>
A file that affects the operation of a program, or
provides site- or host-specific information, or
otherwise customizes the behavior of a program.
modified by the system administrator (if needed or
desired) to conform to local policy or to provide
more useful site-specific behavior.
- </p>
</item>
<tag><tt>conffile</tt></tag>
<item>
- <p>
A file listed in a package's <tt>conffiles</tt>
file, and is treated specially by <prgn>dpkg</prgn>
(see <ref id="configdetails">).
- </p>
</item>
</taglist>
</p>
<sect1>
<heading>Location</heading>
+
<p>
Any configuration files created or used by your package
must reside in <file>/etc</file>. If there are several,
consider creating a subdirectory of <file>/etc</file>
- named after your package.</p>
+ named after your package.
+ </p>
<p>
If your package creates or uses configuration files
outside of <file>/etc</file>, and it is not feasible to modify
the package to use <file>/etc</file> directly, put the files
in <file>/etc</file> and create symbolic links to those files
- from the location that the package requires.</p>
+ from the location that the package requires.
+ </p>
</sect1>
<sect1>
<heading>Behavior</heading>
+
<p>
Configuration file handling must conform to the following
behavior:
<list compact="compact">
<item>
- <p>
local changes must be preserved during a package
upgrade, and
- </p>
</item>
<item>
- <p>
configuration files must be preserved when the
package is removed, and only deleted when the
package is purged.
- </p>
</item>
</list>
</p>
In order to ensure that local changes are preserved
correctly, no package may contain or make hard links to
conffiles.<footnote>
- <p>
Rationale: There are two problems with hard links.
The first is that some editors break the link while
editing one of the files, so that the two files may
unwittingly become unlinked and different. The second
is that <prgn>dpkg</prgn> might break the hard link
while upgrading <tt>conffile</tt>s.
- </p>
</footnote>
- </p>
+ </p>
+ <p>
The other way to do it is via the maintainer scripts. In
this case, the configuration file must not be listed as a
<tt>conffile</tt> and must not be part of the package
<sect1>
<heading>Sharing configuration files</heading>
+
<p>
Packages which specify the same file as a
<tt>conffile</tt> must be tagged as <em>conflicting</em>
depend on the owning package if they require the
configuration file to operate. If the other package will
use the configuration file if present, but is capable of
- operating without it, no dependency need be declared.</p>
+ operating without it, no dependency need be declared.
+ </p>
<p>
If it is desirable for two or more related packages to
file, then the following should be done:
<enumlist compact="compact">
<item>
- <p>
One of the related packages (the "owning" package)
will manage the configuration file with maintainer
scripts as described in the previous section.
- </p>
</item>
<item>
- <p>
The owning package should also provide a program
that the other packages may use to modify the
configuration file.
- </p>
</item>
<item>
- <p>
The related packages must use the provided program
to make any desired modifications to the
configuration file. They should either depend on
is not. (This is in addition to the fact that the
configuration file may not even be present in the
latter scenario.)
- </p>
</item>
</enumlist>
</p>
file (for more information see <manref name="logrotate"
section="8">):
<example compact="compact">
-/var/log/foo/* {
+/var/log/foo/*.log {
rotate 12
weekly
compress
security policy by changing the permissions on a binary:
they can do this by using <prgn>dpkg-statoverride</prgn>, as
described below.<footnote>
- <p>
Ordinary files installed by <prgn>dpkg</prgn> (as
opposed to <tt>conffile</tt>s and other similar objects)
normally have their permissions reset to the distributed
remember to describe <prgn>dpkg-statoverride</prgn> in
the package documentation; being a relatively new
addition to Debian, it is probably not yet well-known.
- </p>
</footnote>
Another method you should consider is to create a group for
people allowed to use the program(s) and make any setuid
If a program needs to specify an <em>architecture specification
string</em> in some place, the following format should be
used: <var>arch</var>-<var>os</var><footnote>
- <p>
The following architectures and operating systems are
currently recognised by <prgn>dpkg-archictecture</prgn>.
The architecture, <tt><var>arch</var></tt>, is one of
<tt>linux</tt>, <tt>gnu</tt>, <tt>freebsd</tt> and
<tt>openbsd</tt>. Use of <tt>gnu</tt> in this string is
reserved for the GNU/Hurd operating system.
- </p>
</footnote>.
</p>
It is not required for a package to depend on
<tt>editor</tt> and <tt>pager</tt>, nor is it required for a
package to provide such virtual packages.<footnote>
- <p>
The Debian base system already provides an editor and a
- pager program,
- </p>
+ pager program.
</footnote>
</p>
</sect>
<p>
<enumlist>
<item>
- <p>
Cgi-bin executable files are installed in the
directory
<example compact="compact">
<example compact="compact">
http://localhost/cgi-bin/<var>cgi-bin-name</var>
</example>
- </p>
</item>
- <item><p>Access to HTML documents</p>
+ <item>
+ <p>Access to HTML documents</p>
<p>
HTML documents for a package are stored in
http://localhost/doc/<var>package</var>/<var>filename</var>
</example>
</p>
- <p>
+
+ <p>
The web server should restrict access to the document
tree so that only clients on the same host can read
the documents. If the web server does not support such
</p>
</item>
- <item><p>Web Document Root</p>
+ <item>
+ <p>Web Document Root</p>
<p>
Web Applications should try to avoid storing files in
</p>
</item>
- </enumlist></p></sect>
-
+ </enumlist>
+ </p>
+ </sect>
<sect id="mail-transport-agents">
<heading>Mail transport, delivery and user agents</heading>
should use <tt>fcntl()</tt> first and dot locking after
this, or alternatively implement the two locking methods in
a non blocking way<footnote>
- <p>
If it is not possible to establish both locks, the
system shouldn't wait for the second lock to be
established, but remove the first lock, wait a (random)
time, and start over locking again.
- </p>
</footnote>. Using the functions <tt>maillock</tt> and
<tt>mailunlock</tt> provided by the
<tt>liblockfile*</tt><footnote>
<taglist>
<tag><file>/etc/news/organization</file></tag>
- <item><p>A string which should appear as the
+ <item>
+ A string which should appear as the
organization header for all messages posted
- by NNTP clients on the machine</p></item>
+ by NNTP clients on the machine
+ </item>
<tag><file>/etc/news/server</file></tag>
- <item><p>Contains the FQDN of the upstream NNTP
+ <item>
+ Contains the FQDN of the upstream NNTP
server, or localhost if the local machine is
- an NNTP server.</p></item>
+ an NNTP server.
+ </item>
</taglist>
Other global files may be added as required for cross-package news
- configuration.</p></sect>
+ configuration.
+ </p>
+ </sect>
<sect>
indirectly, communicates with real input and display
hardware should declare in their control data that they
provide the virtual package <tt>xserver</tt>.<footnote>
- <p>
This implements current practice, and provides an
actual policy for usage of the <tt>xserver</tt>
virtual package which appears in the virtual packages
another subsystem (e.g., GGI) should provide
<tt>xserver</tt>. Things like <tt>Xvfb</tt>,
<tt>Xnest</tt>, and <tt>Xprt</tt> should not.
- </p>
</footnote>
</p>
</sect1>
<p>
To be an <tt>x-terminal-emulator</tt>, a program must:
<list compact="compact">
- <item><p>
+ <item>
Be able to emulate a DEC VT100 terminal, or a
compatible terminal.
- </p></item>
+ </item>
- <item><p>
+ <item>
Support the command-line option <tt>-e
<var>command</var></tt>, which creates a new
terminal window<footnote>
- <p>
"New terminal window" does not necessarily mean
a new top-level X window directly parented by
the window manager; it could, if the terminal
emulator application were so coded, be a new
"view" in a multiple-document interface (MDI).
- </p>
</footnote>
- and runs the specified <var>command</var>.
- </p></item>
+ and runs the specified <var>command</var>,
+ interpreting the entirity of the rest of the command
+ line as a command to pass straight to exec, in the
+ manner that <tt>xterm</tt> does.
+ </item>
- <item><p>
+ <item>
Support the command-line option <tt>-T
<var>title</var></tt>, which creates a new terminal
window with the window title <var>title</var>.
- </p></item>
+ </item>
</list>
</p>
</sect1>
<file>/usr/bin/x-window-manager</file>, with a priority
calculated as follows:
<list compact="compact">
- <item><p>Start with a priority of 20.</p></item>
+ <item>
+ Start with a priority of 20.
+ </item>
<item>
- <p>
If the window manager supports the Debian menu
system, add 20 points if this support is available
in the package's default configuration (i.e., no
have to be edited to activate the feature); if
configuration files must be modified, add only 10
points.
- </p>
</item>
+
<item>
- <p>
If the window manager complies with <url
id="http://www.freedesktop.org/standards/wm-spec.html"
name="The Window Manager Specification Project">,
written by the <url id="http://www.freedesktop.org"
- name="Free Desktop Group">, add 20 points.
- </p>
+ name="Free Desktop Group">, add 40 points.
</item>
<item>
- <p>
If the window manager permits the X session to be
restarted using a <em>different</em> window manager
(without killing the X server) in its default
configuration, add 10 points; otherwise add none.
- </p>
</item>
</list>
</p>
<p>
Packages that provide fonts for the X Window
System<footnote>
- <p>
For the purposes of Debian Policy, a "font for the X
Window System" is one which is accessed via X protocol
requests. Fonts for the Linux console, for PostScript
definition. Any tool which makes such fonts available
to the X Window System, however, must abide by this
font policy.
- </p>
</footnote>
must do a number of things to ensure that they are both
available without modification of the X or font server
themselves.
<enumlist>
<item>
- <p>
Fonts of any type supported by the X Window System
must be in a separate binary package from any
executables, libraries, or documentation (except
provide an enhancement, a Suggests relationship may
be used. Packages must not Depend on font
packages.<footnote>
- <p>
This is because the X server may retrieve fonts
from the local filesystem or over the network
from an X font server; the Debian package system
is empowered to deal only with the local
filesystem.
- </p>
</footnote>
- </p>
</item>
<item>
- <p>
BDF fonts must be converted to PCF fonts with the
<prgn>bdftopcf</prgn> utility (available in the
<tt>xutils</tt> package, <prgn>gzip</prgn>ped, and
placed in a directory that corresponds to their
resolution:
<list compact="compact">
- <item><p>
+ <item>
100 dpi fonts must be placed in
<file>/usr/X11R6/lib/X11/fonts/100dpi/</file>.
- </p></item>
+ </item>
- <item><p>
+ <item>
75 dpi fonts must be placed in
<file>/usr/X11R6/lib/X11/fonts/75dpi/</file>.
- </p></item>
+ </item>
- <item><p>
+ <item>
Character-cell fonts, cursor fonts, and other
low-resolution fonts must be placed in
<file>/usr/X11R6/lib/X11/fonts/misc/</file>.
- </p></item>
+ </item>
</list>
- </p>
</item>
- <item><p>
+ <item>
Speedo fonts must be placed in
<file>/usr/X11R6/lib/X11/fonts/Speedo/</file>.
- </p></item>
+ </item>
- <item><p>
+ <item>
Type 1 fonts must be placed in
<file>/usr/X11R6/lib/X11/fonts/Type1/</file>. If font
metric files are available, they must be placed here
as well.
- </p></item>
+ </item>
<item>
- <p>
Subdirectories of <file>/usr/X11R6/lib/X11/fonts/</file>
other than those listed above must be neither
created nor used. (The <file>PEX</file>, <file>CID</file>,
and <file>cyrillic</file> directories are excepted for
historical reasons, but installation of files into
these directories remains discouraged.)
- </p>
</item>
<item>
- <p>
Font packages may, instead of placing files directly
in the X font directories listed above, provide
symbolic links in that font directory pointing to
the files' actual location in the filesystem. Such
a location must comply with the FHS.
- </p>
</item>
<item>
- <p>
Font packages should not contain both 75dpi and
100dpi versions of a font. If both are available,
they should be provided in separate binary packages
with <tt>-75dpi</tt> or <tt>-100dpi</tt> appended to
the names of the packages containing the
corresponding fonts.
- </p>
</item>
<item>
- <p>
Fonts destined for the <file>misc</file> subdirectory
should not be included in the same package as 75dpi
or 100dpi fonts; instead, they should be provided in
a separate package with <tt>-misc</tt> appended to
its name.
- </p>
</item>
<item>
- <p>
Font packages must not provide the files
<file>fonts.dir</file>, <file>fonts.alias</file>, or
<file>fonts.scale</file> in a font directory:
<list>
- <item><p>
+ <item>
<file>fonts.dir</file> files must not be provided at all.
- </p></item>
+ </item>
<item>
- <p>
<file>fonts.alias</file> and <file>fonts.scale</file>
files, if needed, should be provided in the
directory
<var>extension</var> is either <tt>scale</tt>
or <tt>alias</tt>, whichever corresponds to
the file contents.
- </p>
</item>
</list>
- </p>
</item>
<item>
- <p>
Font packages must declare a dependency on
<tt>xutils (>> 4.0.3)</tt> in their control
data.
- </p>
</item>
<item>
- <p>
Font packages that provide one or more
<file>fonts.scale</file> files as described above must
invoke <prgn>update-fonts-scale</prgn> on each
<prgn>postinst</prgn> (for all arguments) and
<prgn>postrm</prgn> (for all arguments except
<tt>upgrade</tt>) scripts.
- </p>
</item>
<item>
- <p>
Font packages that provide one or more
<file>fonts.alias</file> files as described above must
invoke <prgn>update-fonts-alias</prgn> on each
<prgn>postinst</prgn> (for all arguments) and
<prgn>postrm</prgn> (for all arguments except
<tt>upgrade</tt>) scripts.
- </p>
</item>
<item>
- <p>
Font packages must invoke
<prgn>update-fonts-dir</prgn> on each directory into
which they installed fonts. This invocation must
occur in both the <prgn>postinst</prgn> (for all
arguments) and <prgn>postrm</prgn> (for all
arguments except <tt>upgrade</tt>) scripts.
- </p>
</item>
<item>
- <p>
Font packages must not provide alias names for the
fonts they include which collide with alias names
already in use by fonts already packaged.
- </p>
</item>
<item>
- <p>
Font packages must not provide fonts with the same
XLFD registry name as another font already packaged.
- </p>
</item>
</enumlist>
</p>
<file>/etc/X11/Xresources/</file> directory, which must
registered as a <tt>conffile</tt> or handled as a
configuration file.<footnote>
- <p>
Note that this mechanism is not the same as using
app-defaults; app-defaults are tied to the client
binary on the local filesystem, whereas X resources
are stored in the X server and affect all connecting
clients.
- </p>
</footnote>
<em>Important:</em> packages that install files into the
<file>/etc/X11/Xresources/</file> directory must conflict with
<prgn>imake</prgn> program it provides, in which case the
packages may transition out of the <file>/usr/X11R6/</file>
directory at the maintainer's discretion.<footnote>
- <p>
<prgn>Imake</prgn>-using programs are exempt because,
as long as they are written correctly, the pathnames
they use to locate resources and install themselves
that is required for these programs is a recompile
against the corresponding X Window System library
development packages.
- </p>
</footnote>
+ </p>
+
+ <p>
Programs that use GNU <prgn>autoconf</prgn> and
<prgn>automake</prgn> are usually easily configured at
compile time to use <file>/usr/</file> instead of
to these programs' tight integration with the mechanisms
of the X Window System. Application-level programs should
use the <file>/etc/</file> directory unless otherwise mandated
- by policy. The installation of files into subdirectories
+ by policy.
+ </p>
+
+ <p>
+ The installation of files into subdirectories
of <file>/usr/X11R6/include/X11/</file> and
<file>/usr/X11R6/lib/X11/</file> is permitted but discouraged;
package maintainers should determine if subdirectories of
instead. (The use of symbolic links from the
<file>X11R6</file> directories to other FHS-compliant
locations is encouraged if the program is not easily
- configured to look elsewhere for its files.) Packages
- must not provide or install files into the directories
+ configured to look elsewhere for its files.)
+ </p>
+
+ <p>
+ Packages must not provide or install files into the directories
<file>/usr/bin/X11/</file>, <file>/usr/include/X11/</file> or
<file>/usr/lib/X11/</file>. Files within a package should,
however, make reference to these directories, rather than
<p>
<em>Programs that require the non-DFSG-compliant OSF/Motif or
OpenMotif libraries</em><footnote>
- <p>
OSF/Motif and OpenMotif are collectively referred to as
"Motif" in this policy document.
- </p>
</footnote>
should be compiled against and tested with LessTif (a free
re-implementation of Motif) instead. If the maintainer
statically against Motif and with <tt>-smotif</tt>
appended to the package name, and one linked dynamically
against Motif and with <tt>-dmotif</tt> appended to the
- package name. Both Motif-linked versions are dependent
+ package name.
+ </p>
+
+ <p>
+ Both Motif-linked versions are dependent
upon non-DFSG-compliant software and thus cannot be
uploaded to the <em>main</em> distribution; if the
software is itself DFSG-compliant it may be uploaded to
</sect1>
</sect>
- <sect>
+ <sect id="perl">
<heading>Perl programs and modules</heading>
+
+ <p>
+ Perl programs and modules should follow the current Perl policy.
+ </p>
+
<p>
- Perl programs and modules should follow the current Perl
- policy as defined in the file found on
- <ftpsite>ftp.debian.org</ftpsite> in
- <ftppath>/debian/doc/package-developer/perl-policy.txt.gz</ftppath>
- or your local mirror. In addition, it is included in the
- <tt>debian-policy</tt> package.
+ The Perl policy can be found in the <tt>perl-policy</tt>
+ files in the <tt>debian-policy</tt> package.
+ They are also available from the Debian web mirrors at
+ <tt><url name="/doc/packaging-manuals/perl-policy/"
+ id="http://www.debian.org/doc/packaging-manuals/perl-policy/"></tt>
+ and from the Debian archive mirrors at
+ <tt><url name="/doc/package-developer/perl-policy.txt.gz"
+ id="http://ftp.debian.org/debian/doc/package-developer/perl-policy.txt.gz"></tt>.
</p>
</sect>
- <sect>
+ <sect id="emacs">
<heading>Emacs lisp programs</heading>
<p>
- Please refer to the "Debian Emacs Policy" (documented in
- <file>debian-emacs-policy.gz</file> of the
- <prgn>emacsen-common</prgn> package) for details of how to
+ Please refer to the "Debian Emacs Policy" for details of how to
package emacs lisp programs.
</p>
+
+ <p>
+ The Emacs policy is available in
+ <file>debian-emacs-policy.gz</file> of the
+ <package>emacsen-common</package> package.
+ It is also available from the Debian web mirrors at
+ <tt><url name="/doc/packaging-manuals/debian-emacs-policy"
+ id="http://www.debian.org/doc/packaging-manuals/debian-emacs-policy"></tt>.
+ </p>
</sect>
<sect>
maintainer of the package is allowed to write this bug report
themselves, if they so desire). Do not close the bug report
until a proper manpage is available.<footnote>
- <p>
It is not very hard to write a man page. See the
<url id="http://www.schweikhardt.net/man_page_howto.html"
name="Man-Page-HOWTO">,
created by <prgn>debmake</prgn> or <prgn>dh_make</prgn>,
the helper programs <prgn>help2man</prgn>, or the
directory <file>/usr/share/doc/man-db/examples</file>.
- </p>
</footnote>
</p>
then you should not rely on <prgn>man</prgn> finding your
manpage under those names based solely on the information in
the manpage's header.<footnote>
- <p>
Supporting this in <prgn>man</prgn> often requires
unreasonable processing time to find a manual page or to
report that none exists, and moves knowledge into man's
database that would be better left in the filesystem.
This support is therefore deprecated and will cease to
be present in the future.
- </p>
</footnote>
</p>
</sect>
Packages must not require the existance of any files in
<file>/usr/share/doc/</file> in order to function
<footnote>
- <p>
The system administrator should be able to
delete files in <file>/usr/share/doc/</file> without causing
any programs to break.
- </p>
</footnote>.
Any files that are referenced by programs but are also
useful as standalone documentation should be installed under
changed to <file>/usr/share/doc/<var>package</var></file>,
and packages must not put documentation in the directory
<file>/usr/doc/<var>package</var></file>. <footnote>
- <p>At this phase of the transition, we no longer require a
+ At this phase of the transition, we no longer require a
symbolic link in <file>/usr/doc/</file>. At a later point,
- policy shall change to make the symbolic links a bug.</p>
+ policy shall change to make the symbolic links a bug.
</footnote>
</p>
</sect>
package, in the directory
<file>/usr/share/doc/<var>appropriate-package</var></file> or
its subdirectories.<footnote>
- <p>
The rationale: The important thing here is that HTML
docs should be available in <em>some</em> package, not
necessarily in the main binary package.
- </p>
</footnote>
</p>
</p>
<p>
- If the purpose of a package to provide examples, then the
+ If the purpose of a package is to provide examples, then the
example files may be installed into
<file>/usr/share/doc/<var>package</var></file>.
</p>
in <ref id="dpkgchangelog">. In non-experimental packages you must
use a format for <file>debian/changelog</file> which is supported
by the most recent released version of <prgn>dpkg</prgn>.<footnote>
- <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
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>
</footnote>
</p>
naming convention, then this may be achieved either by
renaming the files, or by adding a symbolic link, at the
maintainer's discretion.<footnote>
- <p>
Rationale: People should not have to look in places for
upstream changelogs merely because they are given
different names or are distributed in HTML format.
- </p>
</footnote>
</p>
<prgn>dpkg</prgn> is a suite of programs for creating binary
package files and installing and removing them on Unix
systems.<footnote>
- <p>
<prgn>dpkg</prgn> is targetted primarily at Debian
GNU/Linux, but may work on or be ported to other
systems.
- </p>
</footnote>
</p>
please see their manpages.
</p>
- <p>
- It does <em>not</em> describe the policy requirements imposed
- on Debian packages, such as the permissions on files and
- directories, documentation requirements, upload procedure, and
- so on. You should see the Debian packaging policy manual for
- these details. (Many of them will probably turn out to be
- helpful even if you don't plan to upload your package and make
- it available as part of the distribution.)
- </p>
-
<p>
It is assumed that the reader is reasonably familiar with the
<prgn>dpkg</prgn> System Administrators' manual.
It is very important to make these scripts
idempotent.
<footnote>
- <p>
That means that if it runs successfully or fails
and then you call it again it doesn't bomb out,
but just ensures that everything is the way it
ought to be.
- </p>
</footnote> This is so that if an error occurs, the
user interrupts <prgn>dpkg</prgn> or some other
unforeseen circumstance happens you don't leave the
<item><p><qref id="pkg-f-Architecture"><tt>Architecture</tt></qref>
(mandatory)
<footnote>
- <p>
This field should appear in all packages, though
<prgn>dpkg</prgn> doesn't require it yet so that
old packages can still be installed.
- </p>
</footnote>
</p>
</item>
times of the upstream source files in a package, as far as
is reasonably possible.
<footnote>
- <p>
The rationale is that there is some information conveyed
by knowing the age of the file, for example, you could
recognize that some documentation is very old by looking
at the modification time, so it would be nice if the
modification time of the upstream source would be
preserved.
- </p>
</footnote>
</p>
</sect>
the easy and automatic building of binaries.
</p>
- <p>
- There was a previous version of the Debian source format,
- which is now being phased out. Instructions for converting an
- old-style package are given in the Debian policy manual.
- </p>
-
<sect id="pkg-sourcetools">
<heading>Tools for processing source packages</heading>
permissions and ownerships set and the package is constructed using
<prgn>dpkg-deb/</prgn>
<footnote>
- <p>
This is so that the control file which is produced has
the right permissions
- </p>
</footnote>.
</p>
This file records the changes to the Debian-specific parts of the
package
<footnote>
- <p>
Though there is nothing stopping an author who is also
the Debian maintainer from using it for all their
changes, it will have to be renamed if the Debian and
upstream maintainers become different
people.
- </p>
</footnote>.
</p>
<p>
The <var>date</var> should be in RFC822 format
<footnote>
- <p>
This is generated by the <prgn>822-date</prgn>
program.
- </p>
</footnote>; it should include the timezone specified
numerically, with the timezone name or abbreviation
optionally present as a comment.
(and any backup files or temporary files such as
<file>files.new</file>
<footnote>
- <p>
<file>files.new</file> is used as a temporary file by
<prgn>dpkg-gencontrol</prgn> and
<prgn>dpkg-distaddfile</prgn> - they write a new
version of <file>files</file> here before renaming it,
to avoid leaving a corrupted copy if an error
occurs
- </p>
</footnote>) should be removed by the
<tt>clean</tt> target. It may also be wise to
ensure a fresh start by emptying or removing it at the
<p>
The source package may not contain any hard links
<footnote>
- <p>
This is not currently detected when building source
packages, but only when extracting
them.
- </p>
</footnote>
<footnote>
- <p>
Hard links may be permitted at some point in the
future, but would require a fair amount of
work.
- </p>
</footnote>, device special files, sockets or setuid or
setgid files.
<footnote>
- <p>
Setgid directories are allowed.
- </p>
</footnote>
</p>
<p>
Removing files, directories or symlinks.
<footnote>
- <p>
Renaming a file is not treated specially - it is
seen as the removal of the old file (which
generates a warning, but is otherwise ignored),
- and the creation of the new
- one.</p>
+ and the creation of the new one.
</footnote>
</p>
</item>
It is important to note that there are several fields which
are optional as far as <prgn>dpkg</prgn> and the related
tools are concerned, but which must appear in every Debian
- package, or whose omission may cause problems. When writing
- the control files for Debian packages you <em>must</em> read
- the Debian policy manual in conjuction with the details
- below and the list of fields for the particular file.</p>
+ package, or whose omission may cause problems.
+ </p>
</sect>
<sect><heading>List of fields
the alphanumerics and <tt>+</tt> <tt>-</tt> <tt>.</tt>
(plus, minus and full stop).
<footnote>
- <p>
The characters <tt>@</tt> <tt>:</tt> <tt>=</tt>
<tt>%</tt> <tt>_</tt> (at, colon, equals, percent
and underscore) used to be legal and are still
accepted when found in a package file, but may not be
- used in new packages
- </p>
+ used in new packages.
</footnote>
</p>
<p>
They must be at least two characters and must start with
an alphanumeric. In current versions of dpkg they are
- sort of case-sensitive<footnote><p>This is a
- bug.</p></footnote>; use lowercase package names unless
+ sort of case-sensitive<footnote>
+ This is a bug.
+ </footnote>; use lowercase package names unless
the package you're building (or referring to, in other
- fields) is already using uppercase.</p>
+ fields) is already using uppercase.
+ </p>
</sect1>
<sect1 id="pkg-f-Version"><heading><tt>Version</tt>
<file>Packages</file> file) it may be followed by a version
number in parentheses.
<footnote>
- <p>
It is usual to leave a space after the package name if
a version number is specified.
- </p>
</footnote> This version number may be omitted (and is, by
<prgn>dpkg-gencontrol</prgn>) if it has the same value as
the <tt>Version</tt> field of the binary package in
<p>
These fields are not used by by <prgn>dpkg</prgn> proper,
but by <prgn>dselect</prgn> when it sorts packages and
- selects defaults. See the Debian policy manual for the
- priorities in use and the criteria for selecting the
- priority for a Debian package, and look at the Debian FTP
- archive for a list of currently in-use priorities.
+ selects defaults.
</p>
<p>
- These fields may appear in binary package control files,
+ These fields can appear in binary package control files,
in which case they provide a default value in case the
<file>Packages</file> files are missing the information.
<prgn>dpkg</prgn> and <prgn>dselect</prgn> will only use
The syntax is a list of binary packages separated by
commas.
<footnote>
- <p>
A space after each comma is conventional.
- </p>
</footnote> Currently the packages must be separated using
only spaces in the <file>.changes</file> file.</p>
</sect1>
tarfile and (if applicable) diff file which make up the
remainder of the source package.
<footnote>
- <p>
- That is, the parts which are not the
- <tt>.dsc</tt>.
- </p>
+ That is, the parts which are not the <tt>.dsc</tt>.
</footnote> The exact forms of the filenames are described
in <ref id="pkg-sourcearchives">.
</p>
</heading>
<p>
- The most recent version of the standards (the
- <prgn>dpkg</prgn> programmers' and policy manuals and
- associated texts) with which the package complies. This
+ The most recent version of the standards (the Debian Policy
+ and associated texts) with which the package complies. This
is updated manually when editing the source package to
conform to newer standards; it can sometimes be used to
tell when a package needs attention.
representation of blank line).</p>
</sect1>
- <sect1 id="pkg-f-Filename"><heading><tt>Filename</tt> and
- <tt>MSDOS-Filename</tt>
- </heading>
+ <sect1 id="pkg-f-Filename">
+ <heading><tt>Filename</tt> and <tt>MSDOS-Filename</tt></heading>
<p>
These fields in <tt>Packages</tt> files give the
distribution directories, relative to the root of the
Debian hierarchy. If the package has been split into
several parts the parts are all listed in order, separated
- by spaces.</p>
+ by spaces.
+ </p>
</sect1>
- <sect1 id="pkg-f-Size"><heading><tt>Size</tt> and <tt>MD5sum</tt>
- </heading>
+ <sect1 id="pkg-f-Size">
+ <heading><tt>Size</tt> and <tt>MD5sum</tt></heading>
<p>
These fields in <file>Packages</file> files give the size (in
file(s) which make(s) up a binary package in the
distribution. If the package is split into several parts
the values for the parts are listed in order, separated by
- spaces.</p>
+ spaces.
+ </p>
</sect1>
- <sect1 id="pkg-f-Status"><heading><tt>Status</tt>
- </heading>
+ <sect1 id="pkg-f-Status">
+ <heading><tt>Status</tt></heading>
<p>
This field in <prgn>dpkg</prgn>'s status file records
left alone, whether it is broken (requiring
reinstallation) or not and what its current state on the
system is. Each of these pieces of information is a
- single word.</p>
+ single word.
+ </p>
</sect1>
- <sect1 id="pkg-f-Config-Version"><heading><tt>Config-Version</tt>
- </heading>
+ <sect1 id="pkg-f-Config-Version">
+ <heading><tt>Config-Version</tt></heading>
<p>
If a package is not installed or not configured, this
field in <prgn>dpkg</prgn>'s status file records the last
version of the package which was successfully
- configured.</p>
+ configured.
+ </p>
</sect1>
- <sect1 id="pkg-f-Conffiles"><heading><tt>Conffiles</tt>
- </heading>
+ <sect1 id="pkg-f-Conffiles">
+ <heading><tt>Conffiles</tt></heading>
<p>
This field in <prgn>dpkg</prgn>'s status file contains
information about the automatically-managed configuration
files held by a package. This field should <em>not</em>
- appear anywhere in a package!</p>
+ appear anywhere in a package!
+ </p>
</sect1>
- <sect1><heading>Obsolete fields
- </heading>
+ <sect1>
+ <heading>Obsolete fields</heading>
<p>
These are still recognised by <prgn>dpkg</prgn> but should
not appear anywhere any more.
+
<taglist compact="compact">
<tag><tt>Revision</tt></tag>
<tag><tt>Package-Revision</tt></tag>
<tag><tt>Package_Revision</tt></tag>
<item>
- <p>
The Debian revision part of the package version was
at one point in a separate control file field. This
- field went through several names.</p>
+ field went through several names.
</item>
<tag><tt>Recommended</tt></tag>
- <item><p>Old name for <tt>Recommends</tt></p>
- </item>
+ <item>Old name for <tt>Recommends</tt>.</item>
<tag><tt>Optional</tt></tag>
- <item><p>Old name for <tt>Suggests</tt>.</p>
- </item>
+ <item>Old name for <tt>Suggests</tt>.</item>
+
<tag><tt>Class</tt></tag>
- <item><p>Old name for <tt>Priority</tt>.</p>
- </item>
+ <item>Old name for <tt>Priority</tt>.</item>
+
</taglist>
</p>
</sect1>
</sect>
+
</appendix>
- <appendix id="pkg-conffiles"><heading>Configuration file handling
- (from old Packaging Manual)
- </heading>
+ <appendix id="pkg-conffiles">
+ <heading>Configuration file handling (from old Packaging Manual)</heading>
<p>
<prgn>dpkg</prgn> can do a certain amount of automatic
projects / debian / debian-policy.git / blobdiff