<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><url name="debian-policy" id="http://packages.debian.org/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>.
+ 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
<em>free</em> in our sense (see the Debian Free Software
Guidelines, below), or may be imported/exported without
restrictions. Thus, the archive is split into the sections
- <em>main</em>, <em>non-free</em>, <em>contrib</em>,
- <em>non-US/main</em>, <em>non-US/non-free</em>, and
- <em>non-US/contrib</em>. The sections are explained in detail
- below.
+ based on their licenses and other restrictions.
+ </p>
+
+ <p>
+ The aims of this are:
+
+ <list compact="compact">
+ <item>to allow us to make as much software available as we can</item>
+ <item>to allow us to encourage everyone to write free software,
+ and</item>
+ <item>to allow us to make it easy for people to produce
+ CD-ROMs of our system without violating any licenses,
+ import/export restrictions, or any other laws.</item>
+ </list>
</p>
<p>
of the Debian distribution, although we support their use and
provide infrastructure for them (such as our bug-tracking
system and mailing lists). This Debian Policy Manual applies
- to these packages as well.</p>
+ to these packages as well.
+ </p>
- <sect id="pkgcopyright">
- <heading>Package copyright and sections</heading>
+ <sect id="dfsg">
+ <heading>The Debian Free Software Guidelines</heading>
<p>
- The aims of this section are:
-
- <list compact="compact">
- <item>
- <p>to allow us to make as much software available as we
- can,</p>
- </item>
- <item>
- <p>to allow us to encourage everyone to write free
- software, and</p>
- </item>
- <item>
- <p>to allow us to make it easy for people to produce
- CD-ROMs of our system without violating any licenses,
- import/export restrictions, or any other laws.</p>
- </item>
- </list>
- </p>
- <sect1>
- <heading>The Debian Free Software Guidelines</heading>
- <p>
- The Debian Free Software Guidelines (DFSG) form our
- definition of "free software". These are:
+ The Debian Free Software Guidelines (DFSG) form our
+ definition of "free software". These are:
<taglist>
<tag>Free Redistribution
</tag>
<item>
- <p>
The license of a Debian component may not restrict any
party from selling or giving away the software as a
component of an aggregate software distribution
containing programs from several different
sources. The license may not require a royalty or
other fee for such sale.
- </p>
</item>
<tag>Source Code
</tag>
<item>
- <p>
The program must include source code, and must allow
distribution in source code as well as compiled form.
- </p>
</item>
<tag>Derived Works
</tag>
<item>
- <p>
The license must allow modifications and derived
works, and must allow them to be distributed under the
same terms as the license of the original software.
- </p>
</item>
<tag>Integrity of The Author's Source Code
</tag>
<item>
- <p>
The license may restrict source-code from being
distributed in modified form <em>only</em> if the
license allows the distribution of "patch files"
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>
- </sect1>
- <sect1>
+ </p>
+ </sect>
+
+ <sect id="sections">
+ <heading>Sections</heading>
+
+ <sect1 id="main">
<heading>The main section</heading>
+
<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",
+ restricted 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
server as well.
</p>
</sect1>
- <sect1>
- <heading>Further copyright considerations</heading>
- <p>
- Every package must be accompanied by a verbatim copy of
- its copyright and distribution license in the file
- <file>/usr/share/doc/<var>package</var>/copyright</file>
- (see <ref id="copyrightfile"> for further details).
- </p>
- <p>
- We reserve the right to restrict files from being included
- anywhere in our archives if
- <list compact="compact">
- <item>
- <p>
+ </sect>
+
+ <sect id="pkgcopyright">
+ <heading>Copyright considerations</heading>
+
+ <p>
+ Every package must be accompanied by a verbatim copy of
+ its copyright and distribution license in the file
+ <file>/usr/share/doc/<var>package</var>/copyright</file>
+ (see <ref id="copyrightfile"> for further details).
+ </p>
+
+ <p>
+ We reserve the right to restrict files from being included
+ anywhere in our archives if
+ <list compact="compact">
+ <item>
their use or distribution would break a law,
- </p>
- </item>
- <item>
- <p>
+ </item>
+ <item>
there is an ethical conflict in their distribution or
use,
- </p>
- </item>
- <item>
- <p>
+ </item>
+ <item>
we would have to sign a license for them, or
- </p>
- </item>
- <item>
- <p>
+ </item>
+ <item>
their distribution would conflict with other project
policies.
- </p>
- </item>
- </list>
- </p>
+ </item>
+ </list>
+ </p>
- <p>
- Programs whose authors encourage the user to make
- donations are fine for the main distribution, provided
- that the authors do not claim that not donating is
- immoral, unethical, illegal or something similar; in such
- a case they must go in <em>non-free</em>.</p>
+ <p>
+ Programs whose authors encourage the user to make
+ donations are fine for the main distribution, provided
+ that the authors do not claim that not donating is
+ immoral, unethical, illegal or something similar; in such
+ a case they must go in <em>non-free</em>.
+ </p>
- <p>
- Packages whose copyright permission notices (or patent
- problems) do not even allow redistribution of binaries
- only, and where no special permission has been obtained,
- must not be placed on the Debian FTP site and its mirrors
- at all.</p>
+ <p>
+ Packages whose copyright permission notices (or patent
+ problems) do not even allow redistribution of binaries
+ only, and where no special permission has been obtained,
+ must not be placed on the Debian FTP site and its mirrors
+ at all.
+ </p>
- <p>
- Note that under international copyright law (this applies
- in the United States, too), <em>no</em> distribution or
- modification of a work is allowed without an explicit
- notice saying so. Therefore a program without a copyright
- notice <em>is</em> copyrighted and you may not do anything
- to it without risking being sued! Likewise if a program
- has a copyright notice but no statement saying what is
- permitted then nothing is permitted.</p>
+ <p>
+ Note that under international copyright law (this applies
+ in the United States, too), <em>no</em> distribution or
+ modification of a work is allowed without an explicit
+ notice saying so. Therefore a program without a copyright
+ notice <em>is</em> copyrighted and you may not do anything
+ to it without risking being sued! Likewise if a program
+ has a copyright notice but no statement saying what is
+ permitted then nothing is permitted.
+ </p>
- Many authors are unaware of the problems that restrictive
- copyrights (or lack of copyright notices) can cause for
- the users of their supposedly-free software. It is often
- worthwhile contacting such authors diplomatically to ask
- them to modify their license terms. However, this can be a
- politically difficult thing to do and you should ask for
- advice on the <tt>debian-legal</tt> mailing list first, as
- explained below.
- </p>
+ <p>
+ Many authors are unaware of the problems that restrictive
+ copyrights (or lack of copyright notices) can cause for
+ the users of their supposedly-free software. It is often
+ worthwhile contacting such authors diplomatically to ask
+ them to modify their license terms. However, this can be a
+ politically difficult thing to do and you should ask for
+ advice on the <tt>debian-legal</tt> mailing list first, as
+ explained below.
+ </p>
- <p>
- When in doubt about a copyright, send mail to
- <email>debian-legal@lists.debian.org</email>. Be prepared
- to provide us with the copyright statement. Software
- covered by the GPL, public domain software and BSD-like
- copyrights are safe; be wary of the phrases "commercial
- use prohibited" and "distribution restricted".
- </p>
- </sect1>
- <sect1>
- <heading>Subsections</heading>
+ <p>
+ When in doubt about a copyright, send mail to
+ <email>debian-legal@lists.debian.org</email>. Be prepared
+ to provide us with the copyright statement. Software
+ covered by the GPL, public domain software and BSD-like
+ copyrights are safe; be wary of the phrases "commercial
+ use prohibited" and "distribution restricted".
+ </p>
+ </sect>
- <p>
- The packages in the sections <em>main</em>,
- <em>contrib</em> and <em>non-free</em> are grouped further
- into <em>subsections</em> to simplify handling.
- </p>
+ <sect id="subsections">
+ <heading>Subsections</heading>
- <p>
- The section and subsection for each package should be
- specified in the package's <tt>Section</tt> control
- record. However, the maintainer of the Debian archive
- may override this selection to ensure the consistency of
- the Debian distribution. The <tt>Section</tt> field
- should be of the form:
- <list compact="compact">
- <item>
- <p>
+ <p>
+ The packages in the sections <em>main</em>,
+ <em>contrib</em> and <em>non-free</em> are grouped further
+ into <em>subsections</em> to simplify handling.
+ </p>
+
+ <p>
+ The section and subsection for each package should be
+ specified in the package's <tt>Section</tt> control
+ record (see <ref id="f-Section">).
+ However, the maintainer of the Debian archive
+ may override this selection to ensure the consistency of
+ the Debian distribution. The <tt>Section</tt> field
+ should be of the form:
+ <list compact="compact">
+ <item>
<em>subsection</em> if the package is in the
<em>main</em> section,
- </p>
- </item>
- <item>
- <p>
+ </item>
+ <item>
<em>section/subsection</em> if the package is in
the <em>contrib</em> or <em>non-free</em> section,
and
- </p>
- </item>
- <item>
- <p>
+ </item>
+ <item>
<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>
+ </item>
+ </list>
+ </p>
- <p>
- The Debian archive maintainers provide the authoritative
- list of subsections. At present, they are:
- <em>admin</em>, <em>base</em>, <em>comm</em>,
- <em>contrib</em>, <em>devel</em>, <em>doc</em>,
- <em>editors</em>, <em>electronics</em>, <em>games</em>,
- <em>graphics</em>, <em>hamradio</em>,
- <em>interpreters</em>, <em>libs</em>, <em>mail</em>,
- <em>math</em>, <em>misc</em>, <em>net</em>, <em>news</em>,
- <em>non-US</em>, <em>non-free</em>, <em>oldlibs</em>,
- <em>otherosfs</em>, <em>science</em>, <em>shells</em>,
- <em>sound</em>, <em>tex</em>, <em>text</em>,
- <em>utils</em>, <em>web</em>, <em>x11</em>.
- </p>
- </sect1>
- <sect>
+ <p>
+ The Debian archive maintainers provide the authoritative
+ list of subsections. At present, they are:
+ <em>admin</em>, <em>base</em>, <em>comm</em>,
+ <em>contrib</em>, <em>devel</em>, <em>doc</em>,
+ <em>editors</em>, <em>electronics</em>, <em>embedded</em>,
+ <em>games</em>, <em>gnome</em> <em>graphics</em>,
+ <em>hamradio</em>, <em>interpreters</em>, <em>kde</em>,
+ <em>libs</em>, <em>libdevel</em>, <em>mail</em>,
+ <em>math</em>, <em>misc</em>, <em>net</em>, <em>news</em>,
+ <em>non-US</em>, <em>non-free</em>, <em>oldlibs</em>,
+ <em>otherosfs</em>, <em>perl</em>, <em>python</em>
+ <em>science</em>, <em>shells</em>,
+ <em>sound</em>, <em>tex</em>, <em>text</em>,
+ <em>utils</em>, <em>web</em>, <em>x11</em>.
+ </p>
+ </sect>
+
+ <sect id="priorities">
<heading>Priorities</heading>
<p>
Each package should have a <em>priority</em> value, which is
- included in the package's <em>control record</em>. This
- information is used by the Debian package management tools
- to separate high-priority packages from less-important
- packages.</p>
+ included in the package's <em>control record</em>
+ (see <ref id="f-Priority">).
+ This information is used by the Debian package management tools to
+ separate high-priority packages from less-important packages.
+ </p>
<p>
The following <em>priority levels</em> are recognised by the
<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
</p>
</sect>
+ </chapt>
+
+
+ <chapt id="binary">
+ <heading>Binary packages</heading>
+
+ <p>
+ The Debian GNU/Linux distribution is based on the Debian
+ package management system, called <prgn>dpkg</prgn>. Thus,
+ all packages in the Debian distribution must be provided
+ in the <tt>.deb</tt> file format.
+ </p>
+
<sect>
- <heading>Binary packages</heading>
+ <heading>The package name</heading>
+
+ <p>
+ Every package must have a name that's unique within the Debian
+ archive.
+ </p>
+
+ <p>
+ The package name is included in the control field
+ <tt>Package</tt>, the format of which is described
+ in <ref id="f-Package">.
+ The package name is also included as a part of the file name
+ of the <tt>.deb</tt> file.
+ </p>
+ </sect>
+
+ <sect id="versions">
+ <heading>The version of a package</heading>
+
+ <p>
+ Every package has a version number recorded in its
+ <tt>Version</tt> control file field, described in
+ <ref id="f-Version">.
+ </p>
<p>
- The Debian GNU/Linux distribution is based on the Debian
- package management system, called <prgn>dpkg</prgn>. Thus,
- all packages in the Debian distribution must be provided
- in the <tt>.deb</tt> file format.</p>
+ The package management system imposes an ordering on version
+ numbers, so that it can tell whether packages are being up- or
+ downgraded and so that package system front end applications
+ can tell whether a package it finds available is newer than
+ the one installed on the system. The version number format
+ has the most significant parts (as far as comparison is
+ concerned) at the beginning.
+ </p>
+ <p>
+ If an upstream package has problematic version numbers they
+ should be converted to a sane form for use in the
+ <tt>Version</tt> field.
+ </p>
<sect1>
- <heading>The package name</heading>
+ <heading>Version numbers based on dates</heading>
<p>
- Every package must have a name that's unique within the Debian
- archive.</p>
+ In general, Debian packages should use the same version
+ numbers as the upstream sources.
+ </p>
<p>
- Package names must consist of lower case letters
- (<tt>a-z</tt>), digits (<tt>0-9</tt>), plus (<tt>+</tt>)
- and minus (<tt>-</tt>) signs, and periods (<tt>.</tt>).
- They must be at least two characters long and must start
- with an alphanumeric character.
+ However, in some cases where the upstream version number is
+ based on a date (e.g., a development "snapshot" release) the
+ package management system cannot handle these version
+ numbers without epochs. For example, dpkg will consider
+ "96May01" to be greater than "96Dec24".
</p>
<p>
- The package name is part of the file name of the
- <tt>.deb</tt> file and is included in the control field
- information.
- </p>
- </sect1>
-
- <sect1>
- <heading>The maintainer of a package</heading>
- <p>
- Every package must have a Debian maintainer (the
- maintainer may be one person or a group of people
- reachable from a common email address, such as a mailing
- list). The maintainer is responsible for ensuring that
- the package is placed in the appropriate distributions.
+ To prevent having to use epochs for every new upstream
+ version, the version number should be changed to the
+ following format in such cases: "19960501", "19961224". It
+ is up to the maintainer whether he/she wants to bother the
+ upstream maintainer to change the version numbers upstream,
+ too.
</p>
<p>
- The maintainer must be specified in the
- <tt>Maintainer</tt> control field with their correct name
- and a working email address. If one person maintains
- several packages, he/she should try to avoid having
- different forms of their name and email address in
- the <tt>Maintainer</tt> fields of those packages.
+ Note that other version formats based on dates which are
+ parsed correctly by the package management system should
+ <em>not</em> be changed.
</p>
<p>
- If the maintainer of a package quits from the Debian
- project, "Debian QA Group"
- <email>packages@qa.debian.org</email> takes over the
- maintainership of the package until someone else
- volunteers for that task. These packages are called
- <em>orphaned packages</em>.<footnote>
- <p>
- The detailed procedure for doing this gracefully can
- be found in the Debian Developer's Reference, either
- in the <tt>developers-reference</tt> package, or on
- the Debian FTP server
- <ftpsite>ftp.debian.org</ftpsite> as
- <ftppath>/debian/doc/package-developer/developers-reference.txt.gz</ftppath>
- or from the <url
- id="http://www.debian.org/doc/packaging-manuals/developers-reference/"
- name="Debian Developer's Reference"> webpage.
- </p>
- </footnote>
+ Native Debian packages (i.e., packages which have been
+ written especially for Debian) whose version numbers include
+ dates should always use the "YYYYMMDD" format.
</p>
</sect1>
+ </sect>
- <sect1>
- <heading>The description of a package</heading>
+ <sect>
+ <heading>The maintainer of a package</heading>
- <p>
- Every Debian package must have an extended description
- stored in the appropriate field of the control record.</p>
+ <p>
+ Every package must have a Debian maintainer (the
+ maintainer may be one person or a group of people
+ reachable from a common email address, such as a mailing
+ list). The maintainer is responsible for ensuring that
+ the package is placed in the appropriate distributions.
+ </p>
+
+ <p>
+ The maintainer must be specified in the
+ <tt>Maintainer</tt> control field with their correct name
+ and a working email address. If one person maintains
+ several packages, he/she should try to avoid having
+ different forms of their name and email address in
+ the <tt>Maintainer</tt> fields of those packages.
+ </p>
+
+ <p>
+ The format of the <tt>Maintainer</tt> control field is
+ described in <ref id="f-Maintainer">.
+ </p>
+
+ <p>
+ If the maintainer of a package quits from the Debian
+ project, "Debian QA Group"
+ <email>packages@qa.debian.org</email> takes over the
+ maintainership of the package until someone else
+ volunteers for that task. These packages are called
+ <em>orphaned packages</em>.<footnote>
+ The detailed procedure for doing this gracefully can
+ be found in the Debian Developer's Reference,
+ see <ref id="related">.
+ </footnote>
+ </p>
+ </sect>
+
+ <sect id="descriptions">
+ <heading>The description of a package</heading>
+
+ <p>
+ Every Debian package must have an extended description
+ stored in the appropriate field of the control record.
+ The technical information about the format of the
+ <tt>Description</tt> field is in <ref id="f-Description">.
+ </p>
+
+ <p>
+ The description should describe the package (the program) to a
+ user (system administrator) who has never met it before so that
+ they have enough information to decide whether they want to
+ install it. This description should not just be copied verbatim
+ from the program's documentation.
+ </p>
+
+ <p>
+ Put important information first, both in the synopsis and
+ extended description. Sometimes only the first part of the
+ synopsis or of the description will be displayed. You can
+ assume that there will usually be a way to see the whole
+ extended description.
+ </p>
+
+ <p>
+ The description should also give information about the
+ significant dependencies and conflicts between this package
+ and others, so that the user knows why these dependencies and
+ conflicts have been declared.
+ </p>
+
+ <p>
+ Instructions for configuring or using the package should
+ not be included (that is what installation scripts,
+ manual pages, info files, etc., are for). Copyright
+ statements and other administrivia should not be included
+ either (that is what the copyright file is for).
+ </p>
+
+ <sect1 id="synopsis"><heading>The single line synopsis</heading>
<p>
- The description should be written so that it gives the
- system administrator enough information to decide whether
- to install the package. This description should not just
- be copied verbatim from the program's documentation.
- Instructions for configuring or using the package should
- not be included (that is what installation scripts,
- manual pages, info files, etc., are for). Copyright
- statements and other administrivia should not be included
- either (that is what the copyright file is for).
+ The single line synopsis should be kept brief - certainly
+ under 80 characters.
</p>
<p>
- Please refer to <ref id="descriptions"> for more information.
+ Do not include the package name in the synopsis line. The
+ display software knows how to display this already, and you
+ do not need to state it. Remember that in many situations
+ the user may only see the synopsis line - make it as
+ informative as you can.
</p>
</sect1>
-
- <sect1>
- <heading>Dependencies</heading>
+ <sect1 id="extendeddesc"><heading>The extended description</heading>
<p>
- Every package must specify the dependency information
- about other packages that are required for the first to
- work correctly.</p>
+ Do not try to continue the single line synopsis into the
+ extended description. This will not work correctly when
+ the full description is displayed, and makes no sense
+ where only the summary (the single line synopsis) is
+ available.
+ </p>
<p>
- For example, a dependency entry must be provided for any
- shared libraries required by a dynamically-linked executable
- binary in a package.</p>
+ The extended description should describe what the package
+ does and how it relates to the rest of the system (in terms
+ of, for example, which subsystem it is which part of).
+ </p>
<p>
- Packages are not required to declare any dependencies they
- have on other packages which are marked <tt>Essential</tt>
- (see below), and should not do so unless they depend on a
- particular version of that package.</p>
+ The description field needs to make sense to anyone, even
+ people who have no idea about any of the things the
+ package deals with.<footnote>
+ The blurb that comes with a program in its
+ announcements and/or <prgn>README</prgn> files is
+ rarely suitable for use in a description. It is
+ usually aimed at people who are already in the
+ community where the package is used.
+ </footnote>
+ </p>
- <p>
- Sometimes, a package requires another package to be installed
- <em>and</em> configured before it can be installed. In this
- case, you must specify a <tt>Pre-Depends</tt> entry for
- the package.</p>
+ </sect1>
- <p>
- You should not specify a <tt>Pre-Depends</tt> entry for a
- package before this has been discussed on the
- <tt>debian-devel</tt> mailing list and a consensus about
- doing that has been reached.</p></sect1>
+ </sect>
+ <sect>
+ <heading>Dependencies</heading>
- <sect1 id="virtual_pkg_sect">
- <heading>Virtual packages</heading>
+ <p>
+ Every package must specify the dependency information
+ about other packages that are required for the first to
+ work correctly.
+ </p>
- <p>
- Sometimes, there are several packages which offer
- more-or-less the same functionality. In this case, it's
- useful to define a <em>virtual package</em> whose name
- describes that common functionality. (The virtual
- packages only exist logically, not physically; that's why
- they are called <em>virtual</em>.) The packages with this
- particular function will then <em>provide</em> the virtual
- package. Thus, any other package requiring that function
- can simply depend on the virtual package without having to
- specify all possible packages individually.</p>
+ <p>
+ For example, a dependency entry must be provided for any
+ shared libraries required by a dynamically-linked executable
+ binary in a package.
+ </p>
- <p>
- All packages should use virtual package names where
- appropriate, and arrange to create new ones if necessary.
- They should not use virtual package names (except privately,
- amongst a cooperating group of packages) unless they have
- been agreed upon and appear in the list of virtual package
- names. (See also <ref id="virtual">)</p>
+ <p>
+ Packages are not required to declare any dependencies they
+ have on other packages which are marked <tt>Essential</tt>
+ (see below), and should not do so unless they depend on a
+ particular version of that package.
+ </p>
- <p>
- The latest version of the authoritative list of virtual
- package names can be found on
- <ftpsite>ftp.debian.org</ftpsite> in
- <ftppath>/debian/doc/package-developer/virtual-package-names-list.txt</ftppath>
- or your local mirror. In addition, it is included in the
- <tt>debian-policy</tt> package. The procedure for updating
- the list is described at the top of the file.</p></sect1>
+ <p>
+ Sometimes, a package requires another package to be installed
+ <em>and</em> configured before it can be installed. In this
+ case, you must specify a <tt>Pre-Depends</tt> entry for
+ the package.
+ </p>
+ <p>
+ You should not specify a <tt>Pre-Depends</tt> entry for a
+ package before this has been discussed on the
+ <tt>debian-devel</tt> mailing list and a consensus about
+ doing that has been reached.
+ </p>
- <sect1>
- <heading>Base system</heading>
+ <p>
+ The format of the package interrelationship control fields is
+ described in <ref id="relationships">.
+ </p>
+ </sect>
- <p>
- The <tt>base system</tt> is a minimum subset of the Debian
- GNU/Linux system that is installed before everything else
- on a new system. Thus, only very few packages are allowed
- to go into the <tt>base</tt> section to keep the required
- disk usage very small.</p>
+ <sect id="virtual_pkg">
+ <heading>Virtual packages</heading>
- <p>
- Most of these packages will have the priority value
- <tt>required</tt> or at least <tt>important</tt>, and many
- of them will be tagged <tt>essential</tt> (see below).</p>
+ <p>
+ Sometimes, there are several packages which offer
+ more-or-less the same functionality. In this case, it's
+ useful to define a <em>virtual package</em> whose name
+ describes that common functionality. (The virtual
+ packages only exist logically, not physically; that's why
+ they are called <em>virtual</em>.) The packages with this
+ particular function will then <em>provide</em> the virtual
+ package. Thus, any other package requiring that function
+ can simply depend on the virtual package without having to
+ specify all possible packages individually.
+ </p>
+ <p>
+ All packages should use virtual package names where
+ appropriate, and arrange to create new ones if necessary.
+ They should not use virtual package names (except privately,
+ amongst a cooperating group of packages) unless they have
+ been agreed upon and appear in the list of virtual package
+ names. (See also <ref id="virtual">)
+ </p>
- </sect1>
+ <p>
+ The latest version of the authoritative list of virtual
+ package names can be found in the <tt>debian-policy</tt> package.
+ It is also available from the Debian web mirrors at
+ <tt><url name="/doc/packaging-manuals/virtual-package-names-list.txt"
+ id="http://www.debian.org/doc/packaging-manuals/virtual-package-names-list.txt"></tt>
+ 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>
- <heading>Essential packages</heading>
+ </sect>
- <p>
- Some packages are tagged <tt>essential</tt>. (They have
- <tt>Essential: yes</tt> in their package control record.)
- This flag is used for packages that are <em>essential</em>
- for a system.</p>
+ <sect>
+ <heading>Base system</heading>
- <p>
- Since these packages cannot be easily removed (one has to
- specify an extra <em>force option</em> to
- <prgn>dpkg</prgn> to do so), this flag must not be used
- unless absolutely necessary. A shared library package
- must not be tagged <tt>essential</tt>; dependencies will
- prevent its premature removal, and we need to be able to
- remove it when it has been superseded.
- </p>
+ <p>
+ The <tt>base system</tt> is a minimum subset of the Debian
+ GNU/Linux system that is installed before everything else
+ on a new system. Thus, only very few packages are allowed
+ to go into the <tt>base</tt> section to keep the required
+ disk usage very small.
+ </p>
- <p>
- Since dpkg will not prevent upgrading of other packages
- while an <tt>essential</tt> package is in an unconfigured
+ <p>
+ Most of these packages will have the priority value
+ <tt>required</tt> or at least <tt>important</tt>, and many
+ of them will be tagged <tt>essential</tt> (see below).
+ </p>
+ </sect>
+
+ <sect>
+ <heading>Essential packages</heading>
+
+ <p>
+ Some packages are tagged <tt>essential</tt> for a system
+ using the <tt>Essential</tt> control file field.
+ The format of the <tt>Essential</tt> control field is
+ described in <ref id="f-Essential">.
+ </p>
+
+ <p>
+ Since these packages cannot be easily removed (one has to
+ specify an extra <em>force option</em> to
+ <prgn>dpkg</prgn> to do so), this flag must not be used
+ unless absolutely necessary. A shared library package
+ must not be tagged <tt>essential</tt>; dependencies will
+ prevent its premature removal, and we need to be able to
+ remove it when it has been superseded.
+ </p>
+
+ <p>
+ Since dpkg will not prevent upgrading of other packages
+ while an <tt>essential</tt> package is in an unconfigured
state, all <tt>essential</tt> packages must supply all of
their core functionality even when unconfigured. If the
package cannot satisfy this requirement it must not be
tagged as essential, and any packages depending on this
package must instead have explicit dependency fields as
appropriate.
- </p>
+ </p>
- <p>
- You must not tag any packages <tt>essential</tt> before
- this has been discussed on the <tt>debian-devel</tt>
- mailing list and a consensus about doing that has been
- reached.
- </p>
- </sect1>
- <sect1>
- <heading>Tasks</heading>
+ <p>
+ You must not tag any packages <tt>essential</tt> before
+ this has been discussed on the <tt>debian-devel</tt>
+ mailing list and a consensus about doing that has been
+ reached.
+ </p>
+ </sect>
- <p>
- The Debian install process allows the user to choose from
- a number of common tasks which a Debian system can be used to
- perform. Selecting a task with <prgn>tasksel</prgn> causes
- a set of packages that are useful in performing that task to be
- installed.
- </p>
+ <sect>
+ <heading>Tasks</heading>
- <p>
- This set of packages is all available packages which have the
- name of the selected task in the <tt>Task</tt> field of their
- control file. The format of this field is a list of tasks,
- separated by commas.
- </p>
+ <p>
+ The Debian install process allows the user to choose from
+ a number of common tasks which a Debian system can be used to
+ perform. Selecting a task with <prgn>tasksel</prgn> causes
+ a set of packages that are useful in performing that task to be
+ installed.
+ </p>
- You should not tag any packages as belonging to a task
- before this has been discussed on the
- <em>debian-devel</em> mailing list and a consensus about
- doing that has been reached.
- </p>
+ <p>
+ This set of packages is all available packages which have the
+ name of the selected task in the <tt>Task</tt> field of their
+ control file. The format of this field is a list of tasks,
+ separated by commas.
+ </p>
- <p>
- For third parties (and historical reasons), tasksel also
- supports constructing tasks based on <em>task
- packages</em>. These are packages whose names begin with
- <em>task-</em>. Task packages should not be included in the
- Debian archive.
- </p>
- </sect1>
+ <p>
+ You should not tag any packages as belonging to a task
+ before this has been discussed on the
+ <em>debian-devel</em> mailing list and a consensus about
+ doing that has been reached.
+ </p>
- <sect1 id="maintscripts">
- <heading>Maintainer Scripts</heading>
+ <p>
+ For third parties (and historical reasons), tasksel also
+ supports constructing tasks based on <em>task
+ packages</em>. These are packages whose names begin with
+ <em>task-</em>. Task packages should not be included in the
+ Debian archive.
+ </p>
+ </sect>
- <p>
- The package installation scripts should avoid producing
- output which it is unnecessary for the user to see and
- should rely on <prgn>dpkg</prgn> to stave off boredom on
- the part of a user installing many packages. This means,
- amongst other things, using the <tt>--quiet</tt> option on
- <prgn>install-info</prgn>.</p>
+ <sect id="maintscripts">
+ <heading>Maintainer Scripts</heading>
- <p>
- Errors which occur during the execution of an installation
- script must be checked and the installation must not
- continue after an error.
- </p>
+ <p>
+ The package installation scripts should avoid producing
+ output which it is unnecessary for the user to see and
+ should rely on <prgn>dpkg</prgn> to stave off boredom on
+ the part of a user installing many packages. This means,
+ amongst other things, using the <tt>--quiet</tt> option on
+ <prgn>install-info</prgn>.
+ </p>
- <p>
- Note that in general <ref id="scripts"> applies to package
- maintainer scripts, too.
- </p>
+ <p>
+ Errors which occur during the execution of an installation
+ script must be checked and the installation must not
+ continue after an error.
+ </p>
+ <p>
+ Note that in general <ref id="scripts"> applies to package
+ maintainer scripts, too.
+ </p>
+
+ <p>
+ You should not use <prgn>dpkg-divert</prgn> on a file
+ belonging to another package without consulting the
+ maintainer of that package first.
+ </p>
+
+ <p>
+ All packages which supply an instance of a common command
+ name (or, in general, filename) should generally use
+ <prgn>update-alternatives</prgn>, so that they may be
+ installed together. If <prgn>update-alternatives</prgn>
+ is not used, then each package must use
+ <tt>Conflicts</tt> to ensure that other packages are
+ de-installed. (In this case, it may be appropriate to
+ specify a conflict against earlier versions of something
+ that previously did not use
+ <prgn>update-alternatives</prgn>; this is an exception to
+ the usual rule that versioned conflicts should be
+ avoided.)
+ </p>
+
+ <sect1 id="maintscriptprompt">
+ <heading>Prompting in maintainer scripts</heading>
<p>
- You should not use <prgn>dpkg-divert</prgn> on a file
- belonging to another package without consulting the
- maintainer of that package first.
+ Package maintainer scripts may prompt the user if
+ necessary. Prompting should be done by communicating
+ through a program, such as <prgn>debconf</prgn>, which
+ conforms to the Debian Configuration management
+ specification, version 2 or higher. Prompting the user by
+ other means, such as by hand<footnote>
+ From the Jargon file: by hand 2. By extension,
+ writing code which does something in an explicit or
+ low-level way for which a presupplied library
+ (<em>debconf, in this instance</em>) routine ought
+ to have been available.
+ </footnote>, is now deprecated.
</p>
<p>
- All packages which supply an instance of a common command
- name (or, in general, filename) should generally use
- <prgn>update-alternatives</prgn>, so that they may be
- installed together. If <prgn>update-alternatives</prgn>
- is not used, then each package must use
- <tt>Conflicts</tt> to ensure that other packages are
- de-installed. (In this case, it may be appropriate to
- specify a conflict against earlier versions of something
- that previously did not use
- <prgn>update-alternatives</prgn>; this is an exception to
- the usual rule that versioned conflicts should be
- avoided.)
+ The Debian Configuration management specification is included
+ in the <file>debconf_specification</file> files in the
+ <package>debian-policy</package> package.
+ It is also available from the Debian web mirrors at
+ <tt><url name="/doc/packaging-manuals/debconf_specification.html"
+ id="http://www.debian.org/doc/packaging-manuals/debconf_specification.html"></tt>
+ 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>
-
- <sect2>
- <heading>Prompting in maintainer scripts</heading>
- <p>
- Package maintainer scripts may prompt the user if
- necessary. Prompting may be accomplished by hand, or by
- communicating with a program, such as
- <prgn>debconf</prgn>, which conforms to the Debian
- Configuration management specification, version 2 or
- higher. These are included in the
- <file>debconf_specification</file> files in the
- <package>debian-policy</package> package.
- You may also find this file on the FTP site
- <ftpsite>ftp.debian.org</ftpsite> in
- <ftppath>/debian/doc/package-developer/debconf_specification.txt.gz</ftppath>
- or on your local mirror.<footnote>
- <p>
- 4% of Debian packages [see <url
- id="http://kitenet.net/programs/debconf/stats/"
- name="Debconf stats">] currently use
- <package>debconf</package> to prompt the user at
- install time, and this number is growing daily. The
- benefits of using debconf are briefly explained at
- <url
- id="http://kitenet.net/doc/debconf-doc/introduction.html"
- name="Debconf introduction">; they include
- preconfiguration, (mostly) noninteractive
- installation, elimination of redundant prompting,
- consistency of user interface, etc.
- </p>
- <p>
- With this increasing number of packages using
- <package>debconf</package>, plus the existance of a
- nascent second implementation of the Debian
- configuration management system
- (<package>cdebconf</package>), and the stabilization
- of the protocol these things use, the time has
- finally come to reflect the use of these things in
- policy.
-
- </p>
- </footnote>
- </p>
- <p>
- Packages which use the Debian Configuration management
- specification may contain an additional
- <prgn>config</prgn> script and a <tt>templates</tt>
- file in their control archive. The <prgn>config</prgn>
- script might be run before the <prgn>preinst</prgn>
- script, and before the package is unpacked or any of its
- dependencies or pre-dependancies are satisfied.
- Therefore it must work using only the tools present in
- <em>essential</em> packages.<footnote>
- <p>
+ <p>
+ Packages which use the Debian Configuration management
+ specification may contain an additional
+ <prgn>config</prgn> script and a <tt>templates</tt>
+ file in their control archive<footnote>
+ The control.tar.gz inside the .deb.
+ See <manref name="deb" section="5">.
+ </footnote>.
+ The <prgn>config</prgn> script might be run before the
+ <prgn>preinst</prgn> script, and before the package is unpacked
+ or any of its dependencies or pre-dependancies are satisfied.
+ Therefore it must work using only the tools present in
+ <em>essential</em> packages.<footnote>
<package>Debconf</package> or another tool that
implements the Debian Configuration management
specification will also be installed, and any
versioned dependencies on it will be satisfied
before preconfiguration begins.
- </p>
- </footnote>
- </p>
-
- <p>
- Packages should try to minimize the amount of prompting
- they need to do, and they should ensure that the user
- will only ever be asked each question once. This means
- that packages should try to use appropriate shared
- configuration files (such as <file>/etc/papersize</file> and
- <file>/etc/news/server</file>), and shared
- <package>debconf</package> variables rather than each
- prompting for their own list of required pieces of
- information.
- </p>
-
- <p>
- It also means that an upgrade should not ask the same
- questions again, unless the user has used <tt>dpkg
- --purge</tt> to remove the package's configuration. The
- answers to configuration questions should be stored in an
- appropriate place in <file>/etc</file> so that the user can
- modify them, and how this has been done should be
- documented.</p>
-
- <p>
- If a package has a vitally important piece of
- information to pass to the user (such as "don't run me
- as I am, you must edit the following configuration files
- first or you risk your system emitting badly-formatted
- messages"), it should display this in the
- <prgn>config</prgn> or <prgn>postinst</prgn> script and
- prompt the user to hit return to acknowledge the
- message. Copyright messages do not count as vitally
- important (they belong in
- <file>/usr/share/doc/<var>package</var>/copyright</file>);
- neither do instructions on how to use a program (these
- should be in on-line documentation, where all the users
- can see them).</p>
-
- <p>
- Any necessary prompting should almost always be confined
- to the <prgn>config</prgn> or <prgn>postinst</prgn>
- script. If it is done in the <prgn>postinst</prgn>, it
- should be protected with a conditional so that
- unnecessary prompting doesn't happen if a package's
- installation fails and the <prgn>postinst</prgn> is
- called with <tt>abort-upgrade</tt>,
- <tt>abort-remove</tt> or <tt>abort-deconfigure</tt>.</p>
- </sect1>
- </sect>
-
- <sect>
- <heading>Source packages</heading>
-
- <sect1 id="standardsversion">
- <heading>Standards conformance</heading>
-
- <p>
- In the source package's <tt>Standards-Version</tt> control
- field, you should specify the most recent version number
- of this policy document with which your package complied
- when it was last updated. The current version number is
- &version;.
+ </footnote>
</p>
<p>
- This information may be used to file bug reports
- automatically if your package becomes too much out of
- date.
+ Packages should try to minimize the amount of prompting
+ they need to do, and they should ensure that the user
+ will only ever be asked each question once. This means
+ that packages should try to use appropriate shared
+ configuration files (such as <file>/etc/papersize</file> and
+ <file>/etc/news/server</file>), and shared
+ <package>debconf</package> variables rather than each
+ prompting for their own list of required pieces of
+ information.
</p>
<p>
- The version number has four components: major and minor
- version number and major and minor patch level. When the
- standards change in a way that requires every package to
- change the major number will be changed. Significant
- changes that will require work in many packages will be
- signaled by a change to the minor number. The major patch
- level will be changed for any change to the meaning of the
- standards, however small; the minor patch level will be
- changed when only cosmetic, typographical or other edits
- are made which neither change the meaning of the document
- nor affect the contents of packages.</p>
+ It also means that an upgrade should not ask the same
+ questions again, unless the user has used
+ <tt>dpkg --purge</tt> to remove the package's configuration.
+ The answers to configuration questions should be stored in an
+ appropriate place in <file>/etc</file> so that the user can
+ modify them, and how this has been done should be
+ documented.
+ </p>
<p>
- Thus only the first three components of the policy version
- are significant in the <em>Standards-Version</em> control
- field, and so either these three components or the all
- four components may be specified.<footnote>
- <p>
- In the past, people specified the full version number
- in the Standards-Version field, for example "2.3.0.0".
- Since minor patch-level changes don"t introduce new
- policy, it was thought it would be better to relax
- policy and only require the first 3 components to be
- specified, in this example "2.3.0". All four
- components may still be used if someone wishes to do
- so.
- </p>
- </footnote>
+ If a package has a vitally important piece of
+ information to pass to the user (such as "don't run me
+ as I am, you must edit the following configuration files
+ first or you risk your system emitting badly-formatted
+ messages"), it should display this in the
+ <prgn>config</prgn> or <prgn>postinst</prgn> script and
+ prompt the user to hit return to acknowledge the
+ message. Copyright messages do not count as vitally
+ important (they belong in
+ <file>/usr/share/doc/<var>package</var>/copyright</file>);
+ neither do instructions on how to use a program (these
+ should be in on-line documentation, where all the users
+ can see them).
</p>
<p>
- You should regularly, and especially if your package has
- become out of date, check for the newest Policy Manual
- available and update your package, if necessary. When your
- package complies with the new standards you should update the
- <tt>Standards-Version</tt> source package field and
- release it.<footnote>
- <p>
- See the file <file>upgrading-checklist</file> for
- information about policy which has changed between
- different versions of this document.
- </p>
- </footnote>
+ Any necessary prompting should almost always be confined
+ to the <prgn>config</prgn> or <prgn>postinst</prgn>
+ script. If it is done in the <prgn>postinst</prgn>, it
+ should be protected with a conditional so that
+ unnecessary prompting doesn't happen if a package's
+ installation fails and the <prgn>postinst</prgn> is
+ called with <tt>abort-upgrade</tt>,
+ <tt>abort-remove</tt> or <tt>abort-deconfigure</tt>.
</p>
</sect1>
+ </sect>
- <sect1 id="pkg-relations">
- <heading>Package relationships</heading>
+ </chapt>
- <p>
- Source packages should specify which binary packages they
- require to be installed or not to be installed in order to
- build correctly. For example, if building a package
- requires a certain compiler, then the compiler should be
- specified as a build-time dependency.
- </p>
- <p>
- It is not necessary to explicitly specify build-time
- relationships on a minimal set of packages that are always
- needed to compile, link and put in a Debian package a
- standard "Hello World!" program written in C or C++. The
- required packages are called <em>build-essential</em>, and
- an informational list can be found in
- <file>/usr/share/doc/build-essential/list</file> (which is
- contained in the <tt>build-essential</tt>
- package).<footnote>
- <p>Rationale:
- <list compact="compact">
- <item>
- <p>This allows maintaining the list separately
- from the policy documents (the list does not
- need the kind of control that the policy
- documents do).
- </p>
- </item>
- <item>
- <p>
- Having a separate package allows one to install
- the build-essential packages on a machine, as
+ <chapt id="source">
+ <heading>Source packages</heading>
+
+ <sect id="standardsversion">
+ <heading>Standards conformance</heading>
+
+ <p>
+ Source packages should specify the most recent version number
+ of this policy document with which your package complied
+ when it was last updated.
+ </p>
+
+ <p>
+ This information may be used to file bug reports
+ automatically if your package becomes too much out of date.
+ </p>
+
+ <p>
+ The version is specified in the <tt>Standards-Version</tt>
+ control field.
+ The format of the <tt>Standards-Version</tt> field is
+ described in <ref id="f-Standards-Version">.
+ </p>
+
+ <p>
+ You should regularly, and especially if your package has
+ become out of date, check for the newest Policy Manual
+ available and update your package, if necessary. When your
+ package complies with the new standards you should update the
+ <tt>Standards-Version</tt> source package field and
+ release it.<footnote>
+ See the file <file>upgrading-checklist</file> for
+ information about policy which has changed between
+ different versions of this document.
+ </footnote>
+ </p>
+
+ </sect>
+
+ <sect id="pkg-relations">
+ <heading>Package relationships</heading>
+
+ <p>
+ Source packages should specify which binary packages they
+ require to be installed or not to be installed in order to
+ build correctly. For example, if building a package
+ requires a certain compiler, then the compiler should be
+ specified as a build-time dependency.
+ </p>
+
+ <p>
+ It is not necessary to explicitly specify build-time
+ relationships on a minimal set of packages that are always
+ needed to compile, link and put in a Debian package a
+ standard "Hello World!" program written in C or C++. The
+ required packages are called <em>build-essential</em>, and
+ an informational list can be found in
+ <file>/usr/share/doc/build-essential/list</file> (which is
+ contained in the <tt>build-essential</tt>
+ package).<footnote>
+ Rationale:
+ <list compact="compact">
+ <item>
+ This allows maintaining the list separately
+ from the policy documents (the list does not
+ need the kind of control that the policy
+ documents do).
+ </item>
+ <item>
+ 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>
+ </footnote>
+ </p>
- <p>
- When specifying the set of build-time dependencies, one
- should list only those packages explicitly required by the
- build. It is not necessary to list packages which are
- required merely because some other package in the list of
- build-time dependencies depends on them.<footnote>
- <p>
+ <p>
+ When specifying the set of build-time dependencies, one
+ should list only those packages explicitly required by the
+ build. It is not necessary to list packages which are
+ required merely because some other package in the list of
+ build-time dependencies depends on them.<footnote>
The reason for this is that dependencies change, and
you should list all those packages, and <em>only</em>
those packages that <em>you</em> need directly. What
them: installation of <package>libimlib2-dev</package>
will automatically ensure that all of its run-time
dependencies are satisfied.
- </p>
- </footnote>
- </p>
-
- <p>
- If build-time dependencies are specified, it must be
- possible to build the package and produce working binaries
- on a system with only essential and build-essential
- packages installed and also those required to satisfy the
- build-time relationships (including any implied
- relationships). In particular, this means that version
- clauses should be used rigorously in build-time
- relationships so that one cannot produce bad or
- inconsistently configured packages when the relationships
- are properly satisfied.
- </p>
-
- <p>
- <ref id="relationships"> explains the technical details.
- </p>
-
- <sect1>
- <heading>Changes to the upstream sources</heading>
-
- <p>
- If changes to the source code are made that are not
- specific to the needs of the Debian system, they should be
- sent to the upstream authors in whatever form they prefer
- so as to be included in the upstream version of the
- package.</p>
+ </footnote>
+ </p>
- <p>
- If you need to configure the package differently for
- Debian or for Linux, and the upstream source doesn't
- provide a way to do so, you should add such configuration
- facilities (for example, a new <prgn>autoconf</prgn> test
- or <tt>#define</tt>) and send the patch to the upstream
- authors, with the default set to the way they originally
- had it. You can then easily override the default in your
- <file>debian/rules</file> or wherever is appropriate.</p>
+ <p>
+ If build-time dependencies are specified, it must be
+ possible to build the package and produce working binaries
+ on a system with only essential and build-essential
+ packages installed and also those required to satisfy the
+ build-time relationships (including any implied
+ relationships). In particular, this means that version
+ clauses should be used rigorously in build-time
+ relationships so that one cannot produce bad or
+ inconsistently configured packages when the relationships
+ are properly satisfied.
+ </p>
- You should make sure that the <prgn>configure</prgn> utility
- detects the correct architecture specification string
- (refer to <ref id="arch-spec"> for details).</p>
+ <p>
+ <ref id="relationships"> explains the technical details.
+ </p>
+ </sect>
- <p>
- If you need to edit a <prgn>Makefile</prgn> where
- GNU-style <prgn>configure</prgn> scripts are used, you
- should edit the <file>.in</file> files rather than editing the
- <prgn>Makefile</prgn> directly. This allows the user to
- reconfigure the package if necessary. You should
- <em>not</em> configure the package and edit the generated
- <prgn>Makefile</prgn>! This makes it impossible for
- someone else to later reconfigure the package.</p>
+ <sect>
+ <heading>Changes to the upstream sources</heading>
- <p>
- You should document your changes and updates to the source
- package properly in the <file>debian/changelog</file> file.
- For more information, please see <ref id="changelogs">.
- </p>
- </sect1>
+ <p>
+ If changes to the source code are made that are not
+ specific to the needs of the Debian system, they should be
+ sent to the upstream authors in whatever form they prefer
+ so as to be included in the upstream version of the
+ package.
+ </p>
+ <p>
+ If you need to configure the package differently for
+ Debian or for Linux, and the upstream source doesn't
+ provide a way to do so, you should add such configuration
+ facilities (for example, a new <prgn>autoconf</prgn> test
+ or <tt>#define</tt>) and send the patch to the upstream
+ authors, with the default set to the way they originally
+ had it. You can then easily override the default in your
+ <file>debian/rules</file> or wherever is appropriate.
+ </p>
- <sect1>
- <heading>Error trapping in makefiles</heading>
+ <p>
+ You should make sure that the <prgn>configure</prgn> utility
+ detects the correct architecture specification string
+ (refer to <ref id="arch-spec"> for details).
+ </p>
- When <prgn>make</prgn> invokes a command in a makefile
- (including your package's upstream makefiles and
- <file>debian/rules</file>), it does so using <prgn>sh</prgn>. This
- means that <prgn>sh</prgn>'s usual bad error handling
- properties apply: if you include a miniature script as one
- of the commands in your makefile you'll find that if you
- don't do anything about it then errors are not detected
- and <prgn>make</prgn> will blithely continue after
- problems.</p>
+ <p>
+ If you need to edit a <prgn>Makefile</prgn> where
+ GNU-style <prgn>configure</prgn> scripts are used, you
+ should edit the <file>.in</file> files rather than editing the
+ <prgn>Makefile</prgn> directly. This allows the user to
+ reconfigure the package if necessary. You should
+ <em>not</em> configure the package and edit the generated
+ <prgn>Makefile</prgn>! This makes it impossible for
+ someone else to later reconfigure the package.
+ </p>
- <p>
- Every time you put more than one shell command (this
- includes using a loop) in a makefile command you
- must make sure that errors are trapped. For
- simple compound commands, such as changing directory and
- then running a program, using <tt>&&</tt> rather
- than semicolon as a command separator is sufficient. For
- more complex commands including most loops and
- conditionals you should include a separate <tt>set -e</tt>
- command at the start of every makefile command that's
- actually one of these miniature shell scripts.</p></sect1>
+ </sect>
+ <sect id="dpkgchangelog">
+ <heading>Debian changelog: <file>debian/changelog</file></heading>
- <sect1>
- <heading>Obsolete constructs and libraries</heading>
+ <p>
+ Changes in the Debian version of the package should be
+ briefly explained in the Debian changelog file
+ <file>debian/changelog</file>. This includes modifications
+ made in the Debian package compared to the upstream one
+ as well as other changes and updates to the package.
+ <footnote>
+ Although there is nothing stopping an author who is also
+ the Debian maintainer from using this changelog for all
+ their changes, it will have to be renamed if the Debian
+ and upstream maintainers become different people. In such
+ a case, however, it might be better to maintain the package
+ as a non-native package.
+ </footnote>
+ </p>
- <p>
- The include file <tt><varargs.h></tt> is
- provided to support end-users compiling very old software;
- the library <tt>libtermcap</tt> is provided to support the
- execution of software which has been linked against it
- (either old programs or those such as Netscape which are
- only available in binary form).</p>
+ <p>
+ Mistakes in changelogs are usually best rectified by making
+ a new changelog entry rather than "rewriting history" by
+ editing old changelog entries.
+ </p>
- <p>
- Debian packages should be patched to use
- <tt><stdarg.h></tt> and <tt>ncurses</tt>
- instead.
- </p>
- </sect1>
- </sect>
- </chapt>
+ <p>
+ The format of the <file>debian/changelog</file> allows the
+ package building tools to discover which version of the package
+ is being built and find out other release-specific information.
+ </p>
- <chapt id="controlfields"><heading>Control files and their fields</heading>
+ <p>
+ That format is a series of entries like this:
- <p>
- Many of the tools in the package management suite manipulate
- data represented in a common format, known as <em>control
- data</em>. The data is often stored in <em>control
- files</em>. Binary and source packages have control files,
- and the <file>.changes</file> files which control the installation
- of uploaded files are also in control file format.
- <prgn>dpkg</prgn>'s internal databases are in a similar
- format.
- </p>
+<example compact="compact">
+<var>package</var> (<var>version</var>) <var>distribution(s)</var>; urgency=<var>urgency</var>
+ <var>
+ [optional blank line(s), stripped]
+ </var>
+ * <var>change details</var>
+ <var>more change details</var>
+ <var>
+ [blank line(s), included in output of dpkg-parsechangelog]
+ </var>
+ * <var>even more change details</var>
+ <var>
+ [optional blank line(s), stripped]
+ </var>
+ -- <var>maintainer name</var> <<var>email address</var>><var>[two spaces]</var> <var>date</var>
+</example>
+ </p>
- <sect id="controlsyntax"><heading>Syntax of control files</heading>
+ <p>
+ <var>package</var> and <var>version</var> are the source
+ package name and version number.
+ </p>
<p>
- A control file consists of one or more paragraphs of fields.
- The paragraphs are separated by blank lines. Some control
- files allow only one paragraph; others allow several, in
- which case each paragraph usually refers to a different
- package. (For example, in source packages, the first
- paragraph refers to the source package, and later paragraphs
- refer to binary packages generated from the source.)
+ <var>distribution(s)</var> lists the distributions where
+ this version should be installed when it is uploaded - it
+ is copied to the <tt>Distribution</tt> field in the
+ <file>.changes</file> file. See <ref id="f-Distribution">.
</p>
<p>
- Each paragraph consists of a series of data fields; each
- field consists of the field name, followed by a colon and
- then the data/value associated with that field. It ends at
- the end of the line. Horizontal whitespace (spaces and
- tabs) may occur immediately before or after the value and is
- ignored there; it is conventional to put a single space
- after the colon. For example, a field might be:
- <example compact="compact">
-Package: libc6
- </example>
- the field name is <tt>Package</tt> and the field value
- <tt>libc6</tt>.
+ <var>urgency</var> is the value for the <tt>Urgency</tt>
+ field in the <file>.changes</file> file for the upload
+ (see <ref id="f-Urgency">). It is not possible to specify
+ an urgency containing commas; commas are used to separate
+ <tt><var>keyword</var>=<var>value</var></tt> settings in the
+ <prgn>dpkg</prgn> changelog format (though there is
+ currently only one useful <var>keyword</var>,
+ <tt>urgency</tt>).<footnote>
+ 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.
+ </footnote>
</p>
<p>
- Some fields' values may span several lines; in this case
- each continuation line <em>must</em> start with a space or
- tab. Any trailing spaces or tabs at the end of individual
- lines of a field value are ignored.
+ The change details may in fact be any series of lines
+ starting with at least two spaces, but conventionally each
+ change starts with an asterisk and a separating space and
+ continuation lines are indented so as to bring them in
+ line with the start of the text above. Blank lines may be
+ used here to separate groups of changes, if desired.
</p>
<p>
- Except where otherwise stated only a single line of data is
- allowed and whitespace is not significant in a field body.
- Whitespace must not appear inside names (of packages,
- architectures, files or anything else) or version numbers,
- or between the characters of multi-character version
- relationships.
+ If this upload resolves bugs recorded in the Bug Tracking
+ System (BTS), they may be automatically closed on the
+ inclusion of this package into the Debian archive by
+ including the string: <tt>closes: Bug#<var>nnnnn</var></tt>
+ in the change details.<footnote>
+ To be precise, the string should match the following
+ Perl regular expression:
+ <example>
+/closes:\s*(?:bug)?\#?\s?\d+(?:,\s*(?:bug)?\#?\s?\d+)*/i
+ </example>
+ Then all of the bug numbers listed will be closed by the
+ archive maintenance script (<prgn>katie</prgn>), or in
+ the case of an NMU, marked as fixed.
+ </footnote>
+ This information is conveyed via the <tt>Closes</tt> field
+ in the <tt>.changes</tt> file (see <ref id="f-Closes">).
</p>
<p>
- Field names are not case-sensitive, but it is usual to
- capitalize the field names using mixed case as shown below.
+ The maintainer name and email address used in the changelog
+ should be the details of the person uploading <em>this</em>
+ version. They are <em>not</em> necessarily those of the
+ usual package maintainer. The information here will be
+ copied to the <tt>Changed-By</tt> field in the
+ <tt>.changes</tt> file (see <ref id="f-Changed-By">),
+ and then later used to send an acknowledgement when the
+ upload has been installed.
</p>
<p>
- Blank lines, or lines consisting only of spaces and tabs,
- are not allowed within field values or between fields - that
- would mean a new paragraph.
+ The <var>date</var> should be in RFC822 format<footnote>
+ This is generated by the <prgn>822-date</prgn>
+ program.
+ </footnote>; it should include the time zone specified
+ numerically, with the time zone name or abbreviation
+ optionally present as a comment in parentheses.
</p>
- </sect>
+ <p>
+ The first "title" line with the package name should start
+ at the left hand margin; the "trailer" line with the
+ maintainer and date details should be preceded by exactly
+ one space. The maintainer details and the date must be
+ separated by exactly two spaces.
+ </p>
- <sect><heading>List of fields</heading>
<p>
- This list here is not supposed to be exhaustive. Most fields
- are dealt with elsewhere in this document.
+ For more information on placement of the changelog files
+ within binary packages, please see <ref id="changelogs">.
</p>
- <sect1 id="f-Package"><heading><tt>Package</tt>
- </heading>
+
+ <sect1><heading>Alternative changelog formats</heading>
<p>
- The name of the binary package. Package names consist of
- lower case letters (<tt>a-z</tt>), digits (<tt>0-9</tt>),
- plus (<tt>+</tt>) and minus (<tt>-</tt>) signs, and
- periods (<tt>.</tt>).
+ In non-experimental packages you must use a format for
+ <file>debian/changelog</file> which is supported by the most
+ recent released version of <prgn>dpkg</prgn>.
</p>
<p>
- They must be at least two characters long and must start
- with an alphanumeric character. The use of lowercase
- package names is required unless the package you're
- building (or referring to, in other fields) is already
- using uppercase characters.</p>
+ It is possible to use a format different from the standard
+ one by providing a changelog parser for the format you wish
+ to use. The parser must have an API compatible with that
+ expected by <prgn>dpkg-genchanges</prgn> and
+ <prgn>dpkg-gencontrol</prgn>, and it must not interact with
+ the user at all.
+ <footnote>
+ If there is general interest in the new format, you should
+ contact the <package>dpkg</package> maintainer to have the
+ parser script for it included in the <prgn>dpkg</prgn>
+ package. (You will need to agree that the parser and its
+ manpage may be distributed under the GNU GPL, just as the rest
+ of <prgn>dpkg</prgn> is.)
+ </footnote>
+ </p>
</sect1>
+ </sect>
- <sect1 id="f-Version"><heading><tt>Version</tt>
- </heading>
+ <sect>
+ <heading>Error trapping in makefiles</heading>
- <p>
- This lists the source or binary package's version number -
- see <ref id="versions">.
- </p>
+ <p>
+ When <prgn>make</prgn> invokes a command in a makefile
+ (including your package's upstream makefiles and
+ <file>debian/rules</file>), it does so using <prgn>sh</prgn>. This
+ means that <prgn>sh</prgn>'s usual bad error handling
+ properties apply: if you include a miniature script as one
+ of the commands in your makefile you'll find that if you
+ don't do anything about it then errors are not detected
+ and <prgn>make</prgn> will blithely continue after
+ problems.
+ </p>
- </sect1>
+ <p>
+ Every time you put more than one shell command (this
+ includes using a loop) in a makefile command you
+ must make sure that errors are trapped. For
+ simple compound commands, such as changing directory and
+ then running a program, using <tt>&&</tt> rather
+ than semicolon as a command separator is sufficient. For
+ more complex commands including most loops and
+ conditionals you should include a separate <tt>set -e</tt>
+ command at the start of every makefile command that's
+ actually one of these miniature shell scripts.
+ </p>
+ </sect>
- <sect1
- id="f-Standards-Version"><heading><tt>Standards-Version</tt>
- </heading>
+ <sect id="timestamps">
+ <heading>Time Stamps</heading>
+ <p>
+ Maintainers should preserve the modification times of the
+ upstream source files in a package, as far as is reasonably
+ possible.<footnote>
+ The rationale is that there is some information conveyed
+ by knowing the age of the file, for example, you could
+ recognize that some documentation is very old by looking
+ at the modification time, so it would be nice if the
+ modification time of the upstream source would be
+ preserved.
+ </footnote>
+ </p>
+ </sect>
- <p>
- The most recent version of the standards (the policy
- manual and associated texts) with which the package
- complies. This is updated manually when editing the
- source package to conform to newer standards; it can
- sometimes be used to tell when a package needs attention.
- Its format is described above; see
- <ref id="standardsversion">.
- </p>
- </sect1>
+ <sect id="restrictions">
+ <heading>Restrictions on objects in source packages</heading>
+ <p>
+ The source package may not contain any hard links<footnote>
+ <p>
+ This is not currently detected when building source
+ packages, but only when extracting
+ them.
+ </p>
+ <p>
+ Hard links may be permitted at some point in the
+ future, but would require a fair amount of
+ work.
+ </p>
+ </footnote>, device special files, sockets or setuid or
+ setgid files.<footnote>
+ Setgid directories are allowed.
+ </footnote>
+ </p>
+ </sect>
- <sect1 id="f-Distribution"><heading><tt>Distribution</tt>
- </heading>
-
- <p>
- In a <file>.changes</file> file or parsed changelog output
- this contains the (space-separated) name(s) of the
- distribution(s) where this version of the package should
- be installed. Valid distributions are determined by the
- archive maintainers.<footnote>
- Current distribution names are:
- <taglist compact="compact">
- <tag><em>stable</em></tag>
- <item>
- <p>
- This is the current "released" version of Debian
- GNU/Linux. Once the distribution is
- <em>stable</em> only security fixes and other
- major bug fixes are allowed. When changes are
- made to this distribution, the release number is
- increased (for example: 2.2r1 becomes 2.2r2 then
- 2.2r3, etc).
- </p>
- </item>
-
- <tag><em>unstable</em></tag>
- <item>
- <p>
- This distribution value refers to the
- <em>developmental</em> part of the Debian
- distribution tree. New packages, new upstream
- versions of packages and bug fixes go into the
- <em>unstable</em> directory tree. Download from
- this distribution at your own risk.
- </p>
- </item>
-
- <tag><em>testing</em></tag>
- <item>
- <p>
- This distribution value refers to the
- <em>testing</em> part of the Debian distribution
- tree. It receives its packages from the
- unstable distribution after a short time lag to
- ensure that there are no major issues with the
- unstable packages. It is less prone to breakage
- than unstable, but still risky. It is not
- possible to upload packages directly to
- <em>testing</em>.
- </p>
- </item>
-
- <tag><em>frozen</em></tag>
- <item>
- <p>
- From time to time, the <em>testing</em>
- distribution enters a state of "code-freeze" in
- anticipation of release as a <em>stable</em>
- version. During this period of testing only
- fixes for existing or newly-discovered bugs will
- be allowed. The exact details of this stage are
- determined by the Release Manager.
- </p>
- </item>
-
- <tag><em>experimental</em></tag>
- <item>
- <p>
- The packages with this distribution value are
- deemed by their maintainers to be high
- risk. Oftentimes they represent early beta or
- developmental packages from various sources that
- the maintainers want people to try, but are not
- ready to be a part of the other parts of the
- Debian distribution tree. Download at your own
- risk.
- </p>
- </item>
- </taglist>
-
- You should list <em>all</em> distributions that the
- package should be installed into.
- </footnote>
- </p>
- </sect1>
-
-
- </sect>
- </chapt>
-
- <chapt id="versions"><heading>Version numbering</heading>
-
- <p>
- Every package has a version number recorded in its
- <tt>Version</tt> control file field.
- </p>
-
- <p>
- The package management system imposes an ordering on version
- numbers, so that it can tell whether packages are being up- or
- downgraded and so that package system front end applications
- can tell whether a package it finds available is newer than
- the one installed on the system. The version number format
- has the most significant parts (as far as comparison is
- concerned) at the beginning.
- </p>
-
- <p>
- The version number format is:
- [<var>epoch</var><tt>:</tt>]<var>upstream_version</var>[<tt>-</tt><var>debian_revision</var>]
- </p>
-
- <p>
- The three components here are:
- <taglist>
- <tag><var>epoch</var></tag>
- <item>
- <p>
- This is a single (generally small) unsigned integer. It
- may be omitted, in which case zero is assumed. If it is
- omitted then the <var>upstream_version</var> may not
- contain any colons.
- </p>
-
- <p>
- It is provided to allow mistakes in the version numbers
- of older versions of a package, and also a package's
- previous version numbering schemes, to be left behind.
- </p>
- </item>
-
- <tag><var>upstream_version</var></tag>
- <item>
- <p>
- This is the main part of the version number. It is
- usually the version number of the original ("upstream")
- package from which the <file>.deb</file> file has been made,
- if this is applicable. Usually this will be in the same
- format as that specified by the upstream author(s);
- however, it may need to be reformatted to fit into the
- package management system's format and comparison
- scheme.
- </p>
-
- <p>
- The comparison behavior of the package management system
- with respect to the <var>upstream_version</var> is
- described below. The <var>upstream_version</var>
- portion of the version number is mandatory.
- </p>
-
- <p>
- The <var>upstream_version</var> may contain only
- alphanumerics<footnote>
- <p>Alphanumerics are <tt>A-Za-z0-9</tt> only.</p>
- </footnote>
- and the characters <tt>.</tt> <tt>+</tt> <tt>-</tt>
- <tt>:</tt> (full stop, plus, hyphen, colon) and should
- start with a digit. If there is no
- <var>debian_revision</var> then hyphens are not allowed;
- if there is no <var>epoch</var> then colons are not
- allowed.</p>
- </item>
-
- <tag><var>debian_revision</var></tag>
- <item>
- <p>
- This part of the version number specifies the version of
- the Debian package based on the upstream version. It
- may contain only alphanumerics and the characters
- <tt>+</tt> and <tt>.</tt> (plus and full stop) and is
- compared in the same way as the
- <var>upstream_version</var> is.
- </p>
-
- <p>
- It is optional; if it isn't present then the
- <var>upstream_version</var> may not contain a hyphen.
- This format represents the case where a piece of
- software was written specifically to be turned into a
- Debian package, and so there is only one "debianization"
- of it and therefore no revision indication is required.
- </p>
-
- <p>
- It is conventional to restart the
- <var>debian_revision</var> at <tt>1</tt> each time the
- <var>upstream_version</var> is increased.
- </p>
-
- <p>
- The package management system will break the version
- number apart at the last hyphen in the string (if there
- is one) to determine the <var>upstream_version</var> and
- <var>debian_revision</var>. The absence of a
- <var>debian_revision</var> compares earlier than the
- presence of one (but note that the
- <var>debian_revision</var> is the least significant part
- of the version number).
- </p>
- </item>
- </taglist>
- </p>
-
- <p>
- The <var>upstream_version</var> and <var>debian_revision</var>
- parts are compared by the package management system using the
- same algorithm:
- </p>
-
- <p>
- The strings are compared from left to right.
- </p>
-
- <p>
- First the initial part of each string consisting entirely of
- non-digit characters is determined. These two parts (one of
- which may be empty) are compared lexically. If a difference
- is found it is returned. The lexical comparison is a
- comparison of ASCII values modified so that all the letters
- sort earlier than all the non-letters.
- </p>
-
- <p>
- Then the initial part of the remainder of each string which
- consists entirely of digit characters is determined. The
- numerical values of these two parts are compared, and any
- difference found is returned as the result of the comparison.
- For these purposes an empty string (which can only occur at
- the end of one or both version strings being compared) counts
- as zero.
- </p>
-
- <p>
- These two steps (comparing and removing initial non-digit
- strings and initial digit strings) are repeated until a
- difference is found or both strings are exhausted.
- </p>
-
- <p>
- Note that the purpose of epochs is to allow us to leave behind
- mistakes in version numbering, and to cope with situations
- where the version numbering scheme changes. It is
- <em>not</em> intended to cope with version numbers containing
- strings of letters which the package management system cannot
- interpret (such as <tt>ALPHA</tt> or <tt>pre-</tt>), or with
- silly orderings (the author of this manual has heard of a
- package whose versions went <tt>1.1</tt>, <tt>1.2</tt>,
- <tt>1.3</tt>, <tt>1</tt>, <tt>2.1</tt>, <tt>2.2</tt>,
- <tt>2</tt> and so forth).
- </p>
-
- <p>
- If an upstream package has problematic version numbers they
- should be converted to a sane form for use in the
- <tt>Version</tt> field.
- </p>
-
- <sect>
- <heading>Version numbers based on dates</heading>
- <p>
- In general, Debian packages should use the same version
- numbers as the upstream sources.</p>
-
- <p>
- However, in some cases where the upstream version number is
- based on a date (e.g., a development "snapshot" release) the
- package management system cannot handle these version
- numbers without epochs. For example, dpkg will consider
- "96May01" to be greater than "96Dec24".</p>
-
- <p>
- To prevent having to use epochs for every new upstream
- version, the version number should be changed to the
- following format in such cases: "19960501", "19961224". It
- is up to the maintainer whether he/she wants to bother the
- upstream maintainer to change the version numbers upstream,
- too.</p>
-
- <p>
- Note that other version formats based on dates which are
- parsed correctly by the package management system should
- <em>not</em> be changed.</p>
-
- <p>
- Native Debian packages (i.e., packages which have been
- written especially for Debian) whose version numbers include
- dates should always use the "YYYYMMDD" format.</p>
- </sect>
- </chapt>
-
- <chapt id="miscellaneous"><heading>Packaging Considerations</heading>
-
- <sect id="timestamps"><heading>Time Stamps</heading>
- <p>
- Maintainers should preserve the modification times of the
- upstream source files in a package, as far as is reasonably
- possible.<footnote>
- <p>
- The rationale is that there is some information conveyed
- by knowing the age of the file, for example, you could
- recognize that some documentation is very old by looking
- at the modification time, so it would be nice if the
- modification time of the upstream source would be
- preserved.
- </p>
- </footnote>
- </p>
- </sect>
-
- <sect id="debianrules"><heading><file>debian/rules</file> - the
- main building script</heading>
+ <sect id="debianrules">
+ <heading>Main building script: <file>debian/rules</file></heading>
<p>
This file must be an executable makefile, and contains the
</p>
<p>
- The required and optional targets are as follows:
+ The targets are as follows (required unless stated otherwise):
<taglist>
- <tag><tt>build</tt>, <tt>build-arch</tt> (optional),
- <tt>build-indep</tt> (optional)</tag>
+ <tag><tt>build</tt></tag>
<item>
<p>
- The <tt>build</tt> target should perform all
- non-interactive configuration and compilation of the
- package. If a package has an interactive pre-build
+ The <tt>build</tt> target should perform all the
+ configuration and compilation of the package.
+ If a package has an interactive pre-build
configuration routine, the Debianized source package
must either be built after this has taken place (so
that the binary package can be built without rerunning
complete. This will ensure that if <tt>debian/rules
build</tt> is run again it will not rebuild the whole
program.<footnote>
- <p>
Another common way to do this is for <tt>build</tt>
to depend on <prgn>build-stamp</prgn> and to do
nothing else, and for the <prgn>build-stamp</prgn>
<tt>.PHONY</tt> target). See the documentation of
<prgn>make</prgn> for more information on phony
targets.
- </p>
</footnote>
</p>
</item>
+ <tag><tt>build-arch</tt> (optional),
+ <tt>build-indep</tt> (optional)
+ </tag>
+ <item>
+ <p>
+ A package may also provide both of the targets
+ <tt>build-arch</tt> and <tt>build-indep</tt>.
+ The <tt>build-arch</tt> target, if provided, should
+ perform all the configuration and compilation required
+ for producing all architecture-dependant binary packages
+ (those packages for which the body of the
+ <tt>Architecture</tt> field in <tt>debian/control</tt>
+ is not <tt>all</tt>).
+ Similarly, the <tt>build-indep</tt> target, if
+ provided, should perform all the configuration and
+ compilation required for producing all
+ architecture-independent binary packages
+ (those packages for which the body of the
+ <tt>Architecture</tt> field in <tt>debian/control</tt>
+ is <tt>all</tt>).
+ The <tt>build</tt> target should depend on those of the
+ targets <tt>build-arch</tt> and <tt>build-indep</tt> that
+ are provided in the rules file.
+ </p>
+
+ <p>
+ If one or both of the targets <tt>build-arch</tt> and
+ <tt>build-indep</tt> are not provided, then invoking
+ <file>debian/rules</file> with one of the not-provided
+ targets as arguments should produce a exit status code
+ of 2. Usually this is provided automatically by make
+ if the target is missing.
+ </p>
+
+ <p>
+ The <tt>build-arch</tt> and <tt>build-indep</tt> targets
+ must not do anything that might require root privilege.
+ </p>
+ </item>
+
<tag><tt>binary</tt>, <tt>binary-arch</tt>,
<tt>binary-indep</tt>
</tag>
<p>
The <tt>binary</tt> target must be all that is
necessary for the user to build the binary package(s)
- produced from this source package. All of these
- targets are required to be non-interactive. It is
+ produced from this source package. It is
split into two parts: <prgn>binary-arch</prgn> builds
the binary packages which are specific to a particular
architecture, and <tt>binary-indep</tt> builds
<p>
The <tt>binary</tt> targets must be invoked as
root.<footnote>
- <p>
The <prgn>fakeroot</prgn> package often allows one
to build a package correctly even without being
root.
- </p>
</footnote>
</p>
</item>
and <tt>binary</tt> targets may have had, except
that it should leave alone any output files created in
the parent directory by a run of a <tt>binary</tt>
- target. This target must be non-interactive.
+ target.
</p>
<p>
<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>
</sect>
- <sect id="dpkgchangelog"><heading><file>debian/changelog</file>
- </heading>
+<!-- FIXME: section pkg-srcsubstvars is the same as substvars -->
+ <sect id="substvars">
+ <heading>Variable substitutions: <file>debian/substvars</file></heading>
<p>
- This file records the changes to the Debian-specific parts of the
- package<footnote>
- <p>
- Though there is nothing stopping an author who is also
- the Debian maintainer from using it for all their
- changes, it will have to be renamed if the Debian and
- upstream maintainers become different people. In such a
- case, however, it might be better to maintain the
- package as a non-native package.
- </p>
- </footnote>.
+ When <prgn>dpkg-gencontrol</prgn>,
+ <prgn>dpkg-genchanges</prgn> and <prgn>dpkg-source</prgn>
+ generate control files they perform variable substitutions
+ on their output just before writing it. Variable
+ substitutions have the form <tt>${<var>variable</var>}</tt>.
+ The optional file <file>debian/substvars</file> contains
+ variable substitutions to be used; variables can also be set
+ directly from <file>debian/rules</file> using the <tt>-V</tt>
+ option to the source packaging commands, and certain
+ predefined variables are also available.
</p>
<p>
- It has a special format which allows the package building
- tools to discover which version of the package is being
- built and find out other release-specific information.
+ The <file>debian/substvars</file> file is usually generated and
+ modified dynamically by <file>debian/rules</file> targets, in
+ which case it must be removed by the <tt>clean</tt> target.
</p>
<p>
- That format is a series of entries like this:
- <example compact="compact">
-<var>package</var> (<var>version</var>) <var>distribution(s)</var>; urgency=<var>urgency</var>
- <comment>
- <p>[optional blank line(s), stripped]</p>
- </comment>
- * <var>change details</var>
- <var>more change details</var>
- <comment>
- <p>[blank line(s), included in output of dpkg-parsechangelog]</p>
- </comment>
- * <var>even more change details</var>
- <comment>
- <p>[optional blank line(s), stripped]</p>
- </comment>
- -- <var>maintainer name</var> <<var>email
- address</var>><var>[two spaces]</var> <var>date</var>
- </example>
- </p>
+ See <manref name="dpkg-source" section="1"> for full
+ details about source variable substitutions, including the
+ format of <file>debian/substvars</file>.</p>
+ </sect>
+
+ <sect id="debianfiles">
+ <heading>Generated files list: <file>debian/files</file></heading>
<p>
- <var>package</var> and <var>version</var> are the source
- package name and version number.
+ This file is not a permanent part of the source tree; it
+ is used while building packages to record which files are
+ being generated. <prgn>dpkg-genchanges</prgn> uses it
+ when it generates a <file>.changes</file> file.
</p>
<p>
- <var>distribution(s)</var> lists the distributions where
- this version should be installed when it is uploaded - it
- is copied to the <tt>Distribution</tt> field in the
- <file>.changes</file> file. See <ref id="f-Distribution">.
+ 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>
+ <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.
+ </footnote>) should be removed by the
+ <tt>clean</tt> target. It may also be wise to
+ ensure a fresh start by emptying or removing it at the
+ start of the <tt>binary</tt> target.
</p>
<p>
- <var>urgency</var> is the value for the <tt>Urgency</tt>
- field in the <file>.changes</file> file for the upload. It is
- not possible to specify an urgency containing commas; commas
- are used to separate
- <tt><var>keyword</var>=<var>value</var></tt> settings in the
- <prgn>dpkg</prgn> changelog format (though there is
- currently only one useful <var>keyword</var>,
- <tt>urgency</tt>).<footnote>
- <p>
- Recognised urgency values are <tt>low</tt>,
- <tt>medium</tt>, <tt>high</tt> and <tt>emergency</tt>.
- They have an effect on how quickly a package will be
- considered for inclusion into the <tt>testing</tt>
- distribution, and give an indication of the importance
- of any fixes included in this upload.
- </p>
- </footnote>
+ When <prgn>dpkg-gencontrol</prgn> is run for a binary
+ package, it adds an entry to <file>debian/files</file> for the
+ <file>.deb</file> file that will be created when <tt>dpkg-deb
+ --build</tt> is run for that binary package. So for most
+ packages all that needs to be done with this file is to
+ delete it in the <tt>clean</tt> target.
</p>
<p>
- The change details may in fact be any series of lines
- starting with at least two spaces, but conventionally each
- change starts with an asterisk and a separating space and
- continuation lines are indented so as to bring them in
- line with the start of the text above. Blank lines may be
- used here to separate groups of changes, if desired.
+ If a package upload includes files besides the source
+ package and any binary packages whose control files were
+ made with <prgn>dpkg-gencontrol</prgn> then they should be
+ placed in the parent of the package's top-level directory
+ and <prgn>dpkg-distaddfile</prgn> should be called to add
+ the file to the list in <file>debian/files</file>.</p>
+ </sect>
+
+ </chapt>
+
+
+ <chapt id="controlfields">
+ <heading>Control files and their fields</heading>
+
+ <p>
+ The package management system manipulates data represented in
+ a common format, known as <em>control data</em>, stored in
+ <em>control files</em>.
+ Control files are used for source packages, binary packages and
+ the <file>.changes</file> files which control the installation
+ of uploaded files<footnote>
+ <prgn>dpkg</prgn>'s internal databases are in a similar
+ format.
+ </footnote>.
+ </p>
+
+ <sect id="controlsyntax">
+ <heading>Syntax of control files</heading>
+
+ <p>
+ A control file consists of one or more paragraphs of
+ fields<footnote>
+ The paragraphs are also sometimes referred to as stanzas.
+ </footnote>.
+ The paragraphs are separated by blank lines. Some control
+ files allow only one paragraph; others allow several, in
+ which case each paragraph usually refers to a different
+ package. (For example, in source packages, the first
+ paragraph refers to the source package, and later paragraphs
+ refer to binary packages generated from the source.)
</p>
<p>
- If this upload resolves bugs recorded in the Bug Tracking
- System (BTS), they may be automatically closed on the
- inclusion of this package into the Debian archive by
- including the string: <tt>closes: Bug#<var>nnnnn</var></tt>
- in the change details.<footnote>
- <p>
- To be precise, the string should match the following
- Perl regular expression:
- <example>
-/closes:\s*(?:bug)?\#?\s?\d+(?:,\s*(?:bug)?\#?\s?\d+)*/i
- </example>
- Then all of the bug numbers listed will be closed by the
- archive maintenance script (<prgn>katie</prgn>), or in
- the case of an NMU, marked as fixed.
- </p>
- </footnote>
+ Each paragraph consists of a series of data fields; each
+ field consists of the field name, followed by a colon and
+ then the data/value associated with that field. It ends at
+ the end of the line. Horizontal whitespace (spaces and
+ tabs) may occur immediately before or after the value and is
+ ignored there; it is conventional to put a single space
+ after the colon. For example, a field might be:
+ <example compact="compact">
+Package: libc6
+ </example>
+ the field name is <tt>Package</tt> and the field value
+ <tt>libc6</tt>.
</p>
<p>
- The maintainer name and email address used in the changelog
- should be the details of the person uploading <em>this</em>
- version. They are <em>not</em> necessarily those of the
- usual package maintainer. The information here will be
- copied to the <tt>Changed-By</tt> field in the
- <tt>.changes</tt> file, and then later used to send an
- acknowledgement when the upload has been installed.
+ Some fields' values may span several lines; in this case
+ each continuation line must start with a space or a tab.
+ Any trailing spaces or tabs at the end of individual
+ lines of a field value are ignored.
</p>
<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.
+ Except where otherwise stated, only a single line of data is
+ allowed and whitespace is not significant in a field body.
+ Whitespace must not appear inside names (of packages,
+ architectures, files or anything else) or version numbers,
+ or between the characters of multi-character version
+ relationships.
</p>
<p>
- The first "title" line with the package name should start
- at the left hand margin; the "trailer" line with the
- maintainer and date details should be preceded by exactly
- one space. The maintainer details and the date must be
- separated by exactly two spaces.
+ Field names are not case-sensitive, but it is usual to
+ capitalize the field names using mixed case as shown below.
</p>
- <sect1><heading>Defining alternative changelog formats</heading>
+ <p>
+ Blank lines, or lines consisting only of spaces and tabs,
+ are not allowed within field values or between fields - that
+ would mean a new paragraph.
+ </p>
- <p>
- It is possible to use a different format to the standard
- one, by providing a parser for the format you wish to
- use.
- </p>
- <p>
- A changelog parser must not interact with the user at
- all.
- </p>
- </sect1>
</sect>
-<!-- FIXME: section pkg-srcsubstvars is the same as srcsubstvars -->
-
- <sect id="srcsubstvars"><heading><file>debian/substvars</file>
- and variable substitutions </heading>
+ <sect id="sourcecontrolfiles">
+ <heading>Source package control files -- <file>debian/control</file></heading>
<p>
- When <prgn>dpkg-gencontrol</prgn>,
- <prgn>dpkg-genchanges</prgn> and <prgn>dpkg-source</prgn>
- generate control files they perform variable substitutions
- on their output just before writing it. Variable
- substitutions have the form <tt>${<var>variable</var>}</tt>.
- The optional file <file>debian/substvars</file> contains
- variable substitutions to be used; variables can also be set
- directly from <file>debian/rules</file> using the <tt>-V</tt>
- option to the source packaging commands, and certain
- predefined variables are also available.
+ The <file>debian/control</file> file contains the most vital
+ (and version-independent) information about the source package
+ and about the binary packages it creates.
</p>
<p>
- The <file>debian/substvars</file> file is usually generated and
- modified dynamically by <file>debian/rules</file> targets, in
- which case it must be removed by the <tt>clean</tt> target.
+ The first paragraph of the control file contains information about
+ the source package in general. The subsequent sets each describe a
+ binary package that the source tree builds.
</p>
<p>
- See <manref name="dpkg-source" section="1"> for full
- details about source variable substitutions, including the
- format of <file>debian/substvars</file>.</p>
- </sect>
+ The fields in the general paragraph (the first one, for the source
+ package) are:
- <sect id="debianfiles"><heading><file>debian/files</file>
- </heading>
+ <list compact="compact">
+ <item><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</item>
+ <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
+ <item><qref id="f-Section"><tt>Section</tt></qref> (recommended)</item>
+ <item><qref id="f-Priority"><tt>Priority</tt></qref> (recommended)</item>
+ <item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
+ <item><qref id="f-Standards-Version"><tt>Standards-Version</tt></qref> (recommended)</item>
+ </list>
+ </p>
<p>
- This file is not a permanent part of the source tree; it
- is used while building packages to record which files are
- being generated. <prgn>dpkg-genchanges</prgn> uses it
- when it generates a <file>.changes</file> file.
+ The fields in the binary package paragraphs are:
+
+ <list compact="compact">
+ <item><qref id="f-Package"><tt>Package</tt></qref> (mandatory)</item>
+ <item><qref id="f-Architecture"><tt>Architecture</tt></qref> (mandatory)</item>
+ <item><qref id="f-Section"><tt>Section</tt></qref> (recommended)</item>
+ <item><qref id="f-Priority"><tt>Priority</tt></qref> (recommended)</item>
+ <item><qref id="f-Essential"><tt>Essential</tt></qref></item>
+ <item><qref id="binarydeps"><tt>Depends</tt> et al</qref></item>
+ <item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
+ </list>
</p>
<p>
- It should not exist in a shipped source package, and so it
- (and any backup files or temporary files such as
- <file>files.new</file><footnote>
- <p>
- <file>files.new</file> is used as a temporary file by
- <prgn>dpkg-gencontrol</prgn> and
- <prgn>dpkg-distaddfile</prgn> - they write a new
- version of <tt>files</tt> here before renaming it,
- to avoid leaving a corrupted copy if an error
- occurs
- </p>
- </footnote>) should be removed by the
- <tt>clean</tt> target. It may also be wise to
- ensure a fresh start by emptying or removing it at the
- start of the <tt>binary</tt> target.
+ The syntax and semantics of the fields are described below.
</p>
+<!-- stuff -->
+
<p>
- When <prgn>dpkg-gencontrol</prgn> is run for a binary
- package, it adds an entry to <file>debian/files</file> for the
- <file>.deb</file> file that will be created when <tt>dpkg-deb
- --build</tt> is run for that binary package. So for most
- packages all that needs to be done with this file is to
- delete it in the <tt>clean</tt> target.
+ These fields are used by <prgn>dpkg-gencontrol</prgn> to
+ generate control files for binary packages (see below), by
+ <prgn>dpkg-genchanges</prgn> to generate the
+ <tt>.changes</tt> file to accompany the upload, and by
+ <prgn>dpkg-source</prgn> when it creates the <file>.dsc</file>
+ source control file as part of a source archive.
</p>
<p>
- If a package upload includes files besides the source
- package and any binary packages whose control files were
- made with <prgn>dpkg-gencontrol</prgn> then they should be
- placed in the parent of the package's top-level directory
- and <prgn>dpkg-distaddfile</prgn> should be called to add
- the file to the list in <file>debian/files</file>.</p>
+ The fields here may contain variable references - their
+ values will be substituted by <prgn>dpkg-gencontrol</prgn>,
+ <prgn>dpkg-genchanges</prgn> or <prgn>dpkg-source</prgn>
+ when they generate output control files.
+ See <ref id="substvars"> for details.
+ </p>
+
</sect>
- <sect id="restrictions"><heading>Restrictions on objects in source packages
- </heading>
+ <sect id="binarycontrolfiles">
+ <heading>Binary package control files -- <file>DEBIAN/control</file></heading>
<p>
- The source package may not contain any hard links<footnote>
- <p>
- This is not currently detected when building source
- packages, but only when extracting
- them.
- </p>
- <p>
- Hard links may be permitted at some point in the
- future, but would require a fair amount of
- work.
- </p>
- </footnote>, device special files, sockets or setuid or
- setgid files.<footnote>
- <p>
- Setgid directories are allowed.
- </p>
- </footnote>
+ The <file>DEBIAN/control</file> file contains the most vital
+ (and version-dependent) information about a binary package.
+ </p>
+
+ <p>
+ The fields in this file are:
+
+ <list compact="compact">
+ <item><qref id="f-Package"><tt>Package</tt></qref> (mandatory)</item>
+ <item><qref id="f-Source"><tt>Source</tt></qref></item>
+ <item><qref id="f-Version"><tt>Version</tt></qref> (mandatory)</item>
+ <item><qref id="f-Section"><tt>Section</tt></qref> (recommended)</item>
+ <item><qref id="f-Priority"><tt>Priority</tt></qref> (recommended)</item>
+ <item><qref id="f-Architecture"><tt>Architecture</tt></qref> (mandatory)</item>
+ <item><qref id="f-Essential"><tt>Essential</tt></qref></item>
+ <item><qref id="binarydeps"><tt>Depends</tt> et al</qref></item>
+ <item><qref id="f-Installed-Size"><tt>Installed-Size</tt></qref></item>
+ <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
+ <item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
+ </list>
</p>
</sect>
- <sect id="descriptions"><heading>Descriptions of packages - the
- <tt>Description</tt> field</heading>
+ <sect id="debiansourcecontrolfiles">
+ <heading>Debian source control files -- <tt>.dsc</tt></heading>
<p>
- The "Description" control file field consists of two parts,
- the synopsis or the short description, and the long description.
- The field's format is as follows:
+ This file contains a series of fields, identified and
+ separated just like the fields in the control file of
+ a binary package. The fields are listed below; their
+ syntax is described above, in <ref id="pkg-controlfields">.
+
+ <list compact="compact">
+ <item><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</item>
+ <item><qref id="f-Version"><tt>Version</tt></qref> (mandatory)</item>
+ <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
+ <item><qref id="f-Binary"><tt>Binary</tt></qref></item>
+ <item><qref id="f-Architecture"><tt>Architecture</tt></qref></item>
+ <item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
+ <item><qref id="f-Standards-Version"><tt>Standards-Version</tt></qref> (recommended)</item>
+ <item><qref id="f-Files"><tt>Files</tt></qref> (mandatory)</item>
+ </list>
</p>
- <p><example>
- Description: <single line synopsis>
- <extended description over several lines>
-</example></p>
+ <p>
+ The source package control file is generated by
+ <prgn>dpkg-source</prgn> when it builds the source
+ archive, from other files in the source package,
+ described above. When unpacking, it is checked against
+ the files and directories in the other parts of the
+ source package.
+ </p>
+
+ </sect>
+
+ <sect id="debianchangesfiles">
+ <heading>Debian changes files -- <file>.changes</file></heading>
<p>
- The description is intended to describe the program to a user
- who has never met it before so that they know whether they
- want to install it. It should also give information about the
- significant dependencies and conflicts between this package
- and others, so that the user knows why these dependencies and
- conflicts have been declared.
+ The .changes files are used by the Debian archive maintenance
+ software to process updates to packages. They contain one
+ paragraph which contains information from the
+ <tt>debian/control</tt> file and other data about the
+ source package gathered via <tt>debian/changelog</tt>
+ and <tt>debian/rules</tt>.
</p>
<p>
- Put important information first, both in the synopsis and
- extended description. Sometimes only the first part of the
- synopsis or of the description will be displayed. You can
- assume that there will usually be a way to see the whole
- extended description.
+ The fields in this file are:
+
+ <list compact="compact">
+ <item><qref id="f-Format"><tt>Format</tt></qref> (mandatory)</item>
+ <item><qref id="f-Date"><tt>Date</tt></qref> (mandatory)</item>
+ <item><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</item>
+ <item><qref id="f-Binary"><tt>Binary</tt></qref> (mandatory)</item>
+ <item><qref id="f-Architecture"><tt>Architecture</tt></qref> (mandatory)</item>
+ <item><qref id="f-Version"><tt>Version</tt></qref> (mandatory)</item>
+ <item><qref id="f-Distribution"><tt>Distribution</tt></qref> (mandatory)</item>
+ <item><qref id="f-Urgency"><tt>Urgency</tt></qref> (recommended)</item>
+ <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
+ <item><qref id="f-Changed-By"><tt>Changed-By</tt></qref></item>
+ <item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
+ <item><qref id="f-Closes"><tt>Closes</tt></qref></item>
+ <item><qref id="f-Changes"><tt>Changes</tt></qref> (mandatory)</item>
+ <item><qref id="f-Files"><tt>Files</tt></qref> (mandatory)</item>
+ </list>
</p>
+ </sect>
- <sect1 id="synopsis"><heading>The single line synopsis</heading>
+ <sect id="controlfieldslist">
+ <heading>List of fields</heading>
+
+ <sect1 id="f-Source">
+ <heading><tt>Source</tt></heading>
<p>
- The single line synopsis should be kept brief - certainly
- under 80 characters.
+ This field identifies the source package name.
</p>
<p>
- Do not include the package name in the synopsis line. The
- display software knows how to display this already, and you
- do not need to state it. Remember that in many situations
- the user may only see the synopsis line - make it as
- informative as you can.
+ In a main source control information, a <file>.changes</file>
+ or a <file>.dsc</file> file this may contain only the name
+ of the source package.
</p>
+ <p>
+ In the control file of a binary package it may be followed
+ by a version number in parentheses<footnote>
+ It is customary to leave a space after the package name
+ if a version number is specified.
+ </footnote>.
+ This version number may be omitted (and is, by
+ <prgn>dpkg-gencontrol</prgn>) if it has the same value as
+ the <tt>Version</tt> field of the binary package in
+ question. The field itself may be omitted from a binary
+ package control file when the source package has the same
+ name and version as the binary package.
+ </p>
</sect1>
- <sect1 id="extendeddesc"><heading>The extended description</heading>
+ <sect1 id="f-Maintainer">
+ <heading><tt>Maintainer</tt></heading>
<p>
- Do not try to continue the single line synopsis into the
- extended description. This will not work correctly when
- the full description is displayed, and makes no sense
- where only the summary (the single line synopsis) is
- available.
+ The package maintainer's name and email address. The name
+ should come first, then the email address inside angle
+ brackets <tt><></tt> (in RFC822 format).
</p>
<p>
- The extended description should describe what the package
- does and how it relates to the rest of the system (in terms
- of, for example, which subsystem it is which part of).
+ If the maintainer's name contains a full stop then the
+ whole field will not work directly as an email address due
+ to a misfeature in the syntax specified in RFC822; a
+ program using this field as an address must check for this
+ and correct the problem if necessary (for example by
+ putting the name in round brackets and moving it to the
+ end, and bringing the email address forward).
</p>
+ </sect1>
+
+ <sect1 id="f-Changed-By">
+ <heading><tt>Changed-By</tt></heading>
<p>
- The description field needs to make sense to anyone, even
- people who have no idea about any of the things the
- package deals with.<footnote>
- The blurb that comes with a program in its
- announcements and/or <prgn>README</prgn> files is
- rarely suitable for use in a description. It is
- usually aimed at people who are already in the
- community where the package is used.
- </footnote>
+ The name and email address of the person who changed the
+ said package. Usually the name of the maintainer.
+ All the rules for the Maintainer field apply here, too.
</p>
+ </sect1>
+
+ <sect1 id="f-Section">
+ <heading><tt>Section</tt></heading>
<p>
- The lines in the extended description can have these formats:
+ This field specifies an application area into which the package
+ has been classified. See <ref id="subsections">.
</p>
- <p><list>
+ <p>
+ When it appears in the <file>debian/control</file> file,
+ it gives the value for the subfield of the same name in
+ the <tt>Files</tt> field of the <file>.changes</file> file.
+ It also gives the default for the same field in the binary
+ packages.
+ </p>
- <item>
- Those starting with a single space are part of a paragraph.
- Successive lines of this form will be word-wrapped when
- displayed. The leading space will usually be stripped off.
- </item>
+ <p>
+ By default, <prgn>dpkg-gencontrol</prgn> does not include this
+ field in the control file of a binary package - use the
+ <tt>-is</tt> (or <tt>-isp</tt>) options to achieve this effect.
+ </p>
+ </sect1>
+
+ <sect1 id="f-Priority">
+ <heading><tt>Priority</tt></heading>
+
+ <p>
+ This field represents how important that it is that the user
+ have the package installed. See <ref id="priorities">.
+ </p>
+
+ <p>
+ When it appears in the <file>debian/control</file> file,
+ it gives the value for the subfield of the same name in
+ the <tt>Files</tt> field of the <file>.changes</file> file.
+ It also gives the default for the same field in the binary
+ packages.
+ </p>
+
+ <p>
+ By default, <prgn>dpkg-gencontrol</prgn> does not include this
+ field in the control file of a binary package - use the
+ <tt>-ip</tt> (or <tt>-isp</tt>) options to achieve this effect.
+ </p>
+ </sect1>
+
+ <sect1 id="f-Package">
+ <heading><tt>Package</tt></heading>
+
+ <p>
+ The name of the binary package.
+ </p>
+
+ <p>
+ Package names must consist only of lower case letters
+ (<tt>a-z</tt>), digits (<tt>0-9</tt>), plus (<tt>+</tt>)
+ and minus (<tt>-</tt>) signs, and periods (<tt>.</tt>).
+ They must be at least two characters long and must start
+ with an alphanumeric character.
+ </p>
+ </sect1>
+
+ <sect1 id="f-Architecture">
+ <heading><tt>Architecture</tt></heading>
+
+ <p>
+ This is the architecture string; it is a single word for
+ the Debian architecture. The special value <tt>all</tt>
+ indicates that the package is architecture-independent.
+ </p>
+
+ <p>
+ In the main <file>debian/control</file> file in the source
+ package, or in the source package control file
+ <file>.dsc</file>, a list of architectures (separated by
+ spaces) is also allowed, as is the special value
+ <tt>any</tt>. A list indicates that the source will build
+ an architecture-dependent package, and will only work
+ correctly on the listed architectures. <tt>any</tt>
+ indicates that though the source package isn't dependent
+ on any particular architecture and should compile fine on
+ any one, the binary package(s) produced are not
+ architecture-independent but will instead be specific to
+ whatever the current build architecture is.
+ </p>
+
+ <p>
+ In a <file>.changes</file> file the <tt>Architecture</tt>
+ field lists the architecture(s) of the package(s)
+ currently being uploaded. This will be a list; if the
+ source for the package is being uploaded too the special
+ entry <tt>source</tt> is also present.
+ </p>
+
+ <p>
+ See <ref id="debianrules"> for information how to get the
+ architecture for the build process.
+ </p>
+ </sect1>
+
+ <sect1 id="f-Essential">
+ <heading><tt>Essential</tt></heading>
+
+ <p>
+ This is a boolean field which may occur only in the
+ control file of a binary package or in a per-package fields
+ paragraph of a main source control data file.
+ </p>
+
+ <p>
+ If set to <tt>yes</tt> then the package management system
+ will refuse to remove the package (upgrading and replacing
+ it is still possible). The other possible value is <tt>no</tt>,
+ which is the same as not having the field at all.
+ </p>
+ </sect1>
+
+ <sect1>
+ <heading>Package interrelationship fields:
+ <tt>Depends</tt>, <tt>Pre-Depends</tt>,
+ <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Conflicts</tt>,
+ <tt>Provides</tt>, <tt>Replaces</tt>
+ </heading>
+
+ <p>
+ These fields describe the package's relationships with
+ other packages. Their syntax and semantics are described
+ in <ref id="relationships">.</p>
+ </sect1>
+
+ <sect1 id="f-Standards-Version">
+ <heading><tt>Standards-Version</tt></heading>
+
+ <p>
+ The most recent version of the standards (the policy
+ manual and associated texts) with which the package
+ complies.
+ </p>
+
+ <p>
+ The version number has four components: major and minor
+ version number and major and minor patch level. When the
+ standards change in a way that requires every package to
+ change the major number will be changed. Significant
+ changes that will require work in many packages will be
+ signaled by a change to the minor number. The major patch
+ level will be changed for any change to the meaning of the
+ standards, however small; the minor patch level will be
+ changed when only cosmetic, typographical or other edits
+ are made which neither change the meaning of the document
+ nor affect the contents of packages.
+ </p>
+
+ <p>
+ Thus only the first three components of the policy version
+ are significant in the <em>Standards-Version</em> control
+ field, and so either these three components or the all
+ four components may be specified.<footnote>
+ In the past, people specified the full version number
+ in the Standards-Version field, for example "2.3.0.0".
+ Since minor patch-level changes don't introduce new
+ policy, it was thought it would be better to relax
+ policy and only require the first 3 components to be
+ specified, in this example "2.3.0". All four
+ components may still be used if someone wishes to do so.
+ </footnote>
+ </p>
+
+ </sect1>
+
+ <sect1 id="f-Version">
+ <heading><tt>Version</tt></heading>
+
+ <p>
+ The version number of a package. The format is:
+ [<var>epoch</var><tt>:</tt>]<var>upstream_version</var>[<tt>-</tt><var>debian_revision</var>]
+ </p>
+
+ <p>
+ The three components here are:
+ <taglist>
+ <tag><var>epoch</var></tag>
+ <item>
+ <p>
+ This is a single (generally small) unsigned integer. It
+ may be omitted, in which case zero is assumed. If it is
+ omitted then the <var>upstream_version</var> may not
+ contain any colons.
+ </p>
+
+ <p>
+ It is provided to allow mistakes in the version numbers
+ of older versions of a package, and also a package's
+ previous version numbering schemes, to be left behind.
+ </p>
+ </item>
+
+ <tag><var>upstream_version</var></tag>
+ <item>
+ <p>
+ This is the main part of the version number. It is
+ usually the version number of the original ("upstream")
+ package from which the <file>.deb</file> file has been made,
+ if this is applicable. Usually this will be in the same
+ format as that specified by the upstream author(s);
+ however, it may need to be reformatted to fit into the
+ package management system's format and comparison
+ scheme.
+ </p>
+
+ <p>
+ The comparison behavior of the package management system
+ with respect to the <var>upstream_version</var> is
+ described below. The <var>upstream_version</var>
+ portion of the version number is mandatory.
+ </p>
+
+ <p>
+ The <var>upstream_version</var> may contain only
+ alphanumerics<footnote>
+ 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
+ start with a digit. If there is no
+ <var>debian_revision</var> then hyphens are not allowed;
+ if there is no <var>epoch</var> then colons are not
+ allowed.
+ </p>
+ </item>
+
+ <tag><var>debian_revision</var></tag>
+ <item>
+ <p>
+ This part of the version number specifies the version of
+ the Debian package based on the upstream version. It
+ may contain only alphanumerics and the characters
+ <tt>+</tt> and <tt>.</tt> (plus and full stop) and is
+ compared in the same way as the
+ <var>upstream_version</var> is.
+ </p>
+
+ <p>
+ It is optional; if it isn't present then the
+ <var>upstream_version</var> may not contain a hyphen.
+ This format represents the case where a piece of
+ software was written specifically to be turned into a
+ Debian package, and so there is only one "debianization"
+ of it and therefore no revision indication is required.
+ </p>
+
+ <p>
+ It is conventional to restart the
+ <var>debian_revision</var> at <tt>1</tt> each time the
+ <var>upstream_version</var> is increased.
+ </p>
+
+ <p>
+ The package management system will break the version
+ number apart at the last hyphen in the string (if there
+ is one) to determine the <var>upstream_version</var> and
+ <var>debian_revision</var>. The absence of a
+ <var>debian_revision</var> compares earlier than the
+ presence of one (but note that the
+ <var>debian_revision</var> is the least significant part
+ of the version number).
+ </p>
+ </item>
+ </taglist>
+ </p>
+
+ <p>
+ The <var>upstream_version</var> and <var>debian_revision</var>
+ parts are compared by the package management system using the
+ same algorithm:
+ </p>
+
+ <p>
+ The strings are compared from left to right.
+ </p>
+
+ <p>
+ First the initial part of each string consisting entirely of
+ non-digit characters is determined. These two parts (one of
+ which may be empty) are compared lexically. If a difference
+ is found it is returned. The lexical comparison is a
+ comparison of ASCII values modified so that all the letters
+ sort earlier than all the non-letters.
+ </p>
+
+ <p>
+ Then the initial part of the remainder of each string which
+ consists entirely of digit characters is determined. The
+ numerical values of these two parts are compared, and any
+ difference found is returned as the result of the comparison.
+ For these purposes an empty string (which can only occur at
+ the end of one or both version strings being compared) counts
+ as zero.
+ </p>
+
+ <p>
+ These two steps (comparing and removing initial non-digit
+ strings and initial digit strings) are repeated until a
+ difference is found or both strings are exhausted.
+ </p>
+
+ <p>
+ Note that the purpose of epochs is to allow us to leave behind
+ mistakes in version numbering, and to cope with situations
+ where the version numbering scheme changes. It is
+ <em>not</em> intended to cope with version numbers containing
+ strings of letters which the package management system cannot
+ interpret (such as <tt>ALPHA</tt> or <tt>pre-</tt>), or with
+ silly orderings (the author of this manual has heard of a
+ package whose versions went <tt>1.1</tt>, <tt>1.2</tt>,
+ <tt>1.3</tt>, <tt>1</tt>, <tt>2.1</tt>, <tt>2.2</tt>,
+ <tt>2</tt> and so forth).
+ </p>
+ </sect1>
+
+ <sect1 id="f-Description">
+ <heading><tt>Description</tt></heading>
+
+ <p>
+ In a source or binary control file, the <tt>Description</tt>
+ field contains a description of the binary package, consisting
+ of two parts, the synopsis or the short description, and the
+ long description. The field's format is as follows:
+ </p>
+
+ <p>
+<example>
+ Description: <single line synopsis>
+ <extended description over several lines>
+</example>
+ </p>
+
+ <p>
+ The lines in the extended description can have these formats:
+ </p>
+
+ <p><list>
+
+ <item>
+ Those starting with a single space are part of a paragraph.
+ Successive lines of this form will be word-wrapped when
+ displayed. The leading space will usually be stripped off.
+ </item>
<item>
Those starting with two or more spaces. These will be
Those containing a single space followed by a single full stop
character. These are rendered as blank lines. This is the
<em>only</em> way to get a blank line<footnote>
- Completely empty lines will not be rendered as blank lines.
+ Completely empty lines will not be rendered as blank lines.
Instead, they will cause the parser to think you're starting
a whole new record in the control file, and will therefore
likely abort with an error.
Do not use tab characters. Their effect is not predictable.
</p>
- </sect1>
+ <p>
+ See <ref id="descriptions"> for further information on this.
+ </p>
- </sect>
+ <p>
+ In a <file>.changes</file> file, the <tt>Description</tt> field
+ contains a summary of the descriptions for the packages being
+ uploaded.
+ </p>
- </chapt>
+ <p>
+ The part of the field before the first newline is empty;
+ thereafter each line has the name of a binary package and
+ the summary description line from that binary package.
+ Each line is indented by one space.
+ </p>
+ </sect1>
- <chapt id="maintainerscripts"><heading>Package maintainer scripts
- and installation procedure
- </heading>
+ <sect1 id="f-Distribution">
+ <heading><tt>Distribution</tt></heading>
- <sect><heading>Introduction to package maintainer scripts
- </heading>
+ <p>
+ In a <file>.changes</file> file or parsed changelog output
+ this contains the (space-separated) name(s) of the
+ distribution(s) where this version of the package should
+ be installed. Valid distributions are determined by the
+ archive maintainers.<footnote>
+ Current distribution names are:
+ <taglist compact="compact">
+ <tag><em>stable</em></tag>
+ <item>
+ This is the current "released" version of Debian
+ GNU/Linux. Once the distribution is
+ <em>stable</em> only security fixes and other
+ major bug fixes are allowed. When changes are
+ made to this distribution, the release number is
+ increased (for example: 2.2r1 becomes 2.2r2 then
+ 2.2r3, etc).
+ </item>
- <p>
- It is possible to supply scripts as part of a package which
- the package management system will run for you when your
- package is installed, upgraded or removed.
- </p>
+ <tag><em>unstable</em></tag>
+ <item>
+ This distribution value refers to the
+ <em>developmental</em> part of the Debian
+ distribution tree. New packages, new upstream
+ versions of packages and bug fixes go into the
+ <em>unstable</em> directory tree. Download from
+ this distribution at your own risk.
+ </item>
- <p>
- These scripts are the files <prgn>preinst</prgn>,
- <prgn>postinst</prgn>, <prgn>prerm</prgn> and <prgn>postrm</prgn> in the
- control area of the package. They must be proper executable
- files; if they are scripts (which is recommended), they must
- start with the usual <tt>#!</tt> convention. They should be
- readable and executable by anyone, and not world-writable.
- </p>
+ <tag><em>testing</em></tag>
+ <item>
+ This distribution value refers to the
+ <em>testing</em> part of the Debian distribution
+ tree. It receives its packages from the
+ unstable distribution after a short time lag to
+ ensure that there are no major issues with the
+ unstable packages. It is less prone to breakage
+ than unstable, but still risky. It is not
+ possible to upload packages directly to
+ <em>testing</em>.
+ </item>
- <p>
- The package management system looks at the exit status from
- these scripts. It is important that they exit with a
- non-zero status if there is an error, so that the package
- management system can stop its processing. For shell
- scripts this means that you <em>almost always</em> need to
- use <tt>set -e</tt> (this is usually true when writing shell
- scripts, in fact). It is also important, of course, that
- they don't exit with a non-zero status if everything went
- well.
- </p>
+ <tag><em>frozen</em></tag>
+ <item>
+ From time to time, the <em>testing</em>
+ distribution enters a state of "code-freeze" in
+ anticipation of release as a <em>stable</em>
+ version. During this period of testing only
+ fixes for existing or newly-discovered bugs will
+ be allowed. The exact details of this stage are
+ determined by the Release Manager.
+ </item>
- <p>
- When a package is upgraded a combination of the scripts from
- the old and new packages is called during the upgrade
- procedure. If your scripts are going to be at all
- complicated you need to be aware of this, and may need to
- check the arguments to your scripts.
- </p>
+ <tag><em>experimental</em></tag>
+ <item>
+ The packages with this distribution value are
+ deemed by their maintainers to be high
+ risk. Oftentimes they represent early beta or
+ developmental packages from various sources that
+ the maintainers want people to try, but are not
+ ready to be a part of the other parts of the
+ Debian distribution tree. Download at your own
+ risk.
+ </item>
+ </taglist>
+
+ <p>
+ You should list <em>all</em> distributions that the
+ package should be installed into.
+ </p>
+
+ <p>
+ More information is available in the Debian Developer's
+ Reference, section "The Debian archive".
+ </p>
+ </footnote>
+ </p>
+ </sect1>
+
+ <sect1 id="f-Date">
+ <heading><tt>Date</tt></heading>
+
+ <p>
+ This field includes the date the package was built or last edited.
+ </p>
+
+ <p>
+ The value of this field is usually extracted from the
+ <file>debian/changelog</file> file - see
+ <ref id="dpkgchangelog">).
+ </p>
+ </sect1>
+
+ <sect1 id="f-Format">
+ <heading><tt>Format</tt></heading>
+
+ <p>
+ This field specifies a format revision for the file.
+ The most current format described in the Policy Manual
+ is version <strong>1.5</strong>. The syntax of the
+ format value is the same as that of a package version
+ number except that no epoch or Debian revision is allowed
+ - see <ref id="f-Version">.
+ </p>
+ </sect1>
+
+ <sect1 id="f-Urgency">
+ <heading><tt>Urgency</tt></heading>
+
+ <p>
+ This is a description of how important it is to upgrade to
+ this version from previous ones. It consists of a single
+ keyword usually taking one of the values <tt>low</tt>,
+ <tt>medium</tt> or <tt>high</tt> (not case-sensitive)
+ followed by an optional commentary (separated by a space)
+ which is usually in parentheses. For example:
+
+ <example>
+ Urgency: low (HIGH for users of diversions)
+ </example>
+
+ </p>
+
+ <p>
+ The value of this field is usually extracted from the
+ <file>debian/changelog</file> file - see
+ <ref id="dpkgchangelog">.
+ </p>
+ </sect1>
+
+ <sect1 id="f-Changes">
+ <heading><tt>Changes</tt></heading>
+
+ <p>
+ This field contains the human-readable changes data, describing
+ the differences between the last version and the current one.
+ </p>
+
+ <p>
+ There should be nothing in this field before the first
+ newline; all the subsequent lines must be indented by at
+ least one space; blank lines must be represented by a line
+ consiting only of a space and a full stop.
+ </p>
+
+ <p>
+ The value of this field is usually extracted from the
+ <file>debian/changelog</file> file - see
+ <ref id="dpkgchangelog">).
+ </p>
+
+ <p>
+ Each version's change information should be preceded by a
+ "title" line giving at least the version, distribution(s)
+ and urgency, in a human-readable way.
+ </p>
+
+ <p>
+ If data from several versions is being returned the entry
+ for the most recent version should be returned first, and
+ entries should be separated by the representation of a
+ blank line (the "title" line may also be followed by the
+ representation of blank line).
+ </p>
+ </sect1>
+
+ <sect1 id="f-Binary">
+ <heading><tt>Binary</tt></heading>
+
+ <p>
+ This field is a list of binary packages.
+ </p>
+
+ <p>
+ When it appears in the <file>.dsc</file> file it is the list
+ of binary packages which a source package can produce. It
+ does not necessarily produce all of these binary packages
+ for every architecture. The source control file doesn't
+ contain details of which architectures are appropriate for
+ which of the binary packages.
+ </p>
+
+ <p>
+ When it appears in a <file>.changes</file> file it lists the
+ names of the binary packages actually being uploaded.
+ </p>
+
+ <p>
+ The syntax is a list of binary packages separated by
+ commas<footnote>
+ A space after each comma is conventional.
+ </footnote>. Currently the packages must be separated using
+ only spaces in the <file>.changes</file> file.
+ </p>
+ </sect1>
+
+ <sect1 id="f-Installed-Size">
+ <heading><tt>Installed-Size</tt></heading>
+
+ <p>
+ This field appears in the control files of binary
+ packages, and in the <file>Packages</file> files. It gives
+ the total amount of disk space required to install the
+ named package.
+ </p>
+
+ <p>
+ The disk space is represented in kilobytes as a simple
+ decimal number.
+ </p>
+ </sect1>
+
+ <sect1 id="f-Files">
+ <heading><tt>Files</tt></heading>
+
+ <p>
+ This field contains a list of files with information about
+ each one. The exact information and syntax varies with
+ the context. In all cases the part of the field
+ contents on the same line as the field name is empty. The
+ remainder of the field is one line per file, each line
+ being indented by one space and containing a number of
+ sub-fields separated by spaces.
+ </p>
+
+ <p>
+ In the <file>.dsc</file> file, each line contains the MD5
+ checksum, size and filename of the tar file and (if applicable)
+ diff file which make up the remainder of the source
+ package<footnote>
+ That is, the parts which are not the <tt>.dsc</tt>.
+ </footnote>.
+ The exact forms of the filenames are described
+ in <ref id="pkg-sourcearchives">.
+ </p>
+
+ <p>
+ In the <file>.changes</file> file this contains one line per
+ file being uploaded. Each line contains the MD5 checksum,
+ size, section and priority and the filename.
+ The <qref id="f-Section">section</qref>
+ and <qref id="f-Priority">priority</qref>
+ are the values of the corresponding fields in
+ the main source control file. If no section or priority is
+ specified then <tt>-</tt> should be used, though section
+ and priority values must be specified for new packages to
+ be installed properly.
+ </p>
+
+ <p>
+ The special value <tt>byhand</tt> for the section in a
+ <tt>.changes</tt> file indicates that the file in question
+ is not an ordinary package file and must by installed by
+ hand by the distribution maintainers. If the section is
+ <tt>byhand</tt> the priority should be <tt>-</tt>.
+ </p>
+
+ <p>
+ If a new Debian revision of a package is being shipped and
+ no new original source archive is being distributed the
+ <tt>.dsc</tt> must still contain the <tt>Files</tt> field
+ entry for the original source archive
+ <file><var>package</var>-<var>upstream-version</var>.orig.tar.gz</file>,
+ but the <file>.changes</file> file should leave it out. In
+ this case the original source archive on the distribution
+ site must match exactly, byte-for-byte, the original
+ source archive which was used to generate the
+ <file>.dsc</file> file and diff which are being uploaded.</p>
+ </sect1>
+
+ <sect1 id="f-Closes">
+ <heading><tt>Closes</tt></heading>
+
+ <p>
+ A space-separated list of bug report numbers that the upload
+ governed by the .changes file closes.
+ </p>
+ </sect1>
+
+ </sect>
+
+ <sect>
+ <heading>User-defined fields</heading>
+
+ <p>
+ Additional user-defined fields may be added to the
+ source package control file. Such fields will be
+ ignored, and not copied to (for example) binary or
+ source package control files or upload control files.
+ </p>
+
+ <p>
+ If you wish to add additional unsupported fields to
+ these output files you should use the mechanism
+ described here.
+ </p>
+
+ <p>
+ Fields in the main source control information file with
+ names starting <tt>X</tt>, followed by one or more of
+ the letters <tt>BCS</tt> and a hyphen <tt>-</tt>, will
+ be copied to the output files. Only the part of the
+ field name after the hyphen will be used in the output
+ file. Where the letter <tt>B</tt> is used the field
+ will appear in binary package control files, where the
+ letter <tt>S</tt> is used in source package control
+ files and where <tt>C</tt> is used in upload control
+ (<tt>.changes</tt>) files.
+ </p>
+
+ <p>
+ For example, if the main source information control file
+ contains the field
+ <example>
+ XBS-Comment: I stand between the candle and the star.
+ </example>
+ then the binary and source package control files will contain the
+ field
+ <example>
+ Comment: I stand between the candle and the star.
+ </example>
+ </p>
+
+ </sect>
+
+ </chapt>
+
+
+ <chapt id="maintainerscripts">
+ <heading>Package maintainer scripts and installation procedure</heading>
+
+ <sect>
+ <heading>Introduction to package maintainer scripts</heading>
+
+ <p>
+ It is possible to supply scripts as part of a package which
+ the package management system will run for you when your
+ package is installed, upgraded or removed.
+ </p>
+
+ <p>
+ These scripts are the files <prgn>preinst</prgn>,
+ <prgn>postinst</prgn>, <prgn>prerm</prgn> and <prgn>postrm</prgn> in the
+ control area of the package. They must be proper executable
+ files; if they are scripts (which is recommended), they must
+ start with the usual <tt>#!</tt> convention. They should be
+ readable and executable by anyone, and not world-writable.
+ </p>
+
+ <p>
+ The package management system looks at the exit status from
+ these scripts. It is important that they exit with a
+ non-zero status if there is an error, so that the package
+ management system can stop its processing. For shell
+ scripts this means that you <em>almost always</em> need to
+ use <tt>set -e</tt> (this is usually true when writing shell
+ scripts, in fact). It is also important, of course, that
+ they don't exit with a non-zero status if everything went
+ well.
+ </p>
+
+ <p>
+ When a package is upgraded a combination of the scripts from
+ the old and new packages is called during the upgrade
+ procedure. If your scripts are going to be at all
+ complicated you need to be aware of this, and may need to
+ check the arguments to your scripts.
+ </p>
<p>
Broadly speaking the <prgn>preinst</prgn> is called before
considerations really apply to all shell scripts.</p>
</sect>
- <sect>
+ <sect id="idempotency">
<heading>Maintainer scripts Idempotency</heading>
<p>
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>
- <sect>
+ <sect id="controllingterminal">
<heading>Controlling terminal for maintainer scripts</heading>
<p>
<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
</p>
<p>
- It is an error for a package to contains files which
+ It is an error for a package to contain files which
are on the system in another package, unless
<tt>Replaces</tt> is used (see <ref id="replaces">).
<!--
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>
If there is no most recently configured version
- <prgn>dpkg</prgn> will pass a null argument; older versions
- of dpkg may pass <tt><unknown></tt> (including the
- angle brackets) in this case. Even older ones do not pass a
- second argument at all, under any circumstances.
+ <prgn>dpkg</prgn> will pass a null argument.
+ <footnote>
+ <p>
+ Historical note: Truly ancient (pre-1997) versions of
+ <prgn>dpkg</prgn> passed <tt><unknown></tt>
+ (including the angle brackets) in this case. Even older
+ ones did not pass a second argument at all, under any
+ circumstance. Note that upgrades using such an old dpkg
+ version are unlikely to work for other reasons, even if
+ this old argument behavior is handled by your postinst script.
+ </p>
+ </footnote>
</p>
</sect>
<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.
+
+ If there are problems during this process, we call
+ <example compact="compact">postinst
+ abort-remove</example>. No other attempt is made to unwind
+ after errors during removal.
</p>
</sect>
</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. This is done in parentheses after each individual
package name; the parentheses should contain a relation from
the list below followed by a version number, in the format
- described in <ref id="versions">.
+ described in <ref id="f-Version">.
</p>
<p>
</p>
</sect>
- <sect>
+ <sect id="binarydeps">
<heading>Binary Dependencies - <tt>Depends</tt>,
<tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
<tt>Pre-Depends</tt>
they may not be installed at the same time as certain other
packages, and/or that they depend on the presence of others.
</p>
-
+
<p>
This is done using the <tt>Depends</tt>, <tt>Pre-Depends</tt>,
<tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt> and
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>
package's <prgn>postrm</prgn> script will be run with a
special argument to allow the package to do any final
cleanup required. See <ref id="mscriptsinstact">.
- </p>
-
- <p>
- If an installed package, <tt>foo</tt> say, declares that
- it replaces another, <tt>bar</tt>, and an attempt is made
- to install <tt>bar</tt>, <prgn>dpkg</prgn> will discard
- files in the <tt>bar</tt> package which would overwrite
- those already present in <tt>foo</tt>. This is so that
- you can install an older version of a package without
- problems.
+ <footnote>
+ <p>
+ Replaces is a one way relationship -- you have to
+ install the replacing package after the replaced
+ package.
+ </p>
+ </footnote>
</p>
<p>
</sect1>
</sect>
- <sect><heading>Relationships between source and binary packages -
+ <sect id="sourcebinarydeps">
+ <heading>Relationships between source and binary packages -
<tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
<tt>Build-Conflicts</tt>, <tt>Build-Conflicts-Indep</tt>
</heading>
installed or absent at the time of building the package
can declare relationships to those binary packages.
</p>
-
+
<p>
This is done using the <tt>Build-Depends</tt>,
<tt>Build-Depends-Indep</tt>, <tt>Build-Conflicts</tt> and
<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>
+ invoked: <tt>build</tt>, <tt>build-indep</tt>,
+ <tt>binary</tt> and <tt>binary-indep</tt>.
</item>
</taglist>
-
</p>
</sect>
- </chapt>
-
-
- <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
<p>
The package should install the shared libraries under
- their normal names. For example, the <package>libgdbmg1</package>
- package should install <file>libgdbm.so.1.7.3</file> as
- <file>/usr/lib/libgdbm.so.1.7.3</file>. The files should not be
+ their normal names. For example, the <package>libgdbm3</package>
+ package should install <file>libgdbm.so.3.0.0</file> as
+ <file>/usr/lib/libgdbm.so.3.0.0</file>. The files should not be
renamed or re-linked by any <prgn>prerm</prgn> or
<prgn>postrm</prgn> scripts; <prgn>dpkg</prgn> will take care
of renaming things safely without affecting running programs,
<p>
The run-time library package should include the symbolic link that
<prgn>ldconfig</prgn> would create for the shared libraries.
- For example, the <package>libgdbmg1</package> package should include
- a symbolic link from <file>/usr/lib/libgdbm.so.1</file> to
- <file>libgdbm.so.1.7.3</file>. This is needed so that the dynamic
+ For example, the <package>libgdbm3</package> package should include
+ a symbolic link from <file>/usr/lib/libgdbm.so.3</file> to
+ <file>libgdbm.so.3.0.0</file>. This is needed so that the dynamic
linker (for example <prgn>ld.so</prgn> or
<prgn>ld-linux.so.*</prgn>) can find the library between the
time that <prgn>dpkg</prgn> installs it and the time that
<prgn>ldconfig</prgn> is run in the <prgn>postinst</prgn>
script.<footnote>
- <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>
<p>
The development package should contain a symlink for the associated
shared library without a version number. For example, the
- <package>libgdbmg1-dev</package> package should include a symlink
+ <package>libgdbm-dev</package> package should include a symlink
from <file>/usr/lib/libgdbm.so</file> to
- <file>libgdbm.so.1.7.3</file>. This symlink is needed by the linker
+ <file>libgdbm.so.3.0.0</file>. This symlink is needed by the linker
(<prgn>ld</prgn>) when compiling packages, as it will only look for
<file>libgdbm.so</file> when compiling dynamically.
</p>
<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>.
</chapt>
+
<chapt id="opersys"><heading>The Operating System</heading>
<sect>
<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
+ subsystem (such as <prgn>sysv-rct</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>
;;
restart)
echo -n "Restarting domain name service: named"
- start-stop-daemon --stop --quiet \
+ start-stop-daemon --stop --quiet --oknodo \
--pidfile /var/run/named.pid --exec /usr/sbin/named
start-stop-daemon --start --verbose --exec /usr/sbin/named \
-- $PARAMS
<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.
+ It is also available from the Debian web mirrors at
+ <tt><url name="/doc/packaging-manuals/menu-policy/"
+ id="http://www.debian.org/doc/packaging-manuals/menu-policy/"></tt>
+ 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
<p>
Registration of MIME type handlers allows programs like mail
- user agents and web browsers to to invoke these handlers to
- view, edit or display MIME types they don't support
- directly.
+ user agents and web browsers to invoke these handlers to
+ view, edit or display MIME types they don't support directly.
+ </p>
+
+ <p>
+ Packages which provide the ability to view/show/play,
+ compose, edit or print MIME types should register themselves
+ as such following the current MIME support policy.
+ </p>
+
+ <p>
+ The MIME support policy can be found in the <tt>mime-policy</tt>
+ files in the <tt>debian-policy</tt> package.
+ It is also available from the Debian web mirrors at
+ <tt><url name="/doc/packaging-manuals/mime-policy/"
+ id="http://www.debian.org/doc/packaging-manuals/mime-policy/"></tt>
+ 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:
<p>
Furthermore, as <file>/etc/profile</file> is a configuration
- file of the <prgn>base-files</prgn> package, other packages must not
- put any environment variables or other commands into that
- file.</p>
+ file of the <prgn>base-files</prgn> package, other packages must
+ not put any environment variables or other commands into that
+ file.
+ </p>
</sect>
+
</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.
+ should be compiled with a minimum of optimization.
For C programs, it is best to add <tt>-O0</tt>
to <tt>CFLAGS</tt> (although this is usually the
default). Some programs might fail to build or run at
this level of optimization; it may be necessary to
use <tt>-O1</tt>, for example.
- </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
the library compatible with LinuxThreads.
</p>
+ <p>
+ Although not enforced by the build tools, shared libraries
+ must be linked against all libraries that they use symbols from
+ in the same way that binaries are. This ensures the correct
+ functioning of the <qref id="sharedlibs-shlibdeps">shlibs</qref>
+ system and guarantees that all libraries can be safely opened
+ with <tt>dlopen()</tt>. Packagers may wish to use the gcc
+ option <tt>-Wl,-z,defs</tt> when building a shared library.
+ Since this option enforces symbol resolution at build time,
+ a missing library reference will be caught early as a fatal
+ build error.
+ </p>
+
<p>
All installed shared libraries should be stripped with
<example compact="compact">
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
<prgn>csh</prgn> and <prgn>tcsh</prgn> should be avoided as
scripting languages. See <em>Csh Programming Considered
Harmful</em>, one of the <tt>comp.unix.*</tt> FAQs, which
- can be found at <url
- id="http://language.perl.com/versus/csh.whynot">.<footnote>
- <p>
- It can also be found on
- <url id="http://www.cpan.org/doc/FMTEYEWTK/versus/csh.whynot">
- or on the ftp site <ftpsite>ftp.cpan.org</ftpsite> as
- <ftppath>/pub/perl/CPAN/doc/FMTEYEWTK/versus/csh.whynot</ftppath>.
- </p>
- </footnote>
+ can be found at <url id="http://language.perl.com/versus/csh.whynot">.
If an upstream package comes with <prgn>csh</prgn> scripts
then you must make sure that they start with
<tt>#!/bin/csh</tt> and make your package depend on the
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
</sect>
</chapt>
+
<chapt id="customized-programs">
<heading>Customized programs</heading>
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>.
+ currently recognised by <prgn>dpkg-architecture</prgn>.
The architecture, <tt><var>arch</var></tt>, is one of
the following: <tt>alpha</tt>, <tt>arm</tt>,
<tt>hppa</tt>, <tt>i386</tt>, <tt>ia64</tt>,
<tt>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>
- <p>
- You will need to depend on <tt>liblockfile1
- (>>1.01)</tt> to use these functions.
- </p>
+ You will need to depend on <tt>liblockfile1 (>>1.01)</tt>
+ to use these functions.
</footnote> packages is the recommended way to realize this.
</p>
<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
points.
</p>
</item>
+
<item>
- <p>
- If the window manager complies with <url
+ 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>
+ written by the <url id="http://www.freedesktop.org/"
+ name="Free Desktop Group">, add 40 points.
</item>
<item>
- <p>
If the window manager permits the X session to be
restarted using a <em>different</em> window manager
(without killing the X server) in its default
configuration, add 10 points; otherwise add none.
- </p>
</item>
</list>
</p>
<p>
Packages that provide fonts for the X Window
System<footnote>
- <p>
For the purposes of Debian Policy, a "font for the X
Window System" is one which is accessed via X protocol
requests. Fonts for the Linux console, for PostScript
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.
+ It is also available from the Debian web mirrors at
+ <tt><url name="/doc/packaging-manuals/perl-policy/"
+ id="http://www.debian.org/doc/packaging-manuals/perl-policy/"></tt>
+ 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>
</sect>
</chapt>
- <chapt id="docs"><heading>Documentation</heading>
+ <chapt id="docs">
+ <heading>Documentation</heading>
<sect>
<heading>Manual pages</heading>
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
+ 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">,
+ name="Man-Page-HOWTO">,
<manref name="man" section="7">, the examples
created by <prgn>debmake</prgn> or <prgn>dh_make</prgn>,
the helper programs <prgn>help2man</prgn>, or the
directory <file>/usr/share/doc/man-db/examples</file>.
- </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>
course!</p>
<p>
- Packages must not require the existance of any files in
+ Packages must not require the existence 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>
<sect id="changelogs">
<heading>Changelog files</heading>
- <p>
- The Debian changelog file (<file>debian/changelog</file>) should
- explain briefly what modifications were made in the Debian version
- of the package compared to the upstream one. Other changes and
- updates to the package should also be documented in this file.
- </p>
-
- <p>
- Mistakes in changelogs are usually best rectified by
- making a new changelog entry rather than "rewriting history"
- by editing old changelog entries.
- </p>
-
- <p>
- The format of the <file>debian/changelog</file> file is described
- 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
- <prgn>dpkg-genchanges</prgn> and <prgn>dpkg-gencontrol</prgn>.
- If there is general interest in the new format, you should
- contact the <package>dpkg</package> maintainer to have the
- parser script for it included in the <prgn>dpkg</prgn>
- package. (You will need to agree that the parser and its
- manpage may be distributed under the GNU GPL, just as the rest
- of <prgn>dpkg</prgn> is.)
- </p>
- </footnote>
- </p>
-
<p>
Packages that are not Debian-native must contain a
compressed copy of the <file>debian/changelog</file> file from
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>
<file>/usr/share/doc/<var>package</var>/changelog.gz</file>; if
there is a separate upstream maintainer, but no upstream
changelog, then the Debian changelog should still be called
- <file>changelog.Debian.gz</file>.</p>
+ <file>changelog.Debian.gz</file>.
+ </p>
+ <p>
+ For details about the format and contents of the Debian
+ changelog file, please see <ref id="dpkgchangelog">.
+ </p>
</sect>
</chapt>
not yet been incorporated into dpkg documentation. However,
they still have value, and hence they are presented here.
</p>
+
<p>
They have not yet been checked to ensure that they are
compatible with the contents of policy, and if there are any
done in due course.
</p>
+ <p>
+ Certain parts of the Packaging manual were integrated into the
+ Policy Manual proper, and removed from the appendices. Links
+ have been placed from the old locations to the new ones.
+ </p>
+
<p>
<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.
Policy and Programmer's Manual.</p>
</appendix>
- <appendix id="pkg-binarypkg"><heading>Binary packages (from old
- Packaging Manual)
- </heading>
+ <appendix id="pkg-binarypkg">
+ <heading>Binary packages (from old Packaging Manual)</heading>
<p>
The binary package has two main sections. The first part
</sect>
<sect id="pkg-controlarea">
- <heading>
- Package control information files
- </heading>
+ <heading>Package control information files</heading>
<p>
The control information portion of a binary package is a
<taglist>
<tag><tt>control</tt>
<item>
-
<p>
This is the key description file used by
<prgn>dpkg</prgn>. It specifies the package's name
and version, gives its description for the user,
states its relationships with other packages, and so
- forth. See <ref id="pkg-controlfile">.
- </p>
-
- <p>
- It is usually generated automatically from information
- in the source package by the
- <prgn>dpkg-gencontrol</prgn> program, and with
- assistance from <prgn>dpkg-shlibdeps</prgn>. See <ref
- id="pkg-sourcetools">.</p>
- </item>
-
- <tag><tt>postinst</tt>, <tt>preinst</tt>, <tt>postrm</tt>,
- <tt>prerm</tt>
- </tag>
- <item>
-
- <p>
- These are exectuable files (usually scripts) which
- <prgn>dpkg</prgn> runs during installation, upgrade
- and removal of packages. They allow the package to
- deal with matters which are particular to that package
- or require more complicated processing than that
- provided by <prgn>dpkg</prgn>. Details of when and
- how they are called are in <ref
- id="maintainerscripts">.
- </p>
-
- <p>
- It is very important to make these scripts
- idempotent.
- <footnote>
- <p>
- That means that if it runs successfully or fails
- and then you call it again it doesn't bomb out,
- but just ensures that everything is the way it
- ought to be.
- </p>
- </footnote> This is so that if an error occurs, the
- user interrupts <prgn>dpkg</prgn> or some other
- unforeseen circumstance happens you don't leave the
- user with a badly-broken package.
- </p>
-
- <p>
- The maintainer scripts are guaranteed to run with a
- controlling terminal and can interact with the user.
- If they need to prompt for passwords, do full-screen
- interaction or something similar you should do these
- things to and from <file>/dev/tty</file>, since
- <prgn>dpkg</prgn> will at some point redirect scripts'
- standard input and output so that it can log the
- installation process. Likewise, because these scripts
- may be executed with standard output redirected into a
- pipe for logging purposes, Perl scripts should set
- unbuffered output by setting <tt>$|=1</tt> so that the
- output is printed immediately rather than being
- buffered.
- </p>
-
- <p>
- Each script should return a zero exit status for
- success, or a nonzero one for failure.</p>
- </item>
-
- <tag><tt>conffiles</tt>
- </tag>
- <item>
-
- <p>
- This file contains a list of configuration files which
- are to be handled automatically by <prgn>dpkg</prgn>
- (see <ref id="pkg-conffiles">). Note that not necessarily
- every configuration file should be listed here.</p>
- </item>
-
- <tag><tt>shlibs</tt>
- </tag>
- <item>
-
- <p>
- This file contains a list of the shared libraries
- supplied by the package, with dependency details for
- each. This is used by <prgn>dpkg-shlibdeps</prgn>
- when it determines what dependencies are required in a
- package control file. The <tt>shlibs</tt> file format
- is described on <ref id="shlibs">.
- </p>
- </item>
- </taglist>
- </p>
-
- <sect id="pkg-controlfile">
- <heading>
- The main control information file: <tt>control</tt>
- </heading>
- <p>
- The most important control information file used by
- <prgn>dpkg</prgn> when it installs a package is
- <tt>control</tt>. It contains all the package"s "vital
- statistics".
- </p>
-
- <p>
- The binary package control files of packages built from
- Debian sources are made by a special tool,
- <prgn>dpkg-gencontrol</prgn>, which reads
- <file>debian/control</file> and <file>debian/changelog</file> to
- find the information it needs. See <ref id="pkg-sourcepkg"> for
- more details.
- </p>
-
- <p>
- The fields in binary package control files are:
- <list compact="compact">
- <item>
- <p><qref id="pkg-f-Package"><tt>Package</tt></qref> (mandatory)</p>
- </item>
- <item>
- <p><qref id="versions"><tt>Version</tt></qref> (mandatory)</p>
- </item>
- <item><p><qref id="pkg-f-Architecture"><tt>Architecture</tt></qref>
- (mandatory)
- <footnote>
- <p>
- This field should appear in all packages, though
- <prgn>dpkg</prgn> doesn't require it yet so that
- old packages can still be installed.
- </p>
- </footnote>
- </p>
- </item>
- <item>
- <p><qref id="relationships"><tt>Depends</tt>,
- <tt>Provides</tt> et al.</qref></p>
- </item>
- <item>
- <p><qref id="pkg-f-Essential"><tt>Essential</tt></qref></p>
- </item>
- <item>
- <p><qref id="pkg-f-Maintainer"><tt>Maintainer</tt></qref></p>
- </item>
- <item>
- <p><qref id="pkg-f-classification"><tt>Section</tt>,
- <tt>Priority</tt></qref></p>
- </item>
- <item>
- <p><qref id="pkg-f-Source"><tt>Source</tt></qref></p>
- </item>
- <item>
- <p><qref id="descriptions"><tt>Description</tt></qref></p>
- </item>
- <item>
- <p>
- <qref id="pkg-f-Installed-Size"><tt>Installed-Size</tt></qref>
- </p>
- </item>
- </list>
-
- <p>
- A description of the syntax of control files and the purpose
- of these fields is available in <ref id="pkg-controlfields">.
- </p>
- </sect>
-
- <sect>
- <heading>Time Stamps</heading>
- <p>
- Maintainers are encouraged to preserve the modification
- times of the upstream source files in a package, as far as
- is reasonably possible.
- <footnote>
- <p>
- The rationale is that there is some information conveyed
- by knowing the age of the file, for example, you could
- recognize that some documentation is very old by looking
- at the modification time, so it would be nice if the
- modification time of the upstream source would be
- preserved.
- </p>
- </footnote>
- </p>
- </sect>
- </appendix>
-
- <appendix id="pkg-sourcepkg">
- <heading>Source packages (from old Packaging Manual) </heading>
-
- <p>
- The Debian binary packages in the distribution are generated
- from Debian sources, which are in a special format to assist
- the easy and automatic building of binaries.
- </p>
-
- <p>
- There was a previous version of the Debian source format,
- which is now being phased out. Instructions for converting an
- old-style package are given in the Debian policy manual.
- </p>
-
- <sect id="pkg-sourcetools">
- <heading>Tools for processing source packages</heading>
-
- <p>
- Various tools are provided for manipulating source packages;
- they pack and unpack sources and help build of binary
- packages and help manage the distribution of new versions.
- </p>
-
- <p>
- They are introduced and typical uses described here; see
- <manref name="dpkg-source" section="1"> for full
- documentation about their arguments and operation.
- </p>
-
- <p>
- For examples of how to construct a Debian source package,
- and how to use those utilities that are used by Debian
- source packages, please see the <prgn>hello</prgn> example
- package.
- </p>
-
- <sect1>
- <heading>
- <prgn>dpkg-source</prgn> - packs and unpacks Debian source
- packages
- </heading>
-
- <p>
- This program is frequently used by hand, and is also
- called from package-independent automated building scripts
- such as <prgn>dpkg-buildpackage</prgn>.
- </p>
-
- <p>
- To unpack a package it is typically invoked with
- <example>
- dpkg-source -x <var>.../path/to/filename</var>.dsc
- </example>
- </p>
-
- <p>
- with the <file><var>filename</var>.tar.gz</file> and
- <file><var>filename</var>.diff.gz</file> (if applicable) in
- the same directory. It unpacks into
- <file><var>package</var>-<var>version</var></file>, and if
- applicable
- <file><var>package</var>-<var>version</var>.orig</file>, in
- the current directory.
- </p>
-
- <p>
- To create a packed source archive it is typically invoked:
- <example>
- dpkg-source -b <var>package</var>-<var>version</var>
- </example>
- </p>
-
- <p>
- This will create the <file>.dsc</file>, <file>.tar.gz</file> and
- <file>.diff.gz</file> (if appropriate) in the current
- directory. <prgn>dpkg-source</prgn> does not clean the
- source tree first - this must be done separately if it is
- required.
- </p>
-
- <p>
- See also <ref id="pkg-sourcearchives">.</p>
- </sect1>
-
-
- <sect1>
- <heading>
- <prgn>dpkg-buildpackage</prgn> - overall package-building
- control script
- </heading>
-
- <p>
- <prgn>dpkg-buildpackage</prgn> is a script which invokes
- <prgn>dpkg-source</prgn>, the <file>debian/rules</file>
- targets <tt>clean</tt>, <tt>build</tt> and
- <tt>binary</tt>, <prgn>dpkg-genchanges</prgn> and
- <prgn>pgp</prgn> to build a signed source and binary
- package upload.
- </p>
-
- <p>
- It is usually invoked by hand from the top level of the
- built or unbuilt source directory. It may be invoked with
- no arguments; useful arguments include:
- <taglist compact="compact">
- <tag><tt>-uc</tt>, <tt>-us</tt></tag>
- <item>
- <p>
- Do not PGP-sign the <tt>.changes</tt> file or the
- source package <tt>.dsc</tt> file, respectively.</p>
- </item>
- <tag><tt>-p<var>pgp-command</var></tt></tag>
- <item>
- <p>
- Invoke <var>pgp-command</var> instead of finding
- <tt>pgp</tt> on the <prgn>PATH</prgn>.
- <var>pgp-command</var> must behave just like
- <prgn>pgp</prgn>.</p>
- </item>
- <tag><tt>-r<var>root-command</var></tt></tag>
- <item>
- <p>
- When root privilege is required, invoke the command
- <var>root-command</var>. <var>root-command</var>
- should invoke its first argument as a command, from
- the <prgn>PATH</prgn> if necessary, and pass its
- second and subsequent arguments to the command it
- calls. If no <var>root-command</var> is supplied
- then <var>dpkg-buildpackage</var> will take no
- special action to gain root privilege, so that for
- most packages it will have to be invoked as root to
- start with.</p>
- </item>
- <tag><tt>-b</tt>, <tt>-B</tt></tag>
- <item>
- <p>
- Two types of binary-only build and upload - see
- <manref name="dpkg-source" section="1">.
- </p>
- </item>
- </taglist>
- </p>
- </sect1>
-
- <sect1>
- <heading>
- <prgn>dpkg-gencontrol</prgn> - generates binary package
- control files
- </heading>
-
- <p>
- This program is usually called from <file>debian/rules</file>
- (see <ref id="pkg-sourcetree">) in the top level of the source
- tree.
- </p>
-
- <p>
- This is usually done just before the files and directories in the
- temporary directory tree where the package is being built have their
- permissions and ownerships set and the package is constructed using
- <prgn>dpkg-deb/</prgn>
- <footnote>
- <p>
- This is so that the control file which is produced has
- the right permissions
- </p>
- </footnote>.
- </p>
-
- <p>
- <prgn>dpkg-gencontrol</prgn> must be called after all the
- files which are to go into the package have been placed in
- the temporary build directory, so that its calculation of
- the installed size of a package is correct.
- </p>
-
- <p>
- It is also necessary for <prgn>dpkg-gencontrol</prgn> to
- be run after <prgn>dpkg-shlibdeps</prgn> so that the
- variable substitutions created by
- <prgn>dpkg-shlibdeps</prgn> in <file>debian/substvars</file>
- are available.
- </p>
-
- <p>
- For a package which generates only one binary package, and
- which builds it in <file>debian/tmp</file> relative to the top
- of the source package, it is usually sufficient to call
- <prgn>dpkg-gencontrol</prgn>.
- </p>
-
- <p>
- Sources which build several binaries will typically need
- something like:
- <example>
- dpkg-gencontrol -Pdebian/tmp-<var>pkg</var> -p<var>package</var>
- </example> The <tt>-P</tt> tells
- <prgn>dpkg-gencontrol</prgn> that the package is being
- built in a non-default directory, and the <tt>-p</tt>
- tells it which package's control file should be generated.
- </p>
-
- <p>
- <prgn>dpkg-gencontrol</prgn> also adds information to the
- list of files in <file>debian/files</file>, for the benefit of
- (for example) a future invocation of
- <prgn>dpkg-genchanges</prgn>.</p>
- </sect1>
-
- <sect1>
- <heading>
- <prgn>dpkg-shlibdeps</prgn> - calculates shared library
- dependencies
- </heading>
-
- <p>
- This program is usually called from <file>debian/rules</file>
- just before <prgn>dpkg-gencontrol</prgn> (see <ref
- id="pkg-sourcetree">), in the top level of the source tree.
- </p>
-
- <p>
- Its arguments are executables.
- <footnote>
- <p>
- In a forthcoming dpkg version,
- <prgn>dpkg-shlibdeps</prgn> would be required to be
- called on shared libraries as well.
- </p>
- <p>
- They may be specified either in the locations in the
- source tree where they are created or in the locations
- in the temporary build tree where they are installed
- prior to binary package creation.
- </p>
- </footnote> for which shared library dependencies should
- be included in the binary package's control file.
- </p>
-
- <p>
- If some of the found shared libraries should only
- warrant a <tt>Recommends</tt> or <tt>Suggests</tt>, or if
- some warrant a <tt>Pre-Depends</tt>, this can be achieved
- by using the <tt>-d<var>dependency-field</var></tt> option
- before those executable(s). (Each <tt>-d</tt> option
- takes effect until the next <tt>-d</tt>.)
- </p>
-
- <p>
- <prgn>dpkg-shlibdeps</prgn> does not directly cause the
- output control file to be modified. Instead by default it
- adds to the <file>debian/substvars</file> file variable
- settings like <tt>shlibs:Depends</tt>. These variable
- settings must be referenced in dependency fields in the
- appropriate per-binary-package sections of the source
- control file.
- </p>
-
- <p>
- For example, the <prgn>procps</prgn> package generates two
- kinds of binaries, simple C binaries like <prgn>ps</prgn>
- which require a predependency and full-screen ncurses
- binaries like <prgn>top</prgn> which require only a
- recommendation. It can say in its <file>debian/rules</file>:
- <example>
- dpkg-shlibdeps -dPre-Depends ps -dRecommends top
- </example>
- and then in its main control file <file>debian/control</file>:
- <example>
- <var>...</var>
- Package: procps
- Pre-Depends: ${shlibs:Pre-Depends}
- Recommends: ${shlibs:Recommends}
- <var>...</var>
- </example>
- </p>
-
- <p>
- Sources which produce several binary packages with
- different shared library dependency requirements can use
- the <tt>-p<var>varnameprefix</var></tt> option to override
- the default <tt>shlibs:</tt> prefix (one invocation of
- <prgn>dpkg-shlibdeps</prgn> per setting of this option).
- They can thus produce several sets of dependency
- variables, each of the form
- <tt><var>varnameprefix</var>:<var>dependencyfield</var></tt>,
- which can be referred to in the appropriate parts of the
- binary package control files.
- </p>
- </sect1>
-
-
- <sect1>
- <heading>
- <prgn>dpkg-distaddfile</prgn> - adds a file to
- <file>debian/files</file>
- </heading>
-
- <p>
- Some packages' uploads need to include files other than
- the source and binary package files.
- </p>
-
- <p>
- <prgn>dpkg-distaddfile</prgn> adds a file to the
- <file>debian/files</file> file so that it will be included in
- the <file>.changes</file> file when
- <prgn>dpkg-genchanges</prgn> is run.
- </p>
-
- <p>
- It is usually invoked from the <tt>binary</tt> target of
- <file>debian/rules</file>:
- <example>
- dpkg-distaddfile <var>filename</var> <var>section</var> <var>priority</var>
- </example>
- The <var>filename</var> is relative to the directory where
- <prgn>dpkg-genchanges</prgn> will expect to find it - this
- is usually the directory above the top level of the source
- tree. The <file>debian/rules</file> target should put the
- file there just before or just after calling
- <prgn>dpkg-distaddfile</prgn>.
- </p>
-
- <p>
- The <var>section</var> and <var>priority</var> are passed
- unchanged into the resulting <file>.changes</file> file. See
- <ref id="pkg-f-classification">.
- </p>
- </sect1>
-
-
- <sect1><heading><prgn>dpkg-genchanges</prgn> - generates a <file>.changes</file> upload
- control file
- </heading>
-
- <p>
- This program is usually called by package-independent
- automatic building scripts such as
- <prgn>dpkg-buildpackage</prgn>, but it may also be called
- by hand.
- </p>
-
- <p>
- It is usually called in the top level of a built source
- tree, and when invoked with no arguments will print out a
- straightforward <file>.changes</file> file based on the
- information in the source package's changelog and control
- file and the binary and source packages which should have
- been built.
- </p>
- </sect1>
-
-
- <sect1><heading><prgn>dpkg-parsechangelog</prgn> - produces parsed representation of
- a changelog
- </heading>
-
- <p>
- This program is used internally by
- <prgn>dpkg-source</prgn> et al. It may also occasionally
- be useful in <file>debian/rules</file> and elsewhere. It
- parses a changelog, <file>debian/changelog</file> by default,
- and prints a control-file format representation of the
- information in it to standard output.
- </p>
- </sect1>
-
- <sect1 id="pkg-dpkgarch"><heading><prgn>dpkg-architecture</prgn> -
- information about the build and host system
- </heading>
-
- <p>
- This program can be used manually, but is also invoked by
- <tt>dpkg-buildpackage</tt> or <file>debian/rules</file> to set
- to set environment or make variables which specify the build and
- host architecture for the package building process.
- </p>
- </sect1>
- </sect>
-
- <sect id="pkg-sourcetree"><heading>The Debianised source tree
- </heading>
-
- <p>
- The source archive scheme described later is intended to
- allow a Debianised source tree with some associated control
- information to be reproduced and transported easily. The
- Debianised source tree is a version of the original program
- with certain files added for the benefit of the
- Debianisation process, and with any other changes required
- made to the rest of the source code and installation
- scripts.
- </p>
-
- <p>
- The extra files created for Debian are in the subdirectory
- <file>debian</file> of the top level of the Debianised source
- tree. They are described below.
- </p>
-
- <sect1 id="pkg-debianrules"><heading><file>debian/rules</file> - the main building
- script
- </heading>
-
- <p>
- This file is an executable makefile, and contains the
- package-specific recipies for compiling the package and
- building binary package(s) out of the source.
- </p>
-
- <p>
- It must start with the line <tt>#!/usr/bin/make -f</tt>,
- so that it can be invoked by saying its name rather than
- invoking <prgn>make</prgn> explicitly.
- </p>
-
- <p>
- Since an interactive <file>debian/rules</file> script makes it
- impossible to autocompile that package and also makes it
- hard for other people to reproduce the same binary
- package, all <strong>required targets</strong> have to be
- non-interactive. At a minimul, required targets are the
- ones called by <prgn>dpkg-buildpackage</prgn>, namely,
- <em>clean</em>, <em>binary</em>, <em>binary-arch</em>, and
- <em>build</em>. It also follows that any target that these
- targets depend on must also be non-interactive.
- </p>
-
- <p>
- The targets which are required to be present are:
- <taglist>
- <tag><tt>build</tt></tag>
- <item>
- <p>
- This should perform all non-interactive
- configuration and compilation of the package. If a
- package has an interactive pre-build configuration
- routine, the Debianised source package should be
- built after this has taken place, so that it can be
- built without rerunning the configuration.
- </p>
-
- <p>
- A package may also provide both of the targets
- <tt>build-arch</tt> and <tt>build-indep</tt>. The
- <tt>build-arch</tt> target, if provided, should
- perform all non-interactive configuration and
- compilation required for producing all
- architecture-dependant binary packages (those packages
- for which the body of the <tt>Architecture</tt> field
- in <tt>debian/control</tt> is not <tt>all</tt>).
- Similarly, the <tt>build-indep</tt> target, if
- provided, should perform all non-interactive
- configuration and compilation required for producing
- all architecture-independent binary packages (those
- packages for which the body of the
- <tt>Architecture</tt> field in <tt>debian/control</tt>
- is <tt>all</tt>). The <tt>build</tt> target should
- depend on those of the targets <tt>build-arch</tt> and
- <tt>build-indep</tt> that are provided in the rules
- file.
- </p>
-
- <p>
- If one or both of the targets <tt>build-arch</tt> and
- <tt>build-indep</tt> are not provided, then invoking
- <file>debian/rules</file> with one of the not-provided
- targets as arguments should produce a exit status code
- of 2. Usually this is provided automatically by make
- if the target is missing.
- </p>
-
- <p>
- For some packages, notably ones where the same
- source tree is compiled in different ways to produce
- two binary packages, the <tt>build</tt> target does
- not make much sense. For these packages it is good
- enough to provide two (or more) targets
- (<tt>build-a</tt> and <tt>build-b</tt> or whatever)
- for each of the ways of building the package, and a
- <tt>build</tt> target that does nothing. The
- <tt>binary</tt> target will have to build the
- package in each of the possible ways and make the
- binary package out of each.
- </p>
-
- <p>
- The targets <tt>build</tt>, <tt>build-arch</tt>
- and <tt>build-indep</tt> target must not do
- anything that might require root privilege.
- </p>
-
- <p>
- The <tt>build</tt> target may need to run
- <tt>clean</tt> first - see below.
- </p>
-
- <p>
- When a package has a configuration routine that takes
- a long time, or when the makefiles are poorly
- designed, or when <tt>build</tt> needs to run
- <tt>clean</tt> first, it is a good idea to <tt>touch
- build</tt> when the build process is complete. This
- will ensure that if <tt>debian/rules build</tt> is run
- again it will not rebuild the whole program.
- </p>
- </item>
-
- <tag><tt>binary</tt>, <tt>binary-arch</tt>,
- <tt>binary-indep</tt>
- </tag>
- <item>
- <p>
- The <tt>binary</tt> target should be all that is
- necessary for the user to build the binary
- package. All these targets are required to be
- non-interactive. It is split into two parts:
- <tt>binary-arch</tt> builds the packages' output
- files which are specific to a particular
- architecture, and <tt>binary-indep</tt> builds
- those which are not.
- </p>
-
- <p>
- <tt>binary</tt> should usually be a target with
- no commands which simply depends on
- <prgn>binary-arch</prgn> and
- <prgn>binary-indep</prgn>.
- </p>
-
- <p>
- Both <prgn>binary-*</prgn> targets should depend on
- the <tt>build</tt> target, above, so that the
- package is built if it has not been already. It
- should then create the relevant binary package(s),
- using <prgn>dpkg-gencontrol</prgn> to make their
- control files and <prgn>dpkg-deb</prgn> to build
- them and place them in the parent of the top level
- directory.
- </p>
-
- <p>
- If one of the <prgn>binary-*</prgn> targets has
- nothing to do (this will be always be the case if
- the source generates only a single binary package,
- whether architecture-dependent or not) it
- <em>must</em> still exist, but should always
- succeed.
- </p>
-
- <p>
- <ref id="pkg-binarypkg"> describes how to construct
- binary packages.
- </p>
-
- <p>
- The <tt>binary</tt> targets must be invoked as
- root.
- </p>
- </item>
-
- <tag><tt>clean</tt></tag>
- <item>
-
- <p>
- This should undo any effects that the
- <tt>build</tt> and <tt>binary</tt> targets
- may have had, except that it should leave alone any
- output files created in the parent directory by a
- run of <tt>binary</tt>. This target is required
- to be non-interactive.
- </p>
-
- <p>
- If a <tt>build</tt> file is touched at the end
- of the <tt>build</tt> target, as suggested
- above, it must be removed as the first thing that
- <tt>clean</tt> does, so that running
- <tt>build</tt> again after an interrupted
- <tt>clean</tt> doesn't think that everything is
- already done.
- </p>
-
- <p>
- The <tt>clean</tt> target must be invoked as
- root if <tt>binary</tt> has been invoked since
- the last <tt>clean</tt>, or if
- <tt>build</tt> has been invoked as root (since
- <tt>build</tt> may create directories, for
- example).
- </p>
- </item>
-
- <tag><tt>get-orig-source</tt> (optional)</tag>
- <item>
-
- <p>
- This target fetches the most recent version of the
- original source package from a canonical archive
- site (via FTP or WWW, for example), does any
- necessary rearrangement to turn it into the original
- source tarfile format described below, and leaves it
- in the current directory.
- </p>
-
- <p>
- This target may be invoked in any directory, and
- should take care to clean up any temporary files it
- may have left.
- </p>
-
- <p>
- This target is optional, but providing it if
- possible is a good idea.
- </p>
- </item>
- </taglist>
-
- <p>
- The <tt>build</tt>, <tt>binary</tt> and
- <tt>clean</tt> targets must be invoked with a current
- directory of the package's top-level directory.
- </p>
-
-
- <p>
- Additional targets may exist in <file>debian/rules</file>,
- either as published or undocumented interfaces or for the
- package's internal use.
- </p>
-
- <p>
- The architecture we build on and build for is determined by make
- variables via dpkg-architecture (see <ref id="pkg-dpkgarch">). You can
- get the Debian architecture and the GNU style architecture
- specification string for the build machine as well as the host
- machine. Here is a list of supported make variables:
- <list compact="compact">
- <item>
- <p><tt>DEB_*_ARCH</tt> (the Debian architecture)</p>
- </item>
- <item>
- <p><tt>DEB_*_GNU_TYPE</tt> (the GNU style architecture
- specification string)</p>
- </item>
- <item>
- <p><tt>DEB_*_GNU_CPU</tt> (the CPU part of DEB_*_GNU_TYPE)</p>
- </item>
- <item>
- <p><tt>DEB_*_GNU_SYSTEM</tt> (the System part of
- DEB_*_GNU_TYPE)</p>
- </list>
- </p>
-
- <p>
- where <tt>*</tt> is either <tt>BUILD</tt> for specification of
- the build machine or <tt>HOST</tt> for specification of the machine
- we build for.
- </p>
-
- <p>
- Backward compatibility can be provided in the rules file
- by setting the needed variables to suitable default
- values, please refer to the documentation of
- dpkg-architecture for details.
- </p>
-
- <p>
- It is important to understand that the <tt>DEB_*_ARCH</tt>
- string does only determine which Debian architecture we
- build on resp. for. It should not be used to get the CPU
- or System information, the GNU style variables should be
- used for that.
- </p>
- </sect1>
-
-
- <sect1><heading><file>debian/control</file>
- </heading>
-
- <p>
- This file contains version-independent details about the
- source package and about the binary packages it creates.
- </p>
-
- <p>
- It is a series of sets of control fields, each
- syntactically similar to a binary package control file.
- The sets are separated by one or more blank lines. The
- first set is information about the source package in
- general; each subsequent set describes one binary package
- that the source tree builds.
- </p>
-
- <p>
- The syntax and semantics of the fields are described below
- in <ref id="pkg-controlfields">.
- </p>
-
- <p>
- The general (binary-package-independent) fields are:
- <list compact="compact">
- <item>
- <p><qref id="pkg-f-Source"><tt>Source</tt></qref> (mandatory)</p>
- </item>
- <item>
- <p><qref id="pkg-f-Maintainer"><tt>Maintainer</tt></qref></p>
- </item>
- <item>
- <p>
- <qref id="pkg-f-classification"><tt>Section</tt> and
- <tt>Priority</tt></qref>
- (classification, mandatory)
- </p>
- </item>
- <item>
- <p>
- <qref id="relationships"><tt>Build-Depends</tt> et
- al.</qref> (source package interrelationships)
- </p>
- </item>
- <item>
- <p>
- <qref id="pkg-f-Standards-Version"><tt>Standards-Version</tt></qref>
- </p>
- </item>
- </list>
-
- <p>
- The per-binary-package fields are:
- <list compact="compact">
- <item>
- <p><qref id="pkg-f-Package"><tt>Package</tt></qref> (mandatory)</p>
- </item>
- <item>
- <p>
- <qref id="pkg-f-Architecture"><tt>Architecture</tt></qref>
- (mandatory)</p>
- </item>
- <item>
- <p><qref id="descriptions"><tt>Description</tt></qref></p>
- </item>
- <item>
- <p>
- <qref id="pkg-f-classification"><tt>Section</tt> and
- <tt>Priority</tt></qref> (classification)</p>
- </item>
- <item>
- <p><qref id="pkg-f-Essential"><tt>Essential</tt></qref></p>
- </item>
- <item>
- <p>
- <qref id="relationships"><tt>Depends</tt> et
- al.</qref> (binary package interrelationships)
- </p>
- </item>
- </list>
-
- <p>
- These fields are used by <prgn>dpkg-gencontrol</prgn> to
- generate control files for binary packages (see below), by
- <prgn>dpkg-genchanges</prgn> to generate the
- <tt>.changes</tt> file to accompany the upload, and by
- <prgn>dpkg-source</prgn> when it creates the <file>.dsc</file>
- source control file as part of a source archive.
- </p>
-
- <p>
- The fields here may contain variable references - their
- values will be substituted by
- <prgn>dpkg-gencontrol</prgn>, <prgn>dpkg-genchanges</prgn>
- or <prgn>dpkg-source</prgn> when they generate output
- control files. See <ref id="pkg-srcsubstvars"> for details.
- </p>
-
- <p> <sect2><heading>User-defined fields
- </heading>
-
- <p>
- Additional user-defined fields may be added to the
- source package control file. Such fields will be
- ignored, and not copied to (for example) binary or
- source package control files or upload control files.
- </p>
-
- <p>
- If you wish to add additional unsupported fields to
- these output files you should use the mechanism
- described here.
- </p>
-
- <p>
- Fields in the main source control information file with
- names starting <tt>X</tt>, followed by one or more of
- the letters <tt>BCS</tt> and a hyphen <tt>-</tt>, will
- be copied to the output files. Only the part of the
- field name after the hyphen will be used in the output
- file. Where the letter <tt>B</tt> is used the field
- will appear in binary package control files, where the
- letter <tt>S</tt> is used in source package control
- files and where <tt>C</tt> is used in upload control
- (<tt>.changes</tt>) files.
- </p>
-
- <p>
- For example, if the main source information control file
- contains the field
- <example>
- XBS-Comment: I stand between the candle and the star.
- </example>
- then the binary and source package control files will contain the
- field
- <example>
- Comment: I stand between the candle and the star.
- </example>
- </p>
- </sect2>
-
- </sect1>
-
- <sect1 id="pkg-dpkgchangelog"><heading><file>debian/changelog</file>
- </heading>
-
- <p>
- This file records the changes to the Debian-specific parts of the
- package
- <footnote>
- <p>
- Though there is nothing stopping an author who is also
- the Debian maintainer from using it for all their
- changes, it will have to be renamed if the Debian and
- upstream maintainers become different
- people.
- </p>
- </footnote>.
- </p>
-
- <p>
- It has a special format which allows the package building
- tools to discover which version of the package is being
- built and find out other release-specific information.
- </p>
-
- <p>
- That format is a series of entries like this:
- <example>
- <var>package</var> (<var>version</var>) <var>distribution(s)</var>; urgency=<var>urgency</var>
-
- * <var>change details</var>
- <var>more change details</var>
- * <var>even more change details</var>
-
- -- <var>maintainer name and email address</var> <var>date</var>
- </example>
- </p>
-
- <p>
- <var>package</var> and <var>version</var> are the source
- package name and version number.
- </p>
-
- <p>
- <var>distribution(s)</var> lists the distributions where
- this version should be installed when it is uploaded - it
- is copied to the <tt>Distribution</tt> field in the
- <tt>.changes</tt> file. See <ref id="pkg-f-Distribution">.
- </p>
-
- <p>
- <var>urgency</var> is the value for the <tt>Urgency</tt>
- field in the <file>.changes</file> file for the upload. See
- <ref id="pkg-f-Urgency">. It is not possible to specify an
- urgency containing commas; commas are used to separate
- <tt><var>keyword</var>=<var>value</var></tt> settings in
- the <prgn>dpkg</prgn> changelog format (though there is
- currently only one useful <var>keyword</var>,
- <tt>urgency</tt>).
- </p>
-
- <p>
- The change details may in fact be any series of lines
- starting with at least two spaces, but conventionally each
- change starts with an asterisk and a separating space and
- continuation lines are indented so as to bring them in
- line with the start of the text above. Blank lines may be
- used here to separate groups of changes, if desired.
- </p>
-
- <p>
- The maintainer name and email address should <em>not</em>
- necessarily be those of the usual package maintainer.
- They should be the details of the person doing
- <em>this</em> version. The information here will be
- copied to the <file>.changes</file> file, and then later used
- to send an acknowledgement when the upload has been
- installed.
- </p>
-
- <p>
- The <var>date</var> should be in RFC822 format
- <footnote>
- <p>
- This is generated by the <prgn>822-date</prgn>
- program.
- </p>
- </footnote>; it should include the timezone specified
- numerically, with the timezone name or abbreviation
- optionally present as a comment.
- </p>
-
- <p>
- The first "title" line with the package name should start
- at the left hand margin; the "trailer" line with the
- maintainer and date details should be preceded by exactly
- one space. The maintainer details and the date must be
- separated by exactly two spaces.
- </p>
-
- <p>
- An Emacs mode for editing this format is available: it is
- called <tt>debian-changelog-mode</tt>. You can have this
- mode selected automatically when you edit a Debian
- changelog by adding a local variables clause to the end of
- the changelog.
- </p>
-
- <sect2><heading>Defining alternative changelog formats
- </heading>
-
- <p>
- It is possible to use a different format to the standard
- one, by providing a parser for the format you wish to
- use.
- </p>
-
- <p>
- In order to have <tt>dpkg-parsechangelog</tt> run your
- parser, you must include a line within the last 40 lines
- of your file matching the Perl regular expression:
- <tt>\schangelog-format:\s+([0-9a-z]+)\W</tt> The part in
- parentheses should be the name of the format. For
- example, you might say:
- <example>
- @@@ changelog-format: joebloggs @@@
- </example>
- Changelog format names are non-empty strings of alphanumerics.
- </p>
-
- <p>
- If such a line exists then <tt>dpkg-parsechangelog</tt>
- will look for the parser as
- <file>/usr/lib/dpkg/parsechangelog/<var>format-name</var></file>
- or
- <file>/usr/local/lib/dpkg/parsechangelog/<var>format-name</var></file>;
- it is an error for it not to find it, or for it not to
- be an executable program. The default changelog format
- is <tt>dpkg</tt>, and a parser for it is provided with
- the <tt>dpkg</tt> package.
- </p>
-
- <p>
- The parser will be invoked with the changelog open on
- standard input at the start of the file. It should read
- the file (it may seek if it wishes) to determine the
- information required and return the parsed information
- to standard output in the form of a series of control
- fields in the standard format. By default it should
- return information about only the most recent version in
- the changelog; it should accept a
- <tt>-v<var>version</var></tt> option to return changes
- information from all versions present <em>strictly
- after</em> <var>version</var>, and it should then be an
- error for <var>version</var> not to be present in the
- changelog.
- </p>
-
- <p>
- The fields are:
- <list compact="compact">
- <item>
- <p><qref id="pkg-f-Source"><tt>Source</tt></qref></p>
- </item>
- <item>
- <p><qref id="versions"><tt>Version</tt></qref> (mandatory)</p>
- </item>
- <item>
- <p>
- <qref id="pkg-f-Distribution"><tt>Distribution</tt></qref>
- (mandatory)
- </p>
- </item>
- <item>
- <p><qref id="pkg-f-Urgency"><tt>Urgency</tt></qref> (mandatory)</p>
- </item>
- <item>
- <p>
- <qref id="pkg-f-Maintainer"><tt>Maintainer</tt></qref>
- (mandatory)
- </p>
- </item>
- <item>
- <p><qref id="pkg-f-Date"><tt>Date</tt></qref></p>
- </item>
- <item>
- <p>
- <qref id="pkg-f-Changes"><tt>Changes</tt></qref>
- (mandatory)
- </p>
- </item>
- </list>
-
- <p>
- If several versions are being returned (due to the use
- of <tt>-v</tt>), the urgency value should be of the
- highest urgency code listed at the start of any of the
- versions requested followed by the concatenated
- (space-separated) comments from all the versions
- requested; the maintainer, version, distribution and
- date should always be from the most recent version.
- </p>
-
- <p>
- For the format of the <tt>Changes</tt> field see <ref
- id="pkg-f-Changes">.
- </p>
-
- <p>
- If the changelog format which is being parsed always or
- almost always leaves a blank line between individual
- change notes these blank lines should be stripped out,
- so as to make the resulting output compact.
- </p>
-
- <p>
- If the changelog format does not contain date or package
- name information this information should be omitted from
- the output. The parser should not attempt to synthesise
- it or find it from other sources.
- </p>
-
- <p>
- If the changelog does not have the expected format the
- parser should exit with a nonzero exit status, rather
- than trying to muddle through and possibly generating
- incorrect output.
- </p>
-
- <p>
- A changelog parser may not interact with the user at
- all.</p></sect2>
- </sect1>
-
-<!-- FIXME: section pkg-srcsubstvars is the same as srcsubstvars -->
-
- <sect1 id="pkg-srcsubstvars"><heading><file>debian/substvars</file>
- and variable substitutions
- </heading>
-
- <p>
- When <prgn>dpkg-gencontrol</prgn>,
- <prgn>dpkg-genchanges</prgn> and <prgn>dpkg-source</prgn>
- generate control files they do variable substitutions on
- their output just before writing it. Variable
- substitutions have the form
- <tt>${<var>variable-name</var>}</tt>. The optional file
- <file>debian/substvars</file> contains variable substitutions
- to be used; variables can also be set directly from
- <file>debian/rules</file> using the <tt>-V</tt> option to the
- source packaging commands, and certain predefined
- variables are available.
- </p>
-
- <p>
- This file is usually generated and modified dynamically by
- <file>debian/rules</file> targets, in which case it must be
- removed by the <tt>clean</tt> target.
- </p>
-
- <p>
- See <manref name="dpkg-source" section="1"> for full
- details about source variable substitutions, including the
- format of <file>debian/substvars</file>.</p>
- </sect1>
-
- <sect1><heading><file>debian/files</file>
- </heading>
-
- <p>
- This file is not a permanent part of the source tree; it
- is used while building packages to record which files are
- being generated. <prgn>dpkg-genchanges</prgn> uses it
- when it generates a <file>.changes</file> file.
- </p>
-
- <p>
- It should not exist in a shipped source package, and so it
- (and any backup files or temporary files such as
- <file>files.new</file>
- <footnote>
- <p>
- <file>files.new</file> is used as a temporary file by
- <prgn>dpkg-gencontrol</prgn> and
- <prgn>dpkg-distaddfile</prgn> - they write a new
- version of <file>files</file> here before renaming it,
- to avoid leaving a corrupted copy if an error
- occurs
- </p>
- </footnote>) should be removed by the
- <tt>clean</tt> target. It may also be wise to
- ensure a fresh start by emptying or removing it at the
- start of the <tt>binary</tt> target.
- </p>
-
- <p>
- <prgn>dpkg-gencontrol</prgn> adds an entry to this file
- for the <file>.deb</file> file that will be created by
- <prgn>dpkg-deb</prgn> from the control file that it
- generates, so for most packages all that needs to be done
- with this file is to delete it in <tt>clean</tt>.
- </p>
-
- <p>
- If a package upload includes files besides the source
- package and any binary packages whose control files were
- made with <prgn>dpkg-gencontrol</prgn> then they should be
- placed in the parent of the package's top-level directory
- and <prgn>dpkg-distaddfile</prgn> should be called to add
- the file to the list in <file>debian/files</file>.</p>
- </sect1>
-
- <sect1><heading><file>debian/tmp</file>
- </heading>
-
- <p>
- This is the canonical temporary location for the
- construction of binary packages by the <tt>binary</tt>
- target. The directory <file>tmp</file> serves as the root of
- the filesystem tree as it is being constructed (for
- example, by using the package's upstream makefiles install
- targets and redirecting the output there), and it also
- contains the <tt>DEBIAN</tt> subdirectory. See <ref
- id="pkg-bincreating">.
- </p>
-
- <p>
- If several binary packages are generated from the same
- source tree it is usual to use several
- <file>debian/tmp<var>something</var></file> directories, for
- example <file>tmp-a</file> or <file>tmp-doc</file>.
- </p>
-
- <p>
- Whatever <file>tmp</file> directories are created and used by
- <tt>binary</tt> must of course be removed by the
- <tt>clean</tt> target.</p></sect1>
- </sect>
-
-
- <sect id="pkg-sourcearchives"><heading>Source packages as archives
- </heading>
-
- <p>
- As it exists on the FTP site, a Debian source package
- consists of three related files. You must have the right
- versions of all three to be able to use them.
- </p>
-
- <p>
- <taglist>
- <tag>Debian source control file - <tt>.dsc</tt></tag>
- <item>
-
- <p>
- This file contains a series of fields, identified and
- separated just like the fields in the control file of
- a binary package. The fields are listed below; their
- syntax is described above, in <ref id="pkg-controlfields">.
- <list compact="compact">
- <item>
- <p><qref id="pkg-f-Source"><tt>Source</tt></qref></p>
- </item>
- <item>
- <p><qref id="versions"><tt>Version</tt></qref></p>
- </item>
- <item>
- <p><qref id="pkg-f-Maintainer"><tt>Maintainer</tt></qref></p>
- </item>
- <item>
- <p><qref id="pkg-f-Binary"><tt>Binary</tt></qref></p>
- </item>
- <item>
- <p><qref id="pkg-f-Architecture"><tt>Architecture</tt></qref></p>
- </item>
- <item>
- <p>
- <qref id="relationships"><tt>Build-Depends</tt> et
- al.</qref> (source package interrelationships)
- </p>
- </item>
- <item>
- <p>
- <qref id="pkg-f-Standards-Version"><tt>Standards-Version</tt></qref></p>
- </item>
- <item>
- <p><qref id="pkg-f-Files"><tt>Files</tt></qref></p>
- </item>
- </list>
-
- <p>
- The source package control file is generated by
- <prgn>dpkg-source</prgn> when it builds the source
- archive, from other files in the source package,
- described above. When unpacking it is checked against
- the files and directories in the other parts of the
- source package, as described below.</p>
- </item>
-
- <tag>
- Original source archive -
- <file>
- <var>package</var>_<var>upstream-version</var>.orig.tar.gz
- </file>
- </tag>
-
- <item>
-
- <p>
- This is a compressed (with <tt>gzip -9</tt>)
- <prgn>tar</prgn> file containing the source code from
- the upstream authors of the program. The tarfile
- unpacks into a directory
- <file><var>package</var>-<var>upstream-version</var>.orig</file>,
- and does not contain files anywhere other than in
- there or in its subdirectories.</p>
+ forth. See <ref id="sourcecontrolfiles"> and
+ <ref id="binarycontrolfiles">.
+ </p>
+
+ <p>
+ It is usually generated automatically from information
+ in the source package by the
+ <prgn>dpkg-gencontrol</prgn> program, and with
+ assistance from <prgn>dpkg-shlibdeps</prgn>.
+ See <ref id="pkg-sourcetools">.
+ </p>
</item>
- <tag>
- Debianisation diff -
- <file>
- <var>package</var>_<var>upstream_version-revision</var>.diff.gz
- </file>
+ <tag><tt>postinst</tt>, <tt>preinst</tt>, <tt>postrm</tt>,
+ <tt>prerm</tt>
</tag>
<item>
-
<p>
- This is a unified context diff (<tt>diff -u</tt>)
- giving the changes which are required to turn the
- original source into the Debian source. These changes
- may only include editing and creating plain files.
- The permissions of files, the targets of symbolic
- links and the characteristics of special files or
- pipes may not be changed and no files may be removed
- or renamed.
+ These are exectuable files (usually scripts) which
+ <prgn>dpkg</prgn> runs during installation, upgrade
+ and removal of packages. They allow the package to
+ deal with matters which are particular to that package
+ or require more complicated processing than that
+ provided by <prgn>dpkg</prgn>. Details of when and
+ how they are called are in <ref id="maintainerscripts">.
</p>
<p>
- All the directories in the diff must exist, except the
- <file>debian</file> subdirectory of the top of the source
- tree, which will be created by
- <prgn>dpkg-source</prgn> if necessary when unpacking.
+ It is very important to make these scripts idempotent.
+ See <ref id="idempotency">.
</p>
<p>
- The <prgn>dpkg-source</prgn> program will
- automatically make the <file>debian/rules</file> file
- executable (see below).</p></item>
- </taglist>
+ The maintainer scripts are guaranteed to run with a
+ controlling terminal and can interact with the user.
+ See <ref id="controllingterminal">.
+ </p>
+ </item>
+ <tag><tt>conffiles</tt>
+ </tag>
+ <item>
+ This file contains a list of configuration files which
+ are to be handled automatically by <prgn>dpkg</prgn>
+ (see <ref id="pkg-conffiles">). Note that not necessarily
+ every configuration file should be listed here.
+ </item>
- <p>
- If there is no original source code - for example, if the
- package is specially prepared for Debian or the Debian
- maintainer is the same as the upstream maintainer - the
- format is slightly different: then there is no diff, and the
- tarfile is named
- <file><var>package</var>_<var>version</var>.tar.gz</file> and
- contains a directory
- <file><var>package</var>-<var>version</var></file>.
+ <tag><tt>shlibs</tt>
+ </tag>
+ <item>
+ This file contains a list of the shared libraries
+ supplied by the package, with dependency details for
+ each. This is used by <prgn>dpkg-shlibdeps</prgn>
+ when it determines what dependencies are required in a
+ package control file. The <tt>shlibs</tt> file format
+ is described on <ref id="shlibs">.
+ </item>
+ </taglist>
</p>
- </sect>
- <sect><heading>Unpacking a Debian source package without
- <prgn>dpkg-source</prgn>
- </heading>
+ <sect id="pkg-controlfile">
+ <heading>The main control information file: <tt>control</tt></heading>
<p>
- <tt>dpkg-source -x</tt> is the recommended way to unpack a
- Debian source package. However, if it is not available it
- is possible to unpack a Debian source archive as follows:
- <enumlist compact="compact">
- <item>
- <p>
- Untar the tarfile, which will create a <file>.orig</file>
- directory.</p>
- </item>
- <item>
- <p>Rename the <file>.orig</file> directory to
- <file><var>package</var>-<var>version</var></file>.</p>
- </item>
- <item>
- <p>
- Create the subdirectory <file>debian</file> at the top of
- the source tree.</p>
- </item>
- <item><p>Apply the diff using <tt>patch -p0</tt>.</p>
- </item>
- <item><p>Untar the tarfile again if you want a copy of the original
- source code alongside the Debianised version.</p>
- </item>
- </enumlist>
+ The most important control information file used by
+ <prgn>dpkg</prgn> when it installs a package is
+ <tt>control</tt>. It contains all the package's "vital
+ statistics".
+ </p>
<p>
- It is not possible to generate a valid Debian source archive
- without using <prgn>dpkg-source</prgn>. In particular,
- attempting to use <prgn>diff</prgn> directly to generate the
- <file>.diff.gz</file> file will not work.
+ The binary package control files of packages built from
+ Debian sources are made by a special tool,
+ <prgn>dpkg-gencontrol</prgn>, which reads
+ <file>debian/control</file> and <file>debian/changelog</file> to
+ find the information it needs. See <ref id="pkg-sourcepkg"> for
+ more details.
</p>
- <sect1><heading>Restrictions on objects in source packages
- </heading>
+ <p>
+ The fields in binary package control files are listed in
+ <ref id="binarycontrolfiles">.
+ </p>
- <p>
- The source package may not contain any hard links
- <footnote>
- <p>
- This is not currently detected when building source
- packages, but only when extracting
- them.
- </p>
- </footnote>
- <footnote>
- <p>
- 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>
+ A description of the syntax of control files and the purpose
+ of the fields is available in <ref id="controlfields">.
+ </p>
+ </sect>
- <p>
- The source packaging tools manage the changes between the
- original and Debianised source using <prgn>diff</prgn> and
- <prgn>patch</prgn>. Turning the original source tree as
- included in the <file>.orig.tar.gz</file> into the debianised
- source must not involve any changes which cannot be
- handled by these tools. Problematic changes which cause
- <prgn>dpkg-source</prgn> to halt with an error when
- building the source package are:
- <list compact="compact">
- <item><p>Adding or removing symbolic links, sockets or pipes.</p>
- </item>
- <item><p>Changing the targets of symbolic links.</p>
- </item>
- <item><p>Creating directories, other than <file>debian</file>.</p>
- </item>
- <item><p>Changes to the contents of binary files.</p></item>
- </list> Changes which cause <prgn>dpkg-source</prgn> to
- print a warning but continue anyway are:
- <list compact="compact">
- <item>
- <p>
- Removing files, directories or symlinks.
- <footnote>
- <p>
- Renaming a file is not treated specially - it is
- seen as the removal of the old file (which
- generates a warning, but is otherwise ignored),
- and the creation of the new
- one.</p>
- </footnote>
- </p>
- </item>
- <item>
- <p>
- Changed text files which are missing the usual final
- newline (either in the original or the modified
- source tree).
- </p>
- </item>
- </list>
- Changes which are not represented, but which are not detected by
- <prgn>dpkg-source</prgn>, are:
- <list compact="compact">
- <item><p>Changing the permissions of files (other than
- <file>debian/rules</file>) and directories.</p></item>
- </list>
- </p>
+ <sect>
+ <heading>Time Stamps</heading>
- <p>
- The <file>debian</file> directory and <file>debian/rules</file>
- are handled specially by <prgn>dpkg-source</prgn> - before
- applying the changes it will create the <file>debian</file>
- directory, and afterwards it will make
- <file>debian/rules</file> world-exectuable.
- </p>
- </sect1>
+ <p>
+ See <ref id="timestamps">.
+ </p>
</sect>
</appendix>
- <appendix id="pkg-controlfields"><heading>Control files and their
- fields (from old Packaging Manual)
- </heading>
+ <appendix id="pkg-sourcepkg">
+ <heading>Source packages (from old Packaging Manual) </heading>
<p>
- Many of the tools in the <prgn>dpkg</prgn> suite manipulate
- data in a common format, known as control files. Binary and
- source packages have control data as do the <file>.changes</file>
- files which control the installation of uploaded files, and
- <prgn>dpkg</prgn>'s internal databases are in a similar
- format.
+ The Debian binary packages in the distribution are generated
+ from Debian sources, which are in a special format to assist
+ the easy and automatic building of binaries.
</p>
- <sect><heading>Syntax of control files
- </heading>
-
- <p>
- A file consists of one or more paragraphs of fields. The
- paragraphs are separated by blank lines. Some control files
- only allow one paragraph; others allow several, in which
- case each paragraph often refers to a different package.
- </p>
+ <sect id="pkg-sourcetools">
+ <heading>Tools for processing source packages</heading>
<p>
- Each paragraph is a series of fields and values; each field
- consists of a name, followed by a colon and the value. It
- ends at the end of the line. Horizontal whitespace (spaces
- and tabs) may occur before or after the value and is ignored
- there; it is conventional to put a single space after the
- colon.
+ Various tools are provided for manipulating source packages;
+ they pack and unpack sources and help build of binary
+ packages and help manage the distribution of new versions.
</p>
<p>
- Some fields' values may span several lines; in this case
- each continuation line <em>must</em> start with a space or
- tab. Any trailing spaces or tabs at the end of individual
- lines of a field value are ignored.
+ They are introduced and typical uses described here; see
+ <manref name="dpkg-source" section="1"> for full
+ documentation about their arguments and operation.
</p>
<p>
- Except where otherwise stated only a single line of data is
- allowed and whitespace is not significant in a field body.
- Whitespace may never appear inside names (of packages,
- architectures, files or anything else), version numbers or
- in between the characters of multi-character version
- relationships.
+ For examples of how to construct a Debian source package,
+ and how to use those utilities that are used by Debian
+ source packages, please see the <prgn>hello</prgn> example
+ package.
</p>
- <p>
- Field names are not case-sensitive, but it is usual to
- capitalise the field names using mixed case as shown below.
- </p>
+ <sect1>
+ <heading>
+ <prgn>dpkg-source</prgn> - packs and unpacks Debian source
+ packages
+ </heading>
- <p>
- Blank lines, or lines consisting only of spaces and tabs,
- are not allowed within field values or between fields - that
- would mean a new paragraph.
- </p>
+ This program is frequently used by hand, and is also
+ called from package-independent automated building scripts
+ such as <prgn>dpkg-buildpackage</prgn>.
+ </p>
- <p>
- It is important to note that there are several fields which
- are optional as far as <prgn>dpkg</prgn> and the related
- tools are concerned, but which must appear in every Debian
- package, or whose omission may cause problems. When writing
- the control files for Debian packages you <em>must</em> read
- the Debian policy manual in conjuction with the details
- below and the list of fields for the particular file.</p>
- </sect>
+ <p>
+ To unpack a package it is typically invoked with
+ <example>
+ dpkg-source -x <var>.../path/to/filename</var>.dsc
+ </example>
+ </p>
- <sect><heading>List of fields
- </heading>
+ <p>
+ with the <file><var>filename</var>.tar.gz</file> and
+ <file><var>filename</var>.diff.gz</file> (if applicable) in
+ the same directory. It unpacks into
+ <file><var>package</var>-<var>version</var></file>, and if
+ applicable
+ <file><var>package</var>-<var>version</var>.orig</file>, in
+ the current directory.
+ </p>
- <sect1 id="pkg-f-Package"><heading><tt>Package</tt>
- </heading>
+ <p>
+ To create a packed source archive it is typically invoked:
+ <example>
+ dpkg-source -b <var>package</var>-<var>version</var>
+ </example>
+ </p>
<p>
- The name of the binary package. Package names consist of
- the alphanumerics and <tt>+</tt> <tt>-</tt> <tt>.</tt>
- (plus, minus and full stop).
- <footnote>
- <p>
- The characters <tt>@</tt> <tt>:</tt> <tt>=</tt>
- <tt>%</tt> <tt>_</tt> (at, colon, equals, percent
- and underscore) used to be legal and are still
- accepted when found in a package file, but may not be
- used in new packages
- </p>
- </footnote>
+ This will create the <file>.dsc</file>, <file>.tar.gz</file> and
+ <file>.diff.gz</file> (if appropriate) in the current
+ directory. <prgn>dpkg-source</prgn> does not clean the
+ source tree first - this must be done separately if it is
+ required.
</p>
<p>
- They must be at least two characters and must start with
- an alphanumeric. In current versions of dpkg they are
- sort of case-sensitive<footnote><p>This is a
- bug.</p></footnote>; use lowercase package names unless
- the package you're building (or referring to, in other
- fields) is already using uppercase.</p>
+ See also <ref id="pkg-sourcearchives">.</p>
</sect1>
- <sect1 id="pkg-f-Version"><heading><tt>Version</tt>
+
+ <sect1>
+ <heading>
+ <prgn>dpkg-buildpackage</prgn> - overall package-building
+ control script
</heading>
<p>
- This lists the source or binary package's version number -
- see <ref id="versions">.
+ <prgn>dpkg-buildpackage</prgn> is a script which invokes
+ <prgn>dpkg-source</prgn>, the <file>debian/rules</file>
+ targets <tt>clean</tt>, <tt>build</tt> and
+ <tt>binary</tt>, <prgn>dpkg-genchanges</prgn> and
+ <prgn>pgp</prgn> to build a signed source and binary
+ package upload.
</p>
+ <p>
+ It is usually invoked by hand from the top level of the
+ built or unbuilt source directory. It may be invoked with
+ no arguments; useful arguments include:
+ <taglist compact="compact">
+ <tag><tt>-uc</tt>, <tt>-us</tt></tag>
+ <item>
+ <p>
+ Do not PGP-sign the <tt>.changes</tt> file or the
+ source package <tt>.dsc</tt> file, respectively.</p>
+ </item>
+ <tag><tt>-p<var>pgp-command</var></tt></tag>
+ <item>
+ <p>
+ Invoke <var>pgp-command</var> instead of finding
+ <tt>pgp</tt> on the <prgn>PATH</prgn>.
+ <var>pgp-command</var> must behave just like
+ <prgn>pgp</prgn>.</p>
+ </item>
+ <tag><tt>-r<var>root-command</var></tt></tag>
+ <item>
+ <p>
+ When root privilege is required, invoke the command
+ <var>root-command</var>. <var>root-command</var>
+ should invoke its first argument as a command, from
+ the <prgn>PATH</prgn> if necessary, and pass its
+ second and subsequent arguments to the command it
+ calls. If no <var>root-command</var> is supplied
+ then <var>dpkg-buildpackage</var> will take no
+ special action to gain root privilege, so that for
+ most packages it will have to be invoked as root to
+ start with.</p>
+ </item>
+ <tag><tt>-b</tt>, <tt>-B</tt></tag>
+ <item>
+ <p>
+ Two types of binary-only build and upload - see
+ <manref name="dpkg-source" section="1">.
+ </p>
+ </item>
+ </taglist>
+ </p>
</sect1>
- <sect1 id="pkg-f-Architecture"><heading><tt>Architecture</tt>
+ <sect1>
+ <heading>
+ <prgn>dpkg-gencontrol</prgn> - generates binary package
+ control files
</heading>
<p>
- This is the architecture string; it is a single word for
- the Debian architecture.
+ This program is usually called from <file>debian/rules</file>
+ (see <ref id="pkg-sourcetree">) in the top level of the source
+ tree.
</p>
<p>
- <prgn>dpkg</prgn> will check the declared architecture of
- a binary package against its own compiled-in value before
- it installs it.
+ This is usually done just before the files and directories in the
+ temporary directory tree where the package is being built have their
+ permissions and ownerships set and the package is constructed using
+ <prgn>dpkg-deb/</prgn>
+ <footnote>
+ This is so that the control file which is produced has
+ the right permissions
+ </footnote>.
</p>
<p>
- The special value <tt>all</tt> indicates that the package
- is architecture-independent.
+ <prgn>dpkg-gencontrol</prgn> must be called after all the
+ files which are to go into the package have been placed in
+ the temporary build directory, so that its calculation of
+ the installed size of a package is correct.
</p>
<p>
- In the main <file>debian/control</file> file in the source
- package, or in the source package control file
- <file>.dsc</file>, a list of architectures (separated by
- spaces) is also allowed, as is the special value
- <tt>any</tt>. A list indicates that the source will build
- an architecture-dependent package, and will only work
- correctly on the listed architectures. <tt>any</tt>
- indicates that though the source package isn't dependent
- on any particular architecture and should compile fine on
- any one, the binary package(s) produced are not
- architecture-independent but will instead be specific to
- whatever the current build architecture is.
+ It is also necessary for <prgn>dpkg-gencontrol</prgn> to
+ be run after <prgn>dpkg-shlibdeps</prgn> so that the
+ variable substitutions created by
+ <prgn>dpkg-shlibdeps</prgn> in <file>debian/substvars</file>
+ are available.
</p>
<p>
- In a <file>.changes</file> file the <tt>Architecture</tt>
- field lists the architecture(s) of the package(s)
- currently being uploaded. This will be a list; if the
- source for the package is being uploaded too the special
- entry <tt>source</tt> is also present.
+ For a package which generates only one binary package, and
+ which builds it in <file>debian/tmp</file> relative to the top
+ of the source package, it is usually sufficient to call
+ <prgn>dpkg-gencontrol</prgn>.
</p>
<p>
- See <ref id="pkg-debianrules"> for information how to get the
- architecture for the build process.
+ Sources which build several binaries will typically need
+ something like:
+ <example>
+ dpkg-gencontrol -Pdebian/tmp-<var>pkg</var> -p<var>package</var>
+ </example> The <tt>-P</tt> tells
+ <prgn>dpkg-gencontrol</prgn> that the package is being
+ built in a non-default directory, and the <tt>-p</tt>
+ tells it which package's control file should be generated.
</p>
+
+ <p>
+ <prgn>dpkg-gencontrol</prgn> also adds information to the
+ list of files in <file>debian/files</file>, for the benefit of
+ (for example) a future invocation of
+ <prgn>dpkg-genchanges</prgn>.</p>
</sect1>
- <sect1 id="pkg-f-Maintainer"><heading><tt>Maintainer</tt>
+ <sect1>
+ <heading>
+ <prgn>dpkg-shlibdeps</prgn> - calculates shared library
+ dependencies
</heading>
<p>
- The package maintainer's name and email address. The name
- should come first, then the email address inside angle
- brackets <tt><></tt> (in RFC822 format).
+ This program is usually called from <file>debian/rules</file>
+ just before <prgn>dpkg-gencontrol</prgn> (see <ref
+ id="pkg-sourcetree">), in the top level of the source tree.
</p>
<p>
- If the maintainer's name contains a full stop then the
- whole field will not work directly as an email address due
- to a misfeature in the syntax specified in RFC822; a
- program using this field as an address must check for this
- and correct the problem if necessary (for example by
- putting the name in round brackets and moving it to the
- end, and bringing the email address forward).
+ Its arguments are executables.
+ <footnote>
+ <p>
+ In a forthcoming dpkg version,
+ <prgn>dpkg-shlibdeps</prgn> would be required to be
+ called on shared libraries as well.
+ </p>
+ <p>
+ They may be specified either in the locations in the
+ source tree where they are created or in the locations
+ in the temporary build tree where they are installed
+ prior to binary package creation.
+ </p>
+ </footnote> for which shared library dependencies should
+ be included in the binary package's control file.
</p>
<p>
- In a <file>.changes</file> file or parsed changelog data this
- contains the name and email address of the person
- responsible for the particular version in question - this
- may not be the package's usual maintainer.
+ If some of the found shared libraries should only
+ warrant a <tt>Recommends</tt> or <tt>Suggests</tt>, or if
+ some warrant a <tt>Pre-Depends</tt>, this can be achieved
+ by using the <tt>-d<var>dependency-field</var></tt> option
+ before those executable(s). (Each <tt>-d</tt> option
+ takes effect until the next <tt>-d</tt>.)
</p>
<p>
- This field is usually optional in as far as the
- <prgn>dpkg</prgn> are concerned, but its absence when
- building packages usually generates a warning.</p>
- </sect1>
+ <prgn>dpkg-shlibdeps</prgn> does not directly cause the
+ output control file to be modified. Instead by default it
+ adds to the <file>debian/substvars</file> file variable
+ settings like <tt>shlibs:Depends</tt>. These variable
+ settings must be referenced in dependency fields in the
+ appropriate per-binary-package sections of the source
+ control file.
+ </p>
- <sect1 id="pkg-f-Source"><heading><tt>Source</tt>
- </heading>
+ <p>
+ For example, the <prgn>procps</prgn> package generates two
+ kinds of binaries, simple C binaries like <prgn>ps</prgn>
+ which require a predependency and full-screen ncurses
+ binaries like <prgn>top</prgn> which require only a
+ recommendation. It can say in its <file>debian/rules</file>:
+ <example>
+ dpkg-shlibdeps -dPre-Depends ps -dRecommends top
+ </example>
+ and then in its main control file <file>debian/control</file>:
+ <example>
+ <var>...</var>
+ Package: procps
+ Pre-Depends: ${shlibs:Pre-Depends}
+ Recommends: ${shlibs:Recommends}
+ <var>...</var>
+ </example>
+ </p>
<p>
- This field identifies the source package name.
+ Sources which produce several binary packages with
+ different shared library dependency requirements can use
+ the <tt>-p<var>varnameprefix</var></tt> option to override
+ the default <tt>shlibs:</tt> prefix (one invocation of
+ <prgn>dpkg-shlibdeps</prgn> per setting of this option).
+ They can thus produce several sets of dependency
+ variables, each of the form
+ <tt><var>varnameprefix</var>:<var>dependencyfield</var></tt>,
+ which can be referred to in the appropriate parts of the
+ binary package control files.
</p>
+ </sect1>
+
+
+ <sect1>
+ <heading>
+ <prgn>dpkg-distaddfile</prgn> - adds a file to
+ <file>debian/files</file>
+ </heading>
<p>
- In a main source control information or a
- <file>.changes</file> or <file>.dsc</file> file or parsed
- changelog data this may contain only the name of the
- source package.
+ Some packages' uploads need to include files other than
+ the source and binary package files.
</p>
<p>
- In the control file of a binary package (or in a
- <file>Packages</file> file) it may be followed by a version
- number in parentheses.
- <footnote>
- <p>
- It is usual to leave a space after the package name if
- a version number is specified.
- </p>
- </footnote> This version number may be omitted (and is, by
- <prgn>dpkg-gencontrol</prgn>) if it has the same value as
- the <tt>Version</tt> field of the binary package in
- question. The field itself may be omitted from a binary
- package control file when the source package has the same
- name and version as the binary package.
+ <prgn>dpkg-distaddfile</prgn> adds a file to the
+ <file>debian/files</file> file so that it will be included in
+ the <file>.changes</file> file when
+ <prgn>dpkg-genchanges</prgn> is run.
</p>
- </sect1>
- <sect1><heading>Package interrelationship fields:
- <tt>Depends</tt>, <tt>Pre-Depends</tt>,
- <tt>Recommends</tt> <tt>Suggests</tt>, <tt>Conflicts</tt>,
- <tt>Provides</tt>, <tt>Replaces</tt>
- </heading>
+ <p>
+ It is usually invoked from the <tt>binary</tt> target of
+ <file>debian/rules</file>:
+ <example>
+ dpkg-distaddfile <var>filename</var> <var>section</var> <var>priority</var>
+ </example>
+ The <var>filename</var> is relative to the directory where
+ <prgn>dpkg-genchanges</prgn> will expect to find it - this
+ is usually the directory above the top level of the source
+ tree. The <file>debian/rules</file> target should put the
+ file there just before or just after calling
+ <prgn>dpkg-distaddfile</prgn>.
+ </p>
<p>
- These fields describe the package's relationships with
- other packages. Their syntax and semantics are described
- in <ref id="relationships">.</p>
+ The <var>section</var> and <var>priority</var> are passed
+ unchanged into the resulting <file>.changes</file> file.
+ </p>
</sect1>
- <sect1 id="pkg-f-Description"><heading><tt>Description</tt>
+
+ <sect1><heading><prgn>dpkg-genchanges</prgn> - generates a <file>.changes</file> upload
+ control file
</heading>
<p>
- In a binary package <tt>Packages</tt> file or main source
- control file this field contains a description of the
- binary package, in a special format. See <ref
- id="descriptions"> for details.
+ This program is usually called by package-independent
+ automatic building scripts such as
+ <prgn>dpkg-buildpackage</prgn>, but it may also be called
+ by hand.
</p>
<p>
- In a <file>.changes</file> file it contains a summary of the
- descriptions for the packages being uploaded. The part of
- the field before the first newline is empty; thereafter
- each line has the name of a binary package and the summary
- description line from that binary package. Each line is
- indented by one space.</p>
+ It is usually called in the top level of a built source
+ tree, and when invoked with no arguments will print out a
+ straightforward <file>.changes</file> file based on the
+ information in the source package's changelog and control
+ file and the binary and source packages which should have
+ been built.
+ </p>
</sect1>
- <sect1 id="pkg-f-Essential"><heading><tt>Essential</tt>
+
+ <sect1><heading><prgn>dpkg-parsechangelog</prgn> - produces parsed representation of
+ a changelog
</heading>
<p>
- This is a boolean field which may occur only in the
- control file of a binary package (or in the
- <file>Packages</file> file) or in a per-package fields
- paragraph of a main source control data file.
+ This program is used internally by
+ <prgn>dpkg-source</prgn> et al. It may also occasionally
+ be useful in <file>debian/rules</file> and elsewhere. It
+ parses a changelog, <file>debian/changelog</file> by default,
+ and prints a control-file format representation of the
+ information in it to standard output.
</p>
-
- <p>
- If set to <tt>yes</tt> then <prgn>dpkg</prgn> and
- <prgn>dselect</prgn> will refuse to remove the package
- (though it can be upgraded and/or replaced). The other
- possible value is <tt>no</tt>, which is the same as not
- having the field at all.</p>
</sect1>
- <sect1 id="pkg-f-classification"><heading><tt>Section</tt> and
- <tt>Priority</tt>
- </heading>
-
- <p>
- These two fields classify the package. The
- <tt>Priority</tt> represents how important that it is that
- the user have it installed; the <tt>Section</tt>
- represents an application area into which the package has
- been classified.
- </p>
+ <sect1 id="pkg-dpkgarch"><heading><prgn>dpkg-architecture</prgn> -
+ information about the build and host system
+ </heading>
- <p>
- When they appear in the <file>debian/control</file> file these
- fields give values for the section and priority subfields
- of the <tt>Files</tt> field of the <file>.changes</file> file,
- and give defaults for the section and priority of the
- binary packages.
- </p>
+ <p>
+ This program can be used manually, but is also invoked by
+ <tt>dpkg-buildpackage</tt> or <file>debian/rules</file> to set
+ to set environment or make variables which specify the build and
+ host architecture for the package building process.
+ </p>
+ </sect1>
+ </sect>
- <p>
- The section and priority are represented, though not as
- separate fields, in the information for each file in the
- <qref id="pkg-f-Files"><tt>-File</tt></qref>field of a
- <file>.changes</file> file. The section value in a
- <file>.changes</file> file is used to decide where to install
- a package in the FTP archive.
- </p>
+ <sect id="pkg-sourcetree">
+ <heading>The Debianised source tree</heading>
- <p>
- These fields are not used by by <prgn>dpkg</prgn> proper,
- but by <prgn>dselect</prgn> when it sorts packages and
- selects defaults. See the Debian policy manual for the
- priorities in use and the criteria for selecting the
- priority for a Debian package, and look at the Debian FTP
- archive for a list of currently in-use priorities.
- </p>
+ <p>
+ The source archive scheme described later is intended to
+ allow a Debianised source tree with some associated control
+ information to be reproduced and transported easily. The
+ Debianised source tree is a version of the original program
+ with certain files added for the benefit of the
+ Debianisation process, and with any other changes required
+ made to the rest of the source code and installation
+ scripts.
+ </p>
- <p>
- These fields may appear in binary package control files,
- in which case they provide a default value in case the
- <file>Packages</file> files are missing the information.
- <prgn>dpkg</prgn> and <prgn>dselect</prgn> will only use
- the value from a <file>.deb</file> file if they have no other
- information; a value listed in a <file>Packages</file> file
- will always take precedence. By default
- <prgn>dpkg-gencontrol</prgn> does not include the section
- and priority in the control file of a binary package - use
- the <tt>-isp</tt>, <tt>-is</tt> or <tt>-ip</tt> options to
- achieve this effect.</p>
- </sect1>
+ <p>
+ The extra files created for Debian are in the subdirectory
+ <file>debian</file> of the top level of the Debianised source
+ tree. They are described below.
+ </p>
- <sect1 id="pkg-f-Binary"><heading><tt>Binary</tt>
- </heading>
+ <sect1 id="pkg-debianrules">
+ <heading><file>debian/rules</file> - the main building script</heading>
<p>
- This field is a list of binary packages.
+ See <ref id="debianrules">.
</p>
+ </sect1>
- <p>
- When it appears in the <file>.dsc</file> file it is the list
- of binary packages which a source package can produce. It
- does not necessarily produce all of these binary packages
- for every architecture. The source control file doesn't
- contain details of which architectures are appropriate for
- which of the binary packages.
- </p>
+
+ <sect1 id="pkg-dpkgchangelog">
+ <heading><file>debian/changelog</file></heading>
<p>
- When it appears in a <file>.changes</file> file it lists the
- names of the binary packages actually being uploaded.
+ See <ref id="dpkgchangelog">.
</p>
<p>
- The syntax is a list of binary packages separated by
- commas.
- <footnote>
+ It is recommended that the entire changelog be encoded in the
+ <url id="http://www.cis.ohio-state.edu/cgi-bin/rfc/rfc2279.html" name="UTF-8">
+ encoding of
+ <url id="http://www.unicode.org/"
+ name="Unicode">.<footnote>
<p>
- A space after each comma is conventional.
+ Support for Unicode, and specifically UTF-8, is
+ steadily increasing among popular applications in
+ Debian. For example, in unstable, GNOME 2 has
+ excellent support (almost level 2) in almost all its
+ applications; the big remaining one is gnome-terminal,
+ of which one requires development versions in order to
+ support UTF-8 (available in Debian experimental now if
+ you want to play). I think that by the time sarge is
+ released, UTF-8 support will start to hit critical
+ mass. </p>
+ <p>
+ I think it is fairly obvious that we need to
+ eventually transition to UTF-8 for our package
+ infrastructure; it is really the only sane charset in
+ an international environment. Now, we can't switch to
+ using UTF-8 for package control fields and the like
+ until dpkg has better support, but one thing we can
+ start doing today is requesting that Debian changelogs
+ are UTF-8 encoded. At some point in time, we can start
+ requiring them to do so.
</p>
- </footnote> Currently the packages must be separated using
- only spaces in the <file>.changes</file> file.</p>
- </sect1>
+ <p>
+ Checking for non-UTF8 characters in a changelog is
+ trivial. Dump the file through
+ <example>iconv -f utf-8 -t ucs-4</example>
+ discard the output, and check the return
+ value. If there are any characters in the stream
+ which are invalid UTF-8 sequences, iconv will exit
+ with an error code; and this will be the case for the
+ vast majority of other character sets.
+ </p>
+ </footnote>
+ </p>
- <sect1 id="pkg-f-Installed-Size"><heading><tt>Installed-Size</tt>
- </heading>
+ <sect2><heading>Defining alternative changelog formats
+ </heading>
- <p>
- This field appears in the control files of binary
- packages, and in the <file>Packages</file> files. It gives
- the total amount of disk space required to install the
- named package.
- </p>
+ <p>
+ It is possible to use a different format to the standard
+ one, by providing a parser for the format you wish to
+ use.
+ </p>
- <p>
- The disk space is represented in kilobytes as a simple
- decimal number.</p>
+ <p>
+ In order to have <tt>dpkg-parsechangelog</tt> run your
+ parser, you must include a line within the last 40 lines
+ of your file matching the Perl regular expression:
+ <tt>\schangelog-format:\s+([0-9a-z]+)\W</tt> The part in
+ parentheses should be the name of the format. For
+ example, you might say:
+ <example>
+ @@@ changelog-format: joebloggs @@@
+ </example>
+ Changelog format names are non-empty strings of alphanumerics.
+ </p>
+
+ <p>
+ If such a line exists then <tt>dpkg-parsechangelog</tt>
+ will look for the parser as
+ <file>/usr/lib/dpkg/parsechangelog/<var>format-name</var></file>
+ or
+ <file>/usr/local/lib/dpkg/parsechangelog/<var>format-name</var></file>;
+ it is an error for it not to find it, or for it not to
+ be an executable program. The default changelog format
+ is <tt>dpkg</tt>, and a parser for it is provided with
+ the <tt>dpkg</tt> package.
+ </p>
+
+ <p>
+ The parser will be invoked with the changelog open on
+ standard input at the start of the file. It should read
+ the file (it may seek if it wishes) to determine the
+ information required and return the parsed information
+ to standard output in the form of a series of control
+ fields in the standard format. By default it should
+ return information about only the most recent version in
+ the changelog; it should accept a
+ <tt>-v<var>version</var></tt> option to return changes
+ information from all versions present <em>strictly
+ after</em> <var>version</var>, and it should then be an
+ error for <var>version</var> not to be present in the
+ changelog.
+ </p>
+
+ <p>
+ The fields are:
+ <list compact="compact">
+ <item><qref id="f-Source"><tt>Source</tt></qref></item>
+ <item><qref id="f-Version"><tt>Version</tt></qref> (mandatory)</item>
+ <item><qref id="f-Distribution"><tt>Distribution</tt></qref> (mandatory)</item>
+ <item><qref id="f-Urgency"><tt>Urgency</tt></qref> (mandatory)</item>
+ <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
+ <item><qref id="f-Date"><tt>Date</tt></qref></item>
+ <item><qref id="f-Changes"><tt>Changes</tt></qref> (mandatory)</item>
+ </list>
+ </p>
+
+ <p>
+ If several versions are being returned (due to the use
+ of <tt>-v</tt>), the urgency value should be of the
+ highest urgency code listed at the start of any of the
+ versions requested followed by the concatenated
+ (space-separated) comments from all the versions
+ requested; the maintainer, version, distribution and
+ date should always be from the most recent version.
+ </p>
+
+ <p>
+ For the format of the <tt>Changes</tt> field see
+ <ref id="f-Changes">.
+ </p>
+
+ <p>
+ If the changelog format which is being parsed always or
+ almost always leaves a blank line between individual
+ change notes these blank lines should be stripped out,
+ so as to make the resulting output compact.
+ </p>
+
+ <p>
+ If the changelog format does not contain date or package
+ name information this information should be omitted from
+ the output. The parser should not attempt to synthesise
+ it or find it from other sources.
+ </p>
+
+ <p>
+ If the changelog does not have the expected format the
+ parser should exit with a nonzero exit status, rather
+ than trying to muddle through and possibly generating
+ incorrect output.
+ </p>
+
+ <p>
+ A changelog parser may not interact with the user at
+ all.
+ </p>
+ </sect2>
</sect1>
- <sect1 id="pkg-f-Files"><heading><tt>Files</tt>
- </heading>
+ <sect1 id="pkg-srcsubstvars">
+ <heading><file>debian/substvars</file> and variable substitutions</heading>
<p>
- This field contains a list of files with information about
- each one. The exact information and syntax varies with
- the context. In all cases the part of the field
- contents on the same line as the field name is empty. The
- remainder of the field is one line per file, each line
- being indented by one space and containing a number of
- sub-fields separated by spaces.
+ See <ref id="substvars">.
</p>
- <p>
- In the <file>.dsc</file> (Debian source control) file each
- line contains the MD5 checksum, size and filename of the
- tarfile and (if applicable) diff file which make up the
- remainder of the source package.
- <footnote>
- <p>
- That is, the parts which are not the
- <tt>.dsc</tt>.
- </p>
- </footnote> The exact forms of the filenames are described
- in <ref id="pkg-sourcearchives">.
- </p>
+ </sect1>
- <p>
- In the <file>.changes</file> file this contains one line per
- file being uploaded. Each line contains the MD5 checksum,
- size, section and priority and the filename. The section
- and priority are the values of the corresponding fields in
- the main source control file - see <ref
- id="pkg-f-classification">. If no section or priority is
- specified then <tt>-</tt> should be used, though section
- and priority values must be specified for new packages to
- be installed properly.
- </p>
+ <sect1>
+ <heading><file>debian/files</file></heading>
<p>
- The special value <tt>byhand</tt> for the section in a
- <tt>.changes</tt> file indicates that the file in question
- is not an ordinary package file and must by installed by
- hand by the distribution maintainers. If the section is
- <tt>byhand</tt> the priority should be <tt>-</tt>.
+ See <ref id="debianfiles">.
</p>
-
- <p>
- If a new Debian revision of a package is being shipped and
- no new original source archive is being distributed the
- <tt>.dsc</tt> must still contain the <tt>Files</tt> field
- entry for the original source archive
- <file><var>package</var>-<var>upstream-version</var>.orig.tar.gz</file>,
- but the <file>.changes</file> file should leave it out. In
- this case the original source archive on the distribution
- site must match exactly, byte-for-byte, the original
- source archive which was used to generate the
- <file>.dsc</file> file and diff which are being uploaded.</p>
</sect1>
-
- <sect1
- id="pkg-f-Standards-Version"><heading><tt>Standards-Version</tt>
+ <sect1><heading><file>debian/tmp</file>
</heading>
<p>
- The most recent version of the standards (the
- <prgn>dpkg</prgn> programmers' and policy manuals and
- associated texts) with which the package complies. This
- is updated manually when editing the source package to
- conform to newer standards; it can sometimes be used to
- tell when a package needs attention.
+ This is the canonical temporary location for the
+ construction of binary packages by the <tt>binary</tt>
+ target. The directory <file>tmp</file> serves as the root of
+ the filesystem tree as it is being constructed (for
+ example, by using the package's upstream makefiles install
+ targets and redirecting the output there), and it also
+ contains the <tt>DEBIAN</tt> subdirectory. See <ref
+ id="pkg-bincreating">.
+ </p>
+
+ <p>
+ If several binary packages are generated from the same
+ source tree it is usual to use several
+ <file>debian/tmp<var>something</var></file> directories, for
+ example <file>tmp-a</file> or <file>tmp-doc</file>.
</p>
<p>
- Its format is the same as that of a version number except
- that no epoch or Debian revision is allowed - see <ref
- id="versions">.</p>
- </sect1>
+ Whatever <file>tmp</file> directories are created and used by
+ <tt>binary</tt> must of course be removed by the
+ <tt>clean</tt> target.</p></sect1>
+ </sect>
- <sect1 id="pkg-f-Distribution"><heading><tt>Distribution</tt>
- </heading>
+ <sect id="pkg-sourcearchives"><heading>Source packages as archives
+ </heading>
- <p>
- In a <file>.changes</file> file or parsed changelog output
- this contains the (space-separated) name(s) of the
- distribution(s) where this version of the package should
- be or was installed. Distribution names follow the rules
- for package names. (See <ref id="pkg-f-Package">).
- </p>
+ <p>
+ As it exists on the FTP site, a Debian source package
+ consists of three related files. You must have the right
+ versions of all three to be able to use them.
+ </p>
- <p>
- Current distribution values are:
+ <p>
<taglist>
- <tag><em>stable</em></tag>
+ <tag>Debian source control file - <tt>.dsc</tt></tag>
<item>
- <p>
- This is the current "released" version of Debian
- GNU/Linux. A new version is released approximately
- every 3 months after the <em>development</em> code has
- been <em>frozen</em> for a month of testing. Once the
- distribution is <em>stable</em> only major bug fixes
- are allowed. When changes are made to this
- distribution, the release number is increased
- (for example: 1.2r1 becomes 1.2r2 then 1.2r3, etc).
- </p>
+ This file is a control file used by <prgn>dpkg-source</prgn>
+ to extract a source package.
+ See <ref id="debiansourcecontrolfiles">.
</item>
- <tag><em>unstable</em></tag>
+ <tag>
+ Original source archive -
+ <file>
+ <var>package</var>_<var>upstream-version</var>.orig.tar.gz
+ </file>
+ </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>
+ This is a compressed (with <tt>gzip -9</tt>)
+ <prgn>tar</prgn> file containing the source code from
+ the upstream authors of the program. The tarfile
+ unpacks into a directory
+ <file><var>package</var>-<var>upstream-version</var>.orig</file>,
+ and does not contain files anywhere other than in
+ there or in its subdirectories.</p>
</item>
- <tag><em>contrib</em></tag>
+ <tag>
+ Debianisation diff -
+ <file>
+ <var>package</var>_<var>upstream_version-revision</var>.diff.gz
+ </file>
+ </tag>
<item>
+
<p>
- The packages with this distribution value do not meet
- the criteria for inclusion in the main Debian
- distribution as defined by the Policy Manual, but meet
- the criteria for the <em>contrib</em>
- Distribution. There is currently no distinction
- between stable and unstable packages in the
- <em>contrib</em> or <em>non-free</em>
- distributions. Use your best judgement in downloading
- from this Distribution.</p>
- </item>
+ This is a unified context diff (<tt>diff -u</tt>)
+ giving the changes which are required to turn the
+ original source into the Debian source. These changes
+ may only include editing and creating plain files.
+ The permissions of files, the targets of symbolic
+ links and the characteristics of special files or
+ pipes may not be changed and no files may be removed
+ or renamed.
+ </p>
- <tag><em>non-free</em></tag>
- <item>
<p>
- Like the packages in the <em>contrib</em> seciton,
- the packages in <em>non-free</em> do not meet the
- criteria for inclusion in the main Debian distribution
- as defined by the Policy Manual. Again, use your best
- judgement in downloading from this Distribution.</p>
+ All the directories in the diff must exist, except the
+ <file>debian</file> subdirectory of the top of the source
+ tree, which will be created by
+ <prgn>dpkg-source</prgn> if necessary when unpacking.
+ </p>
- <tag><em>experimental</em></tag>
- <item>
<p>
- The packages with this distribution value are deemed
- by their maintainers to be high risk. Oftentimes they
- represent early beta or developmental packages from
- various sources that the maintainers want people to
- try, but are not ready to be a part of the other parts
- of the Debian distribution tree. Download at your own
- risk.</p>
- </item>
+ The <prgn>dpkg-source</prgn> program will
+ automatically make the <file>debian/rules</file> file
+ executable (see below).</p></item>
+ </taglist>
+
+
+ <p>
+ If there is no original source code - for example, if the
+ package is specially prepared for Debian or the Debian
+ maintainer is the same as the upstream maintainer - the
+ format is slightly different: then there is no diff, and the
+ tarfile is named
+ <file><var>package</var>_<var>version</var>.tar.gz</file> and
+ contains a directory
+ <file><var>package</var>-<var>version</var></file>.
+ </p>
+ </sect>
+
+ <sect>
+ <heading>Unpacking a Debian source package without <prgn>dpkg-source</prgn></heading>
- <tag><em>frozen</em></tag>
+ <p>
+ <tt>dpkg-source -x</tt> is the recommended way to unpack a
+ Debian source package. However, if it is not available it
+ is possible to unpack a Debian source archive as follows:
+ <enumlist compact="compact">
+ <item>
+ <p>
+ Untar the tarfile, which will create a <file>.orig</file>
+ directory.</p>
+ </item>
+ <item>
+ <p>Rename the <file>.orig</file> directory to
+ <file><var>package</var>-<var>version</var></file>.</p>
+ </item>
<item>
- <p>
- From time to time, (currently, every 3 months) the
- <em>unstable</em> distribution enters a state of
- "code-freeze" in anticipation of release as a
- <em>stable</em> version. During this period of testing
- (usually 4 weeks) only fixes for existing or
- newly-discovered bugs will be allowed.
- </p>
- </item>
- </taglist> You should list <em>all</em> distributions that
- the package should be installed into. Except in unusual
- circumstances, installations to <em>stable</em> should also
- go into <em>frozen</em> (if it exists) and
- <em>unstable</em>. Likewise, installations into
- <em>frozen</em> should also go into <em>unstable</em>.</p>
- </sect1>
+ <p>
+ Create the subdirectory <file>debian</file> at the top of
+ the source tree.</p>
+ </item>
+ <item><p>Apply the diff using <tt>patch -p0</tt>.</p>
+ </item>
+ <item><p>Untar the tarfile again if you want a copy of the original
+ source code alongside the Debianised version.</p>
+ </item>
+ </enumlist>
- <sect1 id="pkg-f-Urgency"><heading><tt>Urgency</tt>
- </heading>
+ <p>
+ It is not possible to generate a valid Debian source archive
+ without using <prgn>dpkg-source</prgn>. In particular,
+ attempting to use <prgn>diff</prgn> directly to generate the
+ <file>.diff.gz</file> file will not work.
+ </p>
+
+ <sect1>
+ <heading>Restrictions on objects in source packages</heading>
<p>
- This is a description of how important it is to upgrade to
- this version from previous ones. It consists of a single
- keyword usually taking one of the values <tt>LOW</tt>,
- <tt>MEDIUM</tt> or <tt>HIGH</tt>) followed by an optional
- commentary (separated by a space) which is usually in
- parentheses. For example:
- <example>
- Urgency: LOW (HIGH for diversions users)
- </example>
+ The source package may not contain any hard links
+ <footnote>
+ This is not currently detected when building source
+ packages, but only when extracting
+ them.
+ </footnote>
+ <footnote>
+ Hard links may be permitted at some point in the
+ future, but would require a fair amount of
+ work.
+ </footnote>, device special files, sockets or setuid or
+ setgid files.
+ <footnote>
+ Setgid directories are allowed.
+ </footnote>
</p>
<p>
- This field appears in the <file>.changes</file> file and in
- parsed changelogs; its value appears as the value of the
- <tt>urgency</tt> attribute in a <prgn>dpkg</prgn>-style
- changelog (see <ref id="pkg-dpkgchangelog">).
+ The source packaging tools manage the changes between the
+ original and Debianised source using <prgn>diff</prgn> and
+ <prgn>patch</prgn>. Turning the original source tree as
+ included in the <file>.orig.tar.gz</file> into the debianised
+ source must not involve any changes which cannot be
+ handled by these tools. Problematic changes which cause
+ <prgn>dpkg-source</prgn> to halt with an error when
+ building the source package are:
+ <list compact="compact">
+ <item><p>Adding or removing symbolic links, sockets or pipes.</p>
+ </item>
+ <item><p>Changing the targets of symbolic links.</p>
+ </item>
+ <item><p>Creating directories, other than <file>debian</file>.</p>
+ </item>
+ <item><p>Changes to the contents of binary files.</p></item>
+ </list> Changes which cause <prgn>dpkg-source</prgn> to
+ print a warning but continue anyway are:
+ <list compact="compact">
+ <item>
+ <p>
+ Removing files, directories or symlinks.
+ <footnote>
+ Renaming a file is not treated specially - it is
+ seen as the removal of the old file (which
+ generates a warning, but is otherwise ignored),
+ and the creation of the new one.
+ </footnote>
+ </p>
+ </item>
+ <item>
+ <p>
+ Changed text files which are missing the usual final
+ newline (either in the original or the modified
+ source tree).
+ </p>
+ </item>
+ </list>
+ Changes which are not represented, but which are not detected by
+ <prgn>dpkg-source</prgn>, are:
+ <list compact="compact">
+ <item><p>Changing the permissions of files (other than
+ <file>debian/rules</file>) and directories.</p></item>
+ </list>
</p>
<p>
- Urgency keywords are not case-sensitive.</p>
+ The <file>debian</file> directory and <file>debian/rules</file>
+ are handled specially by <prgn>dpkg-source</prgn> - before
+ applying the changes it will create the <file>debian</file>
+ directory, and afterwards it will make
+ <file>debian/rules</file> world-exectuable.
+ </p>
</sect1>
+ </sect>
+ </appendix>
- <sect1 id="pkg-f-Date"><heading><tt>Date</tt>
- </heading>
-
- <p>
- In <tt>.changes</tt> files and parsed changelogs, this
- gives the date the package was built or last edited.</p>
- </sect1>
+ <appendix id="pkg-controlfields">
+ <heading>Control files and their fields (from old Packaging Manual)</heading>
- <sect1 id="pkg-f-Format"><heading><tt>Format</tt>
- </heading>
+ <p>
+ Many of the tools in the <prgn>dpkg</prgn> suite manipulate
+ data in a common format, known as control files. Binary and
+ source packages have control data as do the <file>.changes</file>
+ files which control the installation of uploaded files, and
+ <prgn>dpkg</prgn>'s internal databases are in a similar
+ format.
+ </p>
- <p>
- This field occurs in <file>.changes</file> files, and
- specifies a format revision for the file. The format
- described here is version <tt>1.5</tt>. The syntax of the
- format value is the same as that of a package version
- number except that no epoch or Debian revision is allowed
- - see <ref id="versions">.</p>
- </sect1>
+ <sect>
+ <heading>Syntax of control files</heading>
- <sect1 id="pkg-f-Changes"><heading><tt>Changes</tt>
- </heading>
+ <p>
+ See <ref id="controlsyntax">.
+ </p>
- <p>
- In a <file>.changes</file> file or parsed changelog this field
- contains the human-readable changes data, describing the
- differences between the last version and the current one.
- </p>
+ <p>
+ It is important to note that there are several fields which
+ are optional as far as <prgn>dpkg</prgn> and the related
+ tools are concerned, but which must appear in every Debian
+ package, or whose omission may cause problems.
+ </p>
+ </sect>
- <p>
- There should be nothing in this field before the first
- newline; all the subsequent lines must be indented by at
- least one space; blank lines must be represented by a line
- consiting only of a space and a full stop.
- </p>
+ <sect>
+ <heading>List of fields</heading>
- <p>
- Each version's change information should be preceded by a
- "title" line giving at least the version, distribution(s)
- and urgency, in a human-readable way.
- </p>
+ <p>
+ See <ref id="controlfieldslist">.
+ </p>
- <p>
- If data from several versions is being returned the entry
- for the most recent version should be returned first, and
- entries should be separated by the representation of a
- blank line (the "title" line may also be followed by the
- representation of blank line).</p>
- </sect1>
+ <p>
+ This section now contains only the fields that didn't belong
+ to the Policy manual.
+ </p>
- <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