<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>
- 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>
- <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>
licenses that we consider <em>free</em>.
</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
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>
+ </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,
- </item>
- <item>
+ </item>
+ <item>
there is an ethical conflict in their distribution or
use,
- </item>
- <item>
+ </item>
+ <item>
we would have to sign a license for them, or
- </item>
- <item>
+ </item>
+ <item>
their distribution would conflict with other project
policies.
- </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>
+ 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,
- </item>
- <item>
+ </item>
+ <item>
<em>section/subsection</em> if the package is in
the <em>contrib</em> or <em>non-free</em> section,
and
- </item>
- <item>
+ </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.
- </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>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>
- </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
</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>
- 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>
+ Every package must have a name that's unique within the Debian
+ archive.
+ </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>
- <heading>The package name</heading>
+ <p>
+ Format is described in <ref id="f-Package">.
+ </p>
+ </sect>
- <p>
- Every package must have a name that's unique within the Debian
- archive.</p>
+ <sect id="versions">
+ <heading>The version of a package</heading>
- <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>
+ <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 package name is part of the file name of the
- <tt>.deb</tt> file and is included in the control field
- information.
- </p>
- </sect1>
+ <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 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.
- </p>
+ <heading>Version numbers based on dates</heading>
<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.
+ In general, Debian packages should use the same version
+ numbers as the upstream sources.
</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>
+ 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>
- </sect1>
-
-
- <sect1>
- <heading>The description of a package</heading>
<p>
- Every Debian package must have an extended description
- stored in the appropriate field of the control record.</p>
+ 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 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).
+ 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>
- Please refer to <ref id="descriptions"> for more information.
+ 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>Dependencies</heading>
-
- <p>
- Every package must specify the dependency information
- about other packages that are required for the first to
- work correctly.</p>
-
- <p>
- For example, a dependency entry must be provided for any
- shared libraries required by a dynamically-linked executable
- binary in a package.</p>
+ <sect>
+ <heading>The maintainer of a package</heading>
- <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>
+ 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>
- 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>
+ 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>
- 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>
+ <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>
- <sect1 id="virtual_pkg">
- <heading>Virtual packages</heading>
+ <sect id="descriptions">
+ <heading>The description of a package</heading>
- <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>
+ 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>
- 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>
+ 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>
- The latest version of the authoritative list of virtual
- package names can be found in the <tt>debian-policy</tt> package.
- It's also available from the Debian web mirrors at
- <tt><url name="/doc/packaging-manuals/virtual-package-names-list.txt"
- id="http://www.debian.org/doc/packaging-manuals/virtual-package-names-list.txt"></tt>
- and from the Debian archive mirrors at
- <tt><url name="/doc/package-developer/virtual-package-names-list.txt"
- id="http://ftp.debian.org/debian/doc/package-developer/virtual-package-names-list.txt"></tt>.
- </p>
+ <p>
+ 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 procedure for updating the list is described in the preface
- to the list.
- </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>
- </sect1>
+ <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>
- <heading>Base system</heading>
+ <sect1 id="synopsis"><heading>The single line synopsis</heading>
<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>
+ The single line synopsis should be kept brief - certainly
+ under 80 characters.
+ </p>
<p>
- Most of these packages will have the priority value
- <tt>required</tt> or at least <tt>important</tt>, and many
- of them will be tagged <tt>essential</tt> (see below).</p>
-
+ 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>Essential packages</heading>
-
- <p>
- Some packages are tagged <tt>essential</tt>. (They have
- <tt>Essential: yes</tt> in their package control record.)
- This flag is used for packages that are <em>essential</em>
- for a system.</p>
+ <sect1 id="extendeddesc"><heading>The extended description</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.
+ 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>
- 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.
+ 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>
- 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.
+ 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>
+
</sect1>
- <sect1>
- <heading>Tasks</heading>
- <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>
- <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>
+ <sect>
+ <heading>Dependencies</heading>
- <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>
+ Every package must specify the dependency information
+ about other packages that are required for the first to
+ work correctly.
+ </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>
+ For example, a dependency entry must be provided for any
+ shared libraries required by a dynamically-linked executable
+ binary in a package.
+ </p>
- <sect1 id="maintscripts">
- <heading>Maintainer Scripts</heading>
+ <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 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>
+ 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>
- Errors which occur during the execution of an installation
- script must be checked and the installation must not
- continue after an error.
- </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>
- <p>
- Note that in general <ref id="scripts"> applies to package
- maintainer scripts, too.
- </p>
+ <p>
+ The format of the package interrelationship control fields is
+ described in <ref id="relationships">.
+ </p>
+ </sect>
- <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>
+ <sect id="virtual_pkg">
+ <heading>Virtual packages</heading>
- <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>
+ <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>
- <sect2 id="maintscriptprompt">
- <heading>Prompting in maintainer scripts</heading>
- <p>
- Package maintainer scripts may prompt the user if
- necessary. Prompting may be accomplished by
- hand<footnote>
- From the Jargon file: by hand 2. By extension,
- writing code which does something in an explicit or
- low-level way for which a presupplied library
- (<em>debconf, in this instance</em>) routine ought
- to have been available.
- </footnote> (but this is deprecated), or by communicating
- through a program which conforms to the Debian Configuration
- management specification, version 2 or higher, such as
- <prgn>debconf</prgn><footnote>
+ <p>
+ 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>
+
+ </sect>
+
+ <sect>
+ <heading>Base system</heading>
+
+ <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>
+ 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>
+ 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>
+
+ <sect>
+ <heading>Tasks</heading>
+
+ <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>
+
+ <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>
+ 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>
+ 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>
+
+ <sect id="maintscripts">
+ <heading>Maintainer Scripts</heading>
+
+ <p>
+ The package installation scripts should avoid producing
+ output which it is unnecessary for the user to see and
+ 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>
+ 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>
+ Package maintainer scripts may prompt the user if
+ necessary. Prompting may be accomplished by hand<footnote>
+ From the Jargon file: by hand 2. By extension,
+ writing code which does something in an explicit or
+ low-level way for which a presupplied library
+ (<em>debconf, in this instance</em>) routine ought
+ to have been available.
+ </footnote>
+ (but this is deprecated), or by communicating through a program
+ which conforms to the Debian Configuration management
+ specification, version 2 or higher, such as
+ <prgn>debconf</prgn><footnote>
<p>
6% of Debian packages [see <url
- id="http://auric.debian.org/%7Ejoeyh/debconf-stats/data/"
+ id="http://ftp-master.debian.org/~joeyh/debconf-stats/"
name="Debconf stats">] currently use
<package>debconf</package> to prompt the user at
install time, and this number is growing daily. The
finally come to reflect the use of these things in
policy.
</p>
- </footnote>.
- </p>
+ </footnote>.
+ </p>
- The Debian Configuration management specification is included
- in the <file>debconf_specification</file> files in the
-
<package>debian-policy</package> package.
- It is also available from the Debian web mirrors at
- <tt><url name="/doc/packaging-manuals/debconf_specification.html"
+ <p>
+ The Debian Configuration management specification is included
+ in the <file>debconf_specification</file> files in the
+ <package>debian-policy</package> package.
+ It is also available from the Debian web mirrors at
+ <tt><url name="/doc/packaging-manuals/debconf_specification.html"
id="http://www.debian.org/doc/packaging-manuals/debconf_specification.html"></tt>
- and from the Debian archive mirrors at
- <tt><url name="/doc/package-developer/debconf_specification.txt.gz"
+ and from the Debian archive mirrors at
+ <tt><url name="/doc/package-developer/debconf_specification.txt.gz"
id="http://ftp.debian.org/debian/doc/package-developer/debconf_specification.txt.gz"></tt>.
- </p>
+ </p>
- Packages which use the Debian Configuration management
- specification may contain an additional
-
<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>
+ 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>
<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.
- </footnote>
- </p>
+ </footnote>
+ </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>
+ 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>
+ 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>
+ 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>
+ <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>
+ </chapt>
- <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;.
- </p>
+ <chapt id="source">
+ <heading>Source packages</heading>
- <p>
- This information may be used to file bug reports
- automatically if your package becomes too much out of
- date.
- </p>
+ <sect id="standardsversion">
+ <heading>Standards conformance</heading>
- <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>
+ 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>
- 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>
+ <p>
+ This information may be used to file bug reports
+ automatically if your package becomes too much out of date.
+ </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>
+ 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>
- </sect1>
+ </footnote>
+ </p>
+ </sect>
- <sect1 id="pkg-relations">
- <heading>Package relationships</heading>
+ <sect id="pkg-relations">
+ <heading>Package relationships</heading>
- 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>
+ 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>
- 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:
+ <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
the policy management process in the BTS.
</item>
</list>
- </footnote>
- </p>
+ </footnote>
+ </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>
+ 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.
- </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>
-
- <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>
- You should make sure that the <prgn>configure</prgn> utility
- detects the correct architecture specification string
- (refer to <ref id="arch-spec"> for details).</p>
-
- <p>
- If you need to edit a <prgn>Makefile</prgn> where
- GNU-style <prgn>configure</prgn> scripts are used, you
- 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>
- 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>
+ </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>
- <sect1>
- <heading>Error trapping in makefiles</heading>
+ <p>
+ <ref id="relationships"> explains the technical details.
+ </p>
+ </sect>
- <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>
+ <sect>
+ <heading>Changes to the upstream sources</heading>
- <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>
+ <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>Obsolete constructs and libraries</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>
- <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>
+ 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>
- Debian packages should be patched to use
- <tt><stdarg.h></tt> and <tt>ncurses</tt>
- instead.
- </p>
- </sect1>
</sect>
- </chapt>
- <chapt id="controlfields"><heading>Control files and their fields</heading>
+ <sect id="dpkgchangelog">
+ <heading>Debian changelog: <file>debian/changelog</file></heading>
- <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>
+ <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>
- <sect id="controlsyntax"><heading>Syntax of control files</heading>
+ <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>
- A control file consists of one or more paragraphs of fields.
- The paragraphs are separated by blank lines. Some control
- files allow only one paragraph; others allow several, in
- which case each paragraph usually refers to a different
- package. (For example, in source packages, the first
- paragraph refers to the source package, and later paragraphs
- refer to binary packages generated from the source.)
+ <p>
+ 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>
<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>.
+ 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>
+ <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>
<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.
+ <var>package</var> and <var>version</var> are the source
+ package name and version number.
</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.
+ <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>
- Field names are not case-sensitive, but it is usual to
- capitalize the field names using mixed case as shown below.
+ <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>
- 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 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>
- </sect>
-
- <sect><heading>List of fields</heading>
<p>
- This list here is not supposed to be exhaustive. Most fields
- are dealt with elsewhere in this document.
+ 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>
- <sect1 id="f-Package"><heading><tt>Package</tt>
- </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>).
- </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>
- </sect1>
+ <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 (see <ref id="f-Changed-By">),
+ and then later used to send an acknowledgement when the
+ upload has been installed.
+ </p>
- <sect1 id="f-Version"><heading><tt>Version</tt>
- </heading>
+ <p>
+ 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>
- <p>
- This lists the source or binary package's version number -
- see <ref id="versions">.
- </p>
+ <p>
+ The first "title" line with the package name should start
+ at the left hand margin; the "trailer" line with the
+ maintainer and date details should be preceded by exactly
+ one space. The maintainer details and the date must be
+ separated by exactly two spaces.
+ </p>
- </sect1>
+ <p>
+ For more information on placement of the changelog files
+ within binary packages, please see <ref id="changelogs">.
+ </p>
- <sect1
- id="f-Standards-Version"><heading><tt>Standards-Version</tt>
- </heading>
+ <sect1><heading>Alternative changelog formats</heading>
<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">.
+ 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>
+ 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>
-
-
- <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>
- 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>
-
- <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>
-
- <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>
-
- <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>
-
- <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>
-
- You should list <em>all</em> distributions that the
- package should be installed into.
- </footnote>
+ 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.
</p>
</sect1>
-
</sect>
- </chapt>
-
-
- <chapt id="versions"><heading>Version numbering</heading>
+ <sect>
+ <heading>Error trapping in makefiles</heading>
- <p>
- Every package has a version number recorded in its
- <tt>Version</tt> control file field.
- </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>
- <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>
+ 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>
- <p>
- The version number format is:
- [<var>epoch</var><tt>:</tt>]<var>upstream_version</var>[<tt>-</tt><var>debian_revision</var>]
- </p>
+ <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 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>
+ <sect id="restrictions">
+ <heading>Restrictions on objects in source packages</heading>
+ <p>
+ The source package may not contain any hard links<footnote>
<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.
+ This is not currently detected when building source
+ packages, but only when extracting
+ them.
</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.
+ 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>
- <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>
+ <sect>
+ <heading>Obsolete constructs and libraries</heading>
- <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>
+ <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>
- <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>
+ Debian packages should be patched to use
+ <tt><stdarg.h></tt> and <tt>ncurses</tt>
+ instead.
+ </p>
+ </sect>
- <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>
+ <sect id="debianrules">
+ <heading>Main building script: <file>debian/rules</file></heading>
- <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>
- 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>
-
- <sect id="debianrules"><heading><file>debian/rules</file> - the
- main building script</heading>
-
- <p>
- This file must be an executable makefile, and contains the
- package-specific recipes for compiling the package and
- building binary package(s) from the source.
- </p>
+ <p>
+ This file must be an executable makefile, and contains the
+ package-specific recipes for compiling the package and
+ building binary package(s) from the source.
+ </p>
<p>
It must start with the line <tt>#!/usr/bin/make -f</tt>,
</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
</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 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>
+ 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>
</sect>
- <sect id="dpkgchangelog"><heading><file>debian/changelog</file>
- </heading>
-
- <p>
- This file records the changes to the Debian-specific parts of the
- package<footnote>
- 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.
- </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 compact="compact">
-<var>package</var> (<var>version</var>) <var>distribution(s)</var>; urgency=<var>urgency</var>
- <comment>
- <p>[optional blank line(s), stripped]</p>
- </comment>
- * <var>change details</var>
- <var>more change details</var>
- <comment>
- <p>[blank line(s), included in output of dpkg-parsechangelog]</p>
- </comment>
- * <var>even more change details</var>
- <comment>
- <p>[optional blank line(s), stripped]</p>
- </comment>
- -- <var>maintainer name</var> <<var>email
- address</var>><var>[two spaces]</var> <var>date</var>
- </example>
- </p>
-
- <p>
- <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
- <file>.changes</file> file. See <ref id="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. 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>
- 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>
- 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>
- </p>
-
- <p>
- The maintainer name and email address used in the changelog
- should be the details of the person uploading <em>this</em>
- version. They are <em>not</em> necessarily those of the
- usual package maintainer. The information here will be
- copied to the <tt>Changed-By</tt> field in the
- <tt>.changes</tt> file, and then later used to send an
- acknowledgement when the upload has been installed.
- </p>
-
- <p>
- 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>
-
- <p>
- The first "title" line with the package name should start
- at the left hand margin; the "trailer" line with the
- maintainer and date details should be preceded by exactly
- one space. The maintainer details and the date must be
- separated by exactly two spaces.
- </p>
-
- <sect1><heading>Defining alternative changelog formats</heading>
-
- <p>
- 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>
+<!-- FIXME: section pkg-srcsubstvars is the same as substvars -->
+ <sect id="substvars">
+ <heading>Variable substitutions: <file>debian/substvars</file></heading>
<p>
When <prgn>dpkg-gencontrol</prgn>,
format of <file>debian/substvars</file>.</p>
</sect>
- <sect id="debianfiles"><heading><file>debian/files</file>
- </heading>
+ <sect id="debianfiles">
+ <heading>Generated files list: <file>debian/files</file></heading>
<p>
This file is not a permanent part of the source tree; it
the file to the list in <file>debian/files</file>.</p>
</sect>
- <sect id="restrictions"><heading>Restrictions on objects in source packages
- </heading>
+ </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>
- 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>
+ 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>
- </sect>
- <sect id="descriptions"><heading>Descriptions of packages - the
- <tt>Description</tt> field</heading>
+ <p>
+ Each paragraph consists of a series of data fields; each
+ field consists of the field name, followed by a colon and
+ then the data/value associated with that field. It ends at
+ the end of the line. Horizontal whitespace (spaces and
+ tabs) may occur immediately before or after the value and is
+ ignored there; it is conventional to put a single space
+ after the colon. For example, a field might be:
+ <example compact="compact">
+Package: libc6
+ </example>
+ the field name is <tt>Package</tt> and the field value
+ <tt>libc6</tt>.
+ </p>
<p>
- 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:
+ 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><example>
- Description: <single line synopsis>
- <extended description over several lines>
-</example></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.
+ </p>
<p>
- The description is intended to describe the program to a user
- who has never met it before so that they know whether they
- want to install it. It should also give information about the
- significant dependencies and conflicts between this package
- and others, so that the user knows why these dependencies and
- conflicts have been declared.
+ Field names are not case-sensitive, but it is usual to
+ capitalize the field names using mixed case as shown below.
</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.
+ 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>
- <sect1 id="synopsis"><heading>The single line synopsis</heading>
+ </sect>
- <p>
- The single line synopsis should be kept brief - certainly
- under 80 characters.
- </p>
+ <sect id="sourcecontrolfiles">
+ <heading>Source package control files -- <file>debian/control</file></heading>
- <p>
- Do not include the package name in the synopsis line. The
- display software knows how to display this already, and you
- do not need to state it. Remember that in many situations
- the user may only see the synopsis line - make it as
- informative as you can.
- </p>
-
- </sect1>
-
- <sect1 id="extendeddesc"><heading>The extended description</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.
- </p>
-
- <p>
- The extended description should describe what the package
- does and how it relates to the rest of the system (in terms
- of, for example, which subsystem it is which part of).
- </p>
-
- <p>
- 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>
- 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
- displayed verbatim. If the display cannot be panned
- horizontally, the displaying program will linewrap them "hard"
- (i.e., without taking account of word breaks). If it can they
- will be allowed to trail off to the right. None, one or two
- initial spaces may be deleted, but the number of spaces
- deleted from each line will be the same (so that you can have
- indenting work correctly, for example).
- </item>
-
- <item>
- 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.
- 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.
- </footnote>.
- </item>
-
- <item>
- Those containing a space, a full stop and some more characters.
- These are for future expansion. Do not use them.
- </item>
-
- </list></p>
-
- <p>
- Do not use tab characters. Their effect is not predictable.
- </p>
-
- </sect1>
-
- </sect>
-
- </chapt>
-
-
- <chapt id="maintainerscripts"><heading>Package maintainer scripts
- and installation procedure
- </heading>
-
- <sect><heading>Introduction to package maintainer scripts
- </heading>
+ <p>
+ 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>
- 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.
+ 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>
- 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.
+ The fields in the general paragraph (the first one, for the source
+ package) are:
+
+ <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>
- 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.
+ 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>
- 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.
+ The syntax and semantics of the fields are described below.
</p>
+<!-- stuff -->
+
<p>
- Broadly speaking the <prgn>preinst</prgn> is called before
- (a particular version of) a package is installed, and the
- <prgn>postinst</prgn> afterwards; the <prgn>prerm</prgn>
- before (a version of) a package is removed and the
- <prgn>postrm</prgn> afterwards.
+ 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>
- Programs called from maintainer scripts should not normally
- have a path prepended to them. Before installation is
- started, the package management system checks to see if the
- programs <prgn>ldconfig</prgn>,
- <prgn>start-stop-daemon</prgn>, <prgn>install-info</prgn>,
- and <prgn>update-rc.d</prgn> can be found via the
- <tt>PATH</tt> environment variable. Those programs, and any
- other program that one would expect to be on the
- <tt>PATH</tt>, should thus be invoked without an absolute
- pathname. Maintainer scripts should also not reset the
- <tt>PATH</tt>, though they might choose to modify it by
- prepending or appending package-specific directories. These
- considerations really apply to all shell scripts.</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>
- <heading>Maintainer scripts Idempotency</heading>
+ <sect id="binarycontrolfiles">
+ <heading>Binary package control files -- <file>DEBIAN/control</file></heading>
<p>
- It is necessary for the error recovery procedures that the
- scripts be idempotent. This means that if it is run
- successfully, and then it is called again, it doesn't bomb
- out or cause any harm, but just ensures that everything is
- the way it ought to be. If the first call failed, or
- aborted half way through for some reason, the second call
- should merely do the things that were left undone the first
- time, if any, and exit with a success status if everything
- is OK.<footnote>
- 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.
- </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>
- <heading>Controlling terminal for maintainer scripts</heading>
+ <sect id="debiansourcecontrolfiles">
+ <heading>Debian source control files -- <tt>.dsc</tt></heading>
<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.
+ 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>
- Each script should return a zero exit status for
- success, or a nonzero one for failure.
+ 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 (see).
</p>
+
</sect>
- <sect id="mscriptsinstact"><heading>Summary of ways maintainer
- scripts are called
- </heading>
+ <sect id="debianchangesfiles">
+ <heading>Debian changes files -- <file>.changes</file></heading>
<p>
- <list compact="compact">
- <item>
- <var>new-preinst</var> <tt>install</tt>
- </item>
- <item>
- <var>new-preinst</var> <tt>install</tt> <var>old-version</var>
- </item>
- <item>
- <var>new-preinst</var> <tt>upgrade</tt> <var>old-version</var>
- </item>
- <item>
- <var>old-preinst</var> <tt>abort-upgrade</tt>
- <var>new-version</var>
- </item>
- </list>
+ 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>
- <list compact="compact">
- <item>
- <var>postinst</var> <tt>configure</tt>
- <var>most-recently-configured-version</var>
- </item>
- <item>
- <var>old-postinst</var> <tt>abort-upgrade</tt>
- <var>new-version</var>
- </item>
- <item>
- <var>conflictor's-postinst</var> <tt>abort-remove</tt>
- <tt>in-favour</tt> <var>package</var>
- <var>new-version</var>
- </item>
- <item>
- <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>
- </item>
- </list>
+ The fields in this file are:
- <p>
<list compact="compact">
- <item>
- <var>prerm</var> <tt>remove</tt>
- </item>
- <item>
- <var>old-prerm</var> <tt>upgrade</tt>
- <var>new-version</var>
- </item>
- <item>
- <var>new-prerm</var> <tt>failed-upgrade</tt>
- <var>old-version</var>
- </item>
- <item>
- <var>conflictor's-prerm</var> <tt>remove</tt>
- <tt>in-favour</tt> <var>package</var>
- <var>new-version</var>
- </item>
- <item>
- <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>
- </item>
+ <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>
- <p>
- <list compact="compact">
- <item>
- <var>postrm</var> <tt>remove</tt>
- </item>
- <item>
- <var>postrm</var> <tt>purge</tt>
- </item>
- <item>
- <var>old-postrm</var> <tt>upgrade</tt>
- <var>new-version</var>
- </item>
- <item>
- <var>new-postrm</var> <tt>failed-upgrade</tt>
- <var>old-version</var>
- </item>
- <item>
- <var>new-postrm</var> <tt>abort-install</tt>
- </item>
- <item>
- <var>new-postrm</var> <tt>abort-install</tt>
- <var>old-version</var>
- </item>
- <item>
- <var>new-postrm</var> <tt>abort-upgrade</tt>
- <var>old-version</var>
- </item>
- <item>
- <var>disappearer's-postrm</var> <tt>disappear</tt>
- <var>overwriter</var>
- <var>overwriter-version</var>
- </item>
- </list>
- </p>
-
+ <sect id="controlfieldslist">
+ <heading>List of fields</heading>
- <sect id="unpackphase">
- <heading>Details of unpack phase of installation or upgrade</heading>
+ <sect1 id="f-Source">
+ <heading><tt>Source</tt></heading>
- <p>
- The procedure on installation/upgrade/overwrite/disappear
- (i.e., when running <tt>dpkg --unpack</tt>, or the unpack
- stage of <tt>dpkg --install</tt>) is as follows. In each
- case, if a major error occurs (unless listed below) the
- actions are, in general, run backwards - this means that the
- maintainer scripts are run with different arguments in
- reverse order. These are the "error unwind" calls listed
- below.
+ <p>
+ This field identifies the source package name.
+ </p>
- <enumlist>
- <item>
- <enumlist>
- <item>
- If a version of the package is already installed, call
- <example compact="compact">
-<var>old-prerm</var> upgrade <var>new-version</var>
- </example>
- </item>
- <item>
- If the script runs but exits with a non-zero
- exit status, <prgn>dpkg</prgn> will attempt:
- <example compact="compact">
-<var>new-prerm</var> failed-upgrade <var>old-version</var>
- </example>
- Error unwind, for both the above cases:
- <example compact="compact">
-<var>old-postinst</var> abort-upgrade <var>new-version</var>
- </example>
- </item>
- </enumlist>
- </item>
+ <p>
+ 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>
- <item>
- If a "conflicting" package is being removed at the same time:
- <enumlist>
- <item>
- If any packages depended on that conflicting
- package and <tt>--auto-deconfigure</tt> is
- specified, call, for each such package:
- <example compact="compact">
-<var>deconfigured's-prerm</var> deconfigure \
- in-favour <var>package-being-installed</var> <var>version</var> \
- removing <var>conflicting-package</var> <var>version</var>
- </example>
- Error unwind:
- <example compact="compact">
-<var>deconfigured's-postinst</var> abort-deconfigure \
- in-favour <var>package-being-installed-but-failed</var> <var>version</var> \
- removing <var>conflicting-package</var> <var>version</var>
- </example>
- The deconfigured packages are marked as
- requiring configuration, so that if
- <tt>--install</tt> is used they will be
- configured again if possible.
- </item>
- <item>
- 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>
- </example>
- Error unwind:
- <example compact="compact">
-<var>conflictor's-postinst</var> abort-remove \
- in-favour <var>package</var> <var>new-version</var>
- </example>
- </item>
- </enumlist>
- </item>
+ <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>
- <item>
- <enumlist>
- <item>
- If the package is being upgraded, call:
- <example compact="compact">
-<var>new-preinst</var> upgrade <var>old-version</var>
- </example>
- </item>
- <item>
- Otherwise, if the package had some configuration
- files from a previous version installed (i.e., it
- is in the "configuration files only" state):
- <example compact="compact">
-<var>new-preinst</var> install <var>old-version</var>
- </example>
- </item>
- <item>
- Otherwise (i.e., the package was completely purged):
- <example compact="compact">
-<var>new-preinst</var> install
- </example>
- Error unwind actions, respectively:
- <example compact="compact">
-<var>new-postrm</var> abort-upgrade <var>old-version</var>
-<var>new-postrm</var> abort-install <var>old-version</var>
-<var>new-postrm</var> abort-install
- </example>
- </item>
- </enumlist>
- </item>
+ <sect1 id="f-Maintainer">
+ <heading><tt>Maintainer</tt></heading>
- <item>
- <p>
- The new package's files are unpacked, overwriting any
- that may be on the system already, for example any
- from the old version of the same package or from
- another package. Backups of the old files are kept
- temporarily, and if anything goes wrong the package
- management system will attempt to put them back as
- part of the error unwind.
- </p>
+ <p>
+ The package maintainer's name and email address. The name
+ should come first, then the email address inside angle
+ brackets <tt><></tt> (in RFC822 format).
+ </p>
- <p>
- 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">).
- <!--
- The following paragraph is not currently the case:
- Currently the <tt>- - force-overwrite</tt> flag is
- enabled, downgrading it to a warning, but this may not
- always be the case.
- -->
- </p>
+ <p>
+ 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>
- <p>
- It is a more serious error for a package to contain a
- plain file or other kind of non-directory where another
- package has a directory (again, unless
- <tt>Replaces</tt> is used). This error can be
- overridden if desired using
- <tt>--force-overwrite-dir</tt>, but this is not
- advisable.
- </p>
+ <sect1 id="f-Changed-By">
+ <heading><tt>Changed-By</tt></heading>
- <p>
- Packages which overwrite each other's files produce
- behavior which, though deterministic, is hard for the
- system administrator to understand. It can easily
- lead to "missing" programs if, for example, a package
- is installed which overwrites a file from another
- package, and is then removed again.<footnote>
- Part of the problem is due to what is arguably a
- bug in <prgn>dpkg</prgn>.
- </footnote>
- </p>
+ <p>
+ 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>
- <p>
- A directory will never be replaced by a symbolic link
- to a directory or vice versa; instead, the existing
- state (symlink or not) will be left alone and
- <prgn>dpkg</prgn> will follow the symlink if there is
- one.
- </p>
- </item>
+ <sect1 id="f-Section">
+ <heading><tt>Section</tt></heading>
- <item>
- <p>
- <enumlist>
- <item>
- If the package is being upgraded, call
- <example compact="compact">
-<var>old-postrm</var> upgrade <var>new-version</var>
- </example>
- </item>
- <item>
- If this fails, <prgn>dpkg</prgn> will attempt:
- <example compact="compact">
-<var>new-postrm</var> failed-upgrade <var>old-version</var>
- </example>
- Error unwind, for both cases:
- <example compact="compact">
-<var>old-preinst</var> abort-upgrade <var>new-version</var>
- </example>
- </item>
- </enumlist>
- </p>
+ <p>
+ This field specifies an application area into which the package
+ has been classified. See <ref id="subsections">.
+ </p>
- <p>
- This is the point of no return - if
- <prgn>dpkg</prgn> gets this far, it won't back off
- past this point if an error occurs. This will
- leave the package in a fairly bad state, which
- will require a successful re-installation to clear
- up, but it's when <prgn>dpkg</prgn> starts doing
- things that are irreversible.
- </p>
- </item>
+ <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>
- Any files which were in the old version of the package
- but not in the new are removed.
- </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>
- <item>
- The new file list replaces the old.
- </item>
+ <sect1 id="f-Priority">
+ <heading><tt>Priority</tt></heading>
- <item>
- The new maintainer scripts replace the old.
- </item>
+ <p>
+ This field represents how important that it is that the user
+ have the package installed. See <ref id="priorities">.
+ </p>
- <item>
- 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>
- <prgn>dpkg</prgn> calls:
- <example compact="compact">
-<var>disappearer's-postrm</var> disappear \
- <var>overwriter</var> <var>overwriter-version</var>
- </example>
- </item>
- <item>
- The package's maintainer scripts are removed.
- </item>
- <item>
- 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
- removed by <prgn>dpkg</prgn>). Note that
- disappearing packages do not have their prerm
- called, because <prgn>dpkg</prgn> doesn't know
- in advance that the package is going to
- vanish.
- </item>
- </enumlist>
- </item>
+ <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>
- 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.)
- </item>
+ <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>
- <item>
- The backup files made during installation, above, are
- deleted.
- </item>
+ <sect1 id="f-Package">
+ <heading><tt>Package</tt></heading>
- <item>
- <p>
- The new package's status is now sane, and recorded as
- "unpacked".
- </p>
+ <p>
+ The name of the binary package.
+ </p>
- <p>
- Here is another point of no return - if the
- conflicting package's removal fails we do not unwind
- the rest of the installation; the conflicting package
- is left in a half-removed limbo.
- </p>
- </item>
+ <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>
- <item>
- 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).
- </item>
- </enumlist>
- </p>
- </sect>
+ <sect1 id="f-Architecture">
+ <heading><tt>Architecture</tt></heading>
- <sect id="configdetails"><heading>Details of configuration</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>
- When we configure a package (this happens with <tt>dpkg
- --install</tt> and <tt>dpkg --configure</tt>), we first
- update any <tt>conffile</tt>s and then call:
- <example compact="compact">
-<var>postinst</var> configure <var>most-recently-configured-version</var>
- </example>
- </p>
+ <p>
+ 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>
- No attempt is made to unwind after errors during
- configuration.
- </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>
- 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.
- </p>
- </sect>
+ <p>
+ See <ref id="pkg-debianrules"> for information how to get the
+ architecture for the build process.
+ </p>
+ </sect1>
- <sect id="removedetails"><heading>Details of removal and/or
- configuration purging</heading>
+ <sect1 id="f-Essential">
+ <heading><tt>Essential</tt></heading>
- <p>
- <enumlist>
- <item>
- <example compact="compact">
-<var>prerm</var> remove
- </example>
- </item>
- <item>
- The package's files are removed (except <tt>conffile</tt>s).
- </item>
- <item>
- <example compact="compact">
-<var>postrm</var> remove
- </example>
- </item>
- <item>
- <p>
- All the maintainer scripts except the <prgn>postrm</prgn>
- are removed.
- </p>
+ <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 we aren't purging the package we stop here. Note
- that packages which have no <prgn>postrm</prgn> and no
- <tt>conffile</tt>s are automatically purged when
- removed, as there is no difference except for the
- <prgn>dpkg</prgn> status.
- </p>
- </item>
- <item>
- 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.
- </item>
- <item>
- <example compact="compact">
-<var>postrm</var> purge
- </example>
- </item>
- <item>
- The package's file list is removed.
- </item>
- </enumlist>
+ <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>
- No attempt is made to unwind after errors during
- removal.
- </p>
- </sect>
- </chapt>
+ <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>
- <chapt id="relationships">
- <heading>Declaring relationships between packages</heading>
+ <sect1 id="f-Standards-Version">
+ <heading><tt>Standards-Version</tt></heading>
- <sect id="depsyntax">
- <heading>Syntax of relationship fields</heading>
+ <p>
+ The most recent version of the standards (the policy
+ manual and associated texts) with which the package
+ complies.
+ </p>
- <p>
- These fields all have a uniform syntax. They are a list of
- package names separated by commas.
- </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>
- In the <tt>Depends</tt>, <tt>Recommends</tt>,
- <tt>Suggests</tt>, <tt>Pre-Depends</tt>,
- <tt>Build-Depends</tt> and <tt>Build-Depends-Indep</tt>
- control file fields of the package, which declare
- dependencies on other packages, the package names listed may
- also include lists of alternative package names, separated
- by vertical bar (pipe) symbols <tt>|</tt>. In such a case,
- if any one of the alternative packages is installed, that
- part of the dependency is considered to be satisfied.
- </p>
+ <p>
+ 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>
- <p>
- All of the fields except for <tt>Provides</tt> may restrict
- their applicability to particular versions of each named
- package. This is done in parentheses after each individual
- package name; the parentheses should contain a relation from
- the list below followed by a version number, in the format
- described in <ref id="versions">.
- </p>
+ </sect1>
- <p>
- The relations allowed are <tt><<</tt>, <tt><=</tt>,
- <tt>=</tt>, <tt>>=</tt> and <tt>>></tt> for
- strictly earlier, earlier or equal, exactly equal, later or
- equal and strictly later, respectively. The deprecated
- forms <tt><</tt> and <tt>></tt> were used to mean
- earlier/later or equal, rather than strictly earlier/later,
- so they should not appear in new packages (though
- <prgn>dpkg</prgn> still supports them).
- </p>
+ <sect1 id="f-Version">
+ <heading><tt>Version</tt></heading>
- <p>
- Whitespace may appear at any point in the version
- specification subject to the rules in <ref
- id="controlsyntax">, and must appear where it's necessary to
- disambiguate; it is not otherwise significant. For
- consistency and in case of future changes to
- <prgn>dpkg</prgn> it is recommended that a single space be
- used after a version relationship and before a version
- number; it is also conventional to put a single space after
- each comma, on either side of each vertical bar, and before
- each open parenthesis.
- </p>
+ <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>
- For example, a list of dependencies might appear as:
- <example compact="compact">
-Package: mutt
-Version: 1.3.17-1
-Depends: libc6 (>= 2.2.1), exim | mail-transport-agent
- </example>
- </p>
+ <p>
+ 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>
- <p>
- All fields that specify build-time relationships
- (<tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
- <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>)
- may be restricted to a certain set of architectures. This
- is indicated in brackets after each individual package name and
- the optional version specification. The brackets enclose a
- list of Debian architecture names separated by whitespace.
- Exclamation marks may be prepended to each of the names.
- (It is not permitted for some names to be prepended with
- exclamation marks and others not.) If the current Debian
- host architecture is not in this list and there are no
- exclamation marks in the list, or it is in the list with a
- prepended exclamation mark, the package name and the
- associated version specification are ignored completely for
- the purposes of defining the relationships.
- </p>
+ <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>
- <p>
- For example:
- <example compact="compact">
-Source: glibc
-Build-Depends-Indep: texinfo
-Build-Depends: kernel-headers-2.2.10 [!hurd-i386],
- hurd-dev [hurd-i386], gnumach-dev [hurd-i386]
- </example>
- </p>
+ <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>
- Note that the binary package relationship fields such as
- <tt>Depends</tt> appear in one of the binary package
- sections of the control file, whereas the build-time
- relationships such as <tt>Build-Depends</tt> appear in the
- source package section of the control file (which is the
- first section).
- </p>
- </sect>
+ <p>
+ The <var>upstream_version</var> and <var>debian_revision</var>
+ parts are compared by the package management system using the
+ same algorithm:
+ </p>
- <sect>
- <heading>Binary Dependencies - <tt>Depends</tt>,
- <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
- <tt>Pre-Depends</tt>
- </heading>
+ <p>
+ The strings are compared from left to right.
+ </p>
- <p>
- Packages can declare in their control file that they have
- certain relationships to other packages - for example, that
- they may not be installed at the same time as certain other
- 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
- <tt>Conflicts</tt> control file fields.
- </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>
- These six fields are used to declare a dependency
- relationship by one package on another. Except for
- <tt>Enhances</tt>, they appear in the depending (binary)
- package's control file. (<tt>Enhances</tt> appears in the
- recommending package's control file.)
- </p>
+ <p>
+ 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>
- A <tt>Depends</tt> field takes effect <em>only</em> when a
- package is to be configured. It does not prevent a package
- being on the system in an unconfigured state while its
- dependencies are unsatisfied, and it is possible to replace
- a package whose dependencies are satisfied and which is
- properly installed with a different version whose
- dependencies are not and cannot be satisfied; when this is
- done the depending package will be left unconfigured (since
- attempts to configure it will give errors) and will not
- function properly. If it is necessary, a
- <tt>Pre-Depends</tt> field can be used, which has a partial
- effect even when a package is being unpacked, as explained
- in detail below. (The other three dependency fields,
- <tt>Recommends</tt>, <tt>Suggests</tt> and
- <tt>Enhances</tt>, are only used by the various front-ends
- to <prgn>dpkg</prgn> such as <prgn>dselect</prgn>.)
- </p>
+ <p>
+ 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>
- For this reason packages in an installation run are usually
- all unpacked first and all configured later; this gives
- later versions of packages with dependencies on later
- versions of other packages the opportunity to have their
- dependencies satisfied.
- </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>
- <p>
- The <tt>Depends</tt> field thus allows package maintainers
- to impose an order in which packages should be configured.
- </p>
+ <sect1 id="f-Description">
+ <heading><tt>Description</tt></heading>
- <p>
- The meaning of the five dependency fields is as follows:
- <taglist>
- <tag><tt>Depends</tt></tag>
- <item>
- <p>
- This declares an absolute dependency. A package will
- not be configured unless all of the packages listed in
- its <tt>Depends</tt> field have been correctly
- configured.
- </p>
+ <p>
+ 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>
- The <tt>Depends</tt> field should be used if the
- depended-on package is required for the depending
- package to provide a significant amount of
- functionality.
- </p>
+ <p>
+<example>
+ Description: <single line synopsis>
+ <extended description over several lines>
+</example>
+ </p>
- <p>
- The <tt>Depends</tt> field should also be used if the
- <prgn>postinst</prgn>, <prgn>prerm</prgn> or
- <prgn>postrm</prgn> scripts require the package to be
- present in order to run. Note, however, that the
- <prgn>postrm</prgn> cannot rely on any non-essential
- packages to be present during the <tt>purge</tt>
- phase.
- </item>
+ <p>
+ The lines in the extended description can have these formats:
+ </p>
- <tag><tt>Recommends</tt></tag>
- <item>
- <p>
- This declares a strong, but not absolute, dependency.
- </p>
+ <p><list>
- <p>
- The <tt>Recommends</tt> field should list packages
- that would be found together with this one in all but
- unusual installations.
- </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>
- <tag><tt>Suggests</tt></tag>
<item>
- 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.
+ Those starting with two or more spaces. These will be
+ displayed verbatim. If the display cannot be panned
+ horizontally, the displaying program will linewrap them "hard"
+ (i.e., without taking account of word breaks). If it can they
+ will be allowed to trail off to the right. None, one or two
+ initial spaces may be deleted, but the number of spaces
+ deleted from each line will be the same (so that you can have
+ indenting work correctly, for example).
</item>
- <tag><tt>Enhances</tt></tag>
<item>
- 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.
+ 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.
+ 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.
+ </footnote>.
</item>
- <tag><tt>Pre-Depends</tt></tag>
<item>
- <p>
- This field is like <tt>Depends</tt>, except that it
- also forces <prgn>dpkg</prgn> to complete installation
- of the packages named before even starting the
- installation of the package which declares the
- pre-dependency, as follows:
- </p>
+ Those containing a space, a full stop and some more characters.
+ These are for future expansion. Do not use them.
+ </item>
- <p>
- When a package declaring a pre-dependency is about to
- be <em>unpacked</em> the pre-dependency can be
- satisfied if the depended-on package is either fully
- configured, <em>or even if</em> the depended-on
- package(s) are only unpacked or half-configured,
- provided that they have been configured correctly at
- some point in the past (and not removed or partially
- removed since). In this case, both the
- previously-configured and currently unpacked or
- half-configured versions must satisfy any version
- clause in the <tt>Pre-Depends</tt> field.
- </p>
+ </list></p>
- <p>
- When the package declaring a pre-dependency is about
- to be <em>configured</em>, the pre-dependency will be
- treated as a normal <tt>Depends</tt>, that is, it will
- be considered satisfied only if the depended-on
- package has been correctly configured.
- </p>
+ <p>
+ Do not use tab characters. Their effect is not predictable.
+ </p>
- <p>
- <tt>Pre-Depends</tt> should be used sparingly,
- preferably only by packages whose premature upgrade or
- installation would hamper the ability of the system to
- continue with any upgrade that might be in progress.
- </p>
+ <p>
+ See <ref id="descriptions"> for further information on this.
+ </p>
- <p>
- <tt>Pre-Depends</tt> are also required if the
- <prgn>preinst</prgn> script depends on the named
- package. It is best to avoid this situation if
- possible.
- </p>
- </item>
- </taglist>
- </p>
+ <p>
+ In a <file>.changes</file> file, the <tt>Description</tt> field
+ contains a summary of the descriptions for the packages being
+ uploaded.
+ </p>
- <p>
- When selecting which level of dependency to use you should
- consider how important the depended-on package is to the
- functionality of the one declaring the dependency. Some
- packages are composed of components of varying degrees of
- importance. Such a package should list using
- <tt>Depends</tt> the package(s) which are required by the
- more important components. The other components'
- requirements may be mentioned as Suggestions or
- Recommendations, as appropriate to the components' relative
- importance.
- </p>
- </sect>
+ <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>
- <sect id="conflicts">
- <heading>Conflicting binary packages - <tt>Conflicts</tt></heading>
+ </sect1>
- <p>
- When one binary package declares a conflict with another
- using a <tt>Conflicts</tt> field, <prgn>dpkg</prgn> will
- refuse to allow them to be installed on the system at the
- same time.
- </p>
+ <sect1 id="f-Distribution">
+ <heading><tt>Distribution</tt></heading>
- <p>
- If one package is to be installed, the other must be removed
- first - if the package being installed is marked as
- replacing (see <ref id="replaces">) the one on the system,
- or the one on the system is marked as deselected, or both
- packages are marked <tt>Essential</tt>, then
- <prgn>dpkg</prgn> will automatically remove the package
- which is causing the conflict, otherwise it will halt the
- installation of the new package with an error. This
- mechanism is specifically designed to produce an error when
- the installed package is <tt>Essential</tt>, but the new
- package is not.
- </p>
+ <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>
- A package will not cause a conflict merely because its
- configuration files are still installed; it must be at least
- half-installed.
- </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>
- A special exception is made for packages which declare a
- conflict with their own package name, or with a virtual
- package which they provide (see below): this does not
- prevent their installation, and allows a package to conflict
- with others providing a replacement for it. You use this
- feature when you want the package in question to be the only
- package providing some feature.
- </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>
- A <tt>Conflicts</tt> entry should almost never have an
- "earlier than" version clause. This would prevent
- <prgn>dpkg</prgn> from upgrading or installing the package
- which declared such a conflict until the upgrade or removal
- of the conflicted-with package had been completed.
- </p>
- </sect>
+ <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>
- <sect id="virtual"><heading>Virtual packages - <tt>Provides</tt>
- </heading>
+ <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>
- As well as the names of actual ("concrete") packages, the
- package relationship fields <tt>Depends</tt>,
- <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
- <tt>Pre-Depends</tt>, <tt>Conflicts</tt>,
- <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
- <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>
- may mention "virtual packages".
- </p>
+ <p>
+ You should list <em>all</em> distributions that the
+ package should be installed into.
+ </p>
- <p>
- A <em>virtual package</em> is one which appears in the
- <tt>Provides</tt> control file field of another package.
- The effect is as if the package(s) which provide a
- particular virtual package name had been listed by name
- everywhere the virtual package name appears. (See also <ref
- id="virtual_pkg">)
- </p>
+ <p>
+ More information is available in the Debian Developer's
+ Reference, section "The Debian archive".
+ </p>
+ </footnote>
+ </p>
+ </sect1>
- <p>
- If there are both concrete and virtual packages of the same
- name, then the dependency may be satisfied (or the conflict
- caused) by either the concrete package with the name in
- question or any other concrete package which provides the
- virtual package with the name in question. This is so that,
- for example, supposing we have
- <example compact="compact">
-Package: foo
-Depends: bar
- </example>
- and someone else releases an enhanced version of the
- <tt>bar</tt> package (for example, a non-US variant), they
- can say:
- <example compact="compact">
-Package: bar-plus
-Provides: bar
- </example>
- and the <tt>bar-plus</tt> package will now also satisfy the
- dependency for the <tt>foo</tt> package.
- </p>
+ <sect1 id="f-Date">
+ <heading><tt>Date</tt></heading>
- <p>
- If a dependency or a conflict has a version number attached
- then only real packages will be considered to see whether
- the relationship is satisfied (or the prohibition violated,
- for a conflict) - it is assumed that a real package which
- provides the virtual package is not of the "right" version.
- So, a <tt>Provides</tt> field may not contain version
- numbers, and the version number of the concrete package
- which provides a particular virtual package will not be
- looked at when considering a dependency on or conflict with
- the virtual package name.
- </p>
+ <p>
+ This field includes the date the package was built or last edited.
+ </p>
- <p>
- It is likely that the ability will be added in a future
- release of <prgn>dpkg</prgn> to specify a version number for
- each virtual package it provides. This feature is not yet
- present, however, and is expected to be used only
- infrequently.
- </p>
+ <p>
+ The value of this field is usually extracted from the
+ <file>debian/changelog</file> file - see
+ <ref id="dpkgchangelog">).
+ </p>
+ </sect1>
- <p>
- If you want to specify which of a set of real packages
- should be the default to satisfy a particular dependency on
- a virtual package, you should list the real package as an
- alternative before the virtual one.
- </p>
- </sect>
+ <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>
- <sect id="replaces"><heading>Overwriting files and replacing
- packages - <tt>Replaces</tt></heading>
+ <sect1 id="f-Urgency">
+ <heading><tt>Urgency</tt></heading>
- <p>
- Packages can declare in their control file that they should
- overwrite files in certain other packages, or completely
- replace other packages. The <tt>Replaces</tt> control file
- field has these two distinct purposes.
- </p>
+ <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:
- <sect1><heading>Overwriting files in other packages</heading>
+ <example>
+ Urgency: low (HIGH for users of diversions)
+ </example>
+
+ </p>
<p>
- Firstly, as mentioned before, it is usually an error for a
- package to contain files which are on the system in
- another package.
+ 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>
- However, if the overwriting package declares that it
- <tt>Replaces</tt> the one containing the file being
- overwritten, then <prgn>dpkg</prgn> will replace the file
- from the old package with that from the new. The file
- will no longer be listed as "owned" by the old package.
+ This field contains the human-readable changes data, describing
+ the differences between the last version and the current one.
</p>
<p>
- If a package is completely replaced in this way, so that
- <prgn>dpkg</prgn> does not know of any files it still
- contains, it is considered to have "disappeared". It will
- be marked as not wanted on the system (selected for
- removal) and not installed. Any <tt>conffile</tt>s
- details noted for the package will be ignored, as they
- will have been taken over by the overwriting package. The
- package's <prgn>postrm</prgn> script will be run with a
- special argument to allow the package to do any final
- cleanup required. See <ref id="mscriptsinstact">.
+ 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>
- 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.
+ The value of this field is usually extracted from the
+ <file>debian/changelog</file> file - see
+ <ref id="dpkgchangelog">).
</p>
<p>
- For this usage of <tt>Replaces</tt>, virtual packages (see
- <ref id="virtual">) are not considered when looking at a
- <tt>Replaces</tt> field - the packages declared as being
- replaced must be mentioned by their real names.
+ 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>
- Furthermore, this usage of <tt>Replaces</tt> only takes
- effect when both packages are at least partially on the
- system at once, so that it can only happen if they do not
- conflict or if the conflict has been overridden.
+ 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><heading>Replacing whole packages, forcing their
- removal</heading>
+ <sect1 id="f-Installed-Size">
+ <heading><tt>Installed-Size</tt></heading>
<p>
- Secondly, <tt>Replaces</tt> allows the packaging system to
- resolve which package should be removed when there is a
- conflict - see <ref id="conflicts">. This usage only
- takes effect when the two packages <em>do</em> conflict,
- so that the two usages of this field do not interfere with
- each other.
+ 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>
- In this situation, the package declared as being replaced
- can be a virtual package, so for example, all mail
- transport agents (MTAs) would have the following fields in
- their control files:
- <example compact="compact">
-Provides: mail-transport-agent
-Conflicts: mail-transport-agent
-Replaces: mail-transport-agent
- </example>
- ensuring that only one MTA can be installed at any one
- time.
+ 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>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>
+ <sect>
+ <heading>User-defined fields</heading>
<p>
- Source packages that require certain binary packages to be
- 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
- <tt>Build-Conflicts-Indep</tt> control file fields.
- </p>
-
- <p>
- Build-dependencies on "build-essential" binary packages can be
- omitted. Please see <ref id="pkg-relations"> for more information.
+ 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>
- The dependencies and conflicts they define must be satisfied
- (as defined earlier for binary packages) in order to invoke
- the targets in <tt>debian/rules</tt>, as follows:<footnote>
- <p>
- If you make "build-arch" or "binary-arch", you need
- Build-Depends. If you make "build-indep" or
- "binary-indep", you need Build-Depends and
- Build-Depends-Indep. If you make "build" or "binary",
- you need both.
- </p>
- <p>
- There is no Build-Depends-Arch; the autobuilders will
- only need the Build-Depends if they know how to build
- only build-arch and binary-arch. Anyone building the
- build-indep/binary-indep targets is basically assumed to
- be building the whole package and so installs all build
- dependencies.
- </p>
- <p>
- The purpose of the original split, I recall, was so that
- the autobuilders wouldn't need to install extra packages
- needed only for the binary-indep targets. But without a
- build-arch/build-indep split, this didn't work, since
- most of the work is done in the build target, not in the
- binary target.
- </p>
- </footnote>
+ If you wish to add additional unsupported fields to
+ these output files you should use the mechanism
+ described here.
+ </p>
- <taglist>
- <tag><tt>Build-Depends</tt>, <tt>Build-Conflicts</tt></tag>
- <item>
- 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>.
- </item>
- <tag><tt>Build-Depends-Indep</tt>,
- <tt>Build-Conflicts-Indep</tt></tag>
- <item>
- 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>.
- </item>
- </taglist>
+ <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="conffiles">
- <heading>Configuration file handling</heading>
+ <chapt id="maintainerscripts">
+ <heading>Package maintainer scripts and installation procedure</heading>
- <p>
- This chapter has been superseded by <ref id="config-files">.
- </p>
- </chapt>
+ <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>
- <chapt id="sharedlibs"><heading>Shared libraries</heading>
+ <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>
- Packages containing shared libraries must be constructed with
- a little care to make sure that the shared library is always
- available. This is especially important for packages whose
- shared libraries are vitally important, such as the C library
- (currently <tt>libc6</tt>).
- </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>
- Packages involving shared libraries should be split up into
- several binary packages. This section mostly deals with how
- this separation is to be accomplished; rules for files within
- the shared library packages are in <ref id="libraries"> instead.
- </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>
- <sect id="sharedlibs-runtime">
- <heading>Run-time shared libraries</heading>
+ <p>
+ Broadly speaking the <prgn>preinst</prgn> is called before
+ (a particular version of) a package is installed, and the
+ <prgn>postinst</prgn> afterwards; the <prgn>prerm</prgn>
+ before (a version of) a package is removed and the
+ <prgn>postrm</prgn> afterwards.
+ </p>
- <p>
- The run-time shared library needs to be placed in a package called
- <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>
- 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>.
- </footnote>.
- Alternatively, if it would be confusing to directly append
- <var>soversion</var> to <var>libraryname</var> (e.g. because
- <var>libraryname</var> itself ends in a number), you may use
- <package><var>libraryname</var>-<var>soversion</var></package> and
- <package><var>libraryname</var>-<var>soversion</var>-dev</package>
- instead.
- </p>
-
- <p>
- If you have several shared libraries built from the same
- source tree you may lump them all together into a single
- shared library package, provided that you change all of
- their sonames at once (so that you don't get filename
- clashes if you try to install different versions of the
- combined shared libraries package).
- </p>
-
- <p>
- 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
- renamed or re-linked by any <prgn>prerm</prgn> or
- <prgn>postrm</prgn> scripts; <prgn>dpkg</prgn> will take care
- of renaming things safely without affecting running programs,
- and attempts to interfere with this are likely to lead to
- problems.
- </p>
-
- <p>
- Shared libraries should not be installed executable, since
- the dynamic linker does not require this and trying to
- execute a shared library usually results in a core dump.
- </p>
-
- <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
- 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>
- 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
- <prgn>dpkg</prgn> comes to install the symlink
- (overwriting the previous symlink pointing at an older
- version of the library), the new shared library is already
- in place. In the past, this was achieved by creating the
- library in the temporary packaging directory before
- creating the symlink. Unfortunately, this was not always
- effective, since the building of the tar file in the
- <file>.deb</file> depended on the behavior of the underlying
- file system. Some file systems (such as reiserfs) reorder
- the files so that the order of creation is forgotten.
- Since version 1.7.0, <prgn>dpkg</prgn>
- 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.
- </footnote>
- </p>
+ <p>
+ Programs called from maintainer scripts should not normally
+ have a path prepended to them. Before installation is
+ started, the package management system checks to see if the
+ programs <prgn>ldconfig</prgn>,
+ <prgn>start-stop-daemon</prgn>, <prgn>install-info</prgn>,
+ and <prgn>update-rc.d</prgn> can be found via the
+ <tt>PATH</tt> environment variable. Those programs, and any
+ other program that one would expect to be on the
+ <tt>PATH</tt>, should thus be invoked without an absolute
+ pathname. Maintainer scripts should also not reset the
+ <tt>PATH</tt>, though they might choose to modify it by
+ prepending or appending package-specific directories. These
+ considerations really apply to all shell scripts.</p>
+ </sect>
- <sect1 id="ldconfig">
- <heading><tt>ldconfig</tt></heading>
+ <sect id="idempotency">
+ <heading>Maintainer scripts Idempotency</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>
- These are currently
- <list compact="compact">
- <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>
+ It is necessary for the error recovery procedures that the
+ scripts be idempotent. This means that if it is run
+ successfully, and then it is called again, it doesn't bomb
+ out or cause any harm, but just ensures that everything is
+ the way it ought to be. If the first call failed, or
+ aborted half way through for some reason, the second call
+ should merely do the things that were left undone the first
+ time, if any, and exit with a success status if everything
+ is OK.<footnote>
+ 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.
</footnote>
- must use <prgn>ldconfig</prgn> to update the shared library
- system.
</p>
+ </sect>
- <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>
+ <sect id="controllingterminal">
+ <heading>Controlling terminal for maintainer scripts</heading>
- 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>
+ 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>
- </sect1>
+ <p>
+ Each script should return a zero exit status for
+ success, or a nonzero one for failure.
+ </p>
</sect>
- <sect id="sharedlibs-runtime-progs">
- <heading>Run-time support programs</heading>
+ <sect id="mscriptsinstact"><heading>Summary of ways maintainer
+ scripts are called
+ </heading>
- <p>
- If your package has some run-time support programs which use
- the shared library you must not put them in the shared
- library package. If you do that then you won't be able to
- install several versions of the shared library without
- getting filename clashes.
- </p>
+ <p>
+ <list compact="compact">
+ <item>
+ <var>new-preinst</var> <tt>install</tt>
+ </item>
+ <item>
+ <var>new-preinst</var> <tt>install</tt> <var>old-version</var>
+ </item>
+ <item>
+ <var>new-preinst</var> <tt>upgrade</tt> <var>old-version</var>
+ </item>
+ <item>
+ <var>old-preinst</var> <tt>abort-upgrade</tt>
+ <var>new-version</var>
+ </item>
+ </list>
- <p>
- Instead, either create another package for the runtime binaries
- (this package might typically be named
- <package><var>libraryname</var>-runtime</package>; note the absence
- of the <var>soversion</var> in the package name), or if the
- development package is small, include them in there.
- </p>
- </sect>
-
- <sect id="sharedlibs-static">
- <heading>Static libraries</heading>
-
- <p>
- The static library (<file><var>libraryname.a</var></file>)
- is usually provided in addition to the shared version.
- It is placed into the development package (see below).
- </p>
-
- <p>
- In some cases, it is acceptable for a library to be
- available in static form only; these cases include:
- <list>
- <item>libraries for languages whose shared library support
- is immature or unstable</item>
- <item>libraries whose interfaces are in flux or under
- development (commonly the case when the library's
- major version number is zero, or where the ABI breaks
- across patchlevels)</item>
- <item>libraries which are explicitly intended to be
- available only in static form by their upstream
- author(s)</item>
- </list>
- </p>
-
- <sect id="sharedlibs-dev">
- <heading>Development files</heading>
-
- <p>
- The development files associated to a shared library need to be
- placed in a package called
- <package><var>libraryname</var><var>soversion</var>-dev</package>,
- or if you prefer only to support one development version at a
- time, <package><var>libraryname</var>-dev</package>.
- </p>
-
- <p>
- In case several development versions of a library exist, you may
- need to use <prgn>dpkg</prgn>'s Conflicts mechanism (see
- <ref id="conflicts">) to ensure that the user only installs one
- development version at a time (as different development versions are
- likely to have the same header files in them, which would cause a
- filename clash if both were installed).
- </p>
-
- <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
- from <file>/usr/lib/libgdbm.so</file> to
- <file>libgdbm.so.1.7.3</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>
- </sect>
-
- <sect id="sharedlibs-intradeps">
- <heading>Dependencies between the packages of the same library</heading>
-
- <p>
- 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>
- </sect>
-
- <sect id="sharedlibs-shlibdeps">
- <heading>Dependencies between the library and other packages -
- the <tt>shlibs</tt> system</heading>
-
- <p>
- If a package contains a binary or library which links to a
- shared library, we must ensure that when the package is
- installed on the system, all of the libraries needed are
- also installed. This requirement led to the creation of the
- <tt>shlibs</tt> system, which is very simple in its design:
- any package which <em>provides</em> a shared library also
- provides information on the package dependencies required to
- ensure the presence of this library, and any package which
- <em>uses</em> a shared library uses this information to
- determine the dependencies it requires. The files which
- contain the mapping from shared libraries to the necessary
- dependency information are called <file>shlibs</file> files.
- </p>
-
- <p>
- Thus, when a package is built which contains any shared
- libraries, it must provide a <file>shlibs</file> file for other
- packages to use, and when a package is built which contains
- any shared libraries or compiled binaries, it must run
- <prgn>dpkg-shlibdeps</prgn> on these to determine the
- libraries used and hence the dependencies needed by this
- package.<footnote>
- <p>
- In the past, the shared libraries linked to were
- determined by calling <prgn>ldd</prgn>, but now
- <prgn>objdump</prgn> is used to do this. The only
- change this makes to package building is that
- <prgn>dpkg-shlibdeps</prgn> must also be run on shared
- libraries, whereas in the past this was unnecessary.
- The rest of this footnote explains the advantage that
- this method gives.
- </p>
-
- <p>
- We say that a binary <tt>foo</tt> <em>directly</em> uses
- a library <tt>libbar</tt> if it is explicitly linked
- with that library (that is, it uses the flag
- <tt>-lbar</tt> during the linking stage). Other
- libraries that are needed by <tt>libbar</tt> are linked
- <em>indirectly</em> to <tt>foo</tt>, and the dynamic
- linker will load them automatically when it loads
- <tt>libbar</tt>. A package should depend on
- the libraries it directly uses, and the dependencies for
- those libraries should automatically pull in the other
- libraries.
- </p>
-
- <p>
- Unfortunately, the <prgn>ldd</prgn> program shows both
- the directly and indirectly used libraries, meaning that
- the dependencies determined included both direct and
- indirect dependencies. The use of <prgn>objdump</prgn>
- avoids this problem by determining only the directly
- used libraries.
- </p>
-
- <p>
- A good example of where this helps is the following. We
- could update <tt>libimlib</tt> with a new version that
- supports a new graphics format called dgf (but retaining
- the same major version number). If we used the old
- <prgn>ldd</prgn> method, every package that uses
- <tt>libimlib</tt> would need to be recompiled so it
- would also depend on <tt>libdgf</tt> or it wouldn't run
- due to missing symbols. However with the new system,
- packages using <tt>libimlib</tt> can rely on
- <tt>libimlib</tt> itself having the dependency on
- <tt>libdgf</tt> and so they would not need rebuilding.
- </p>
- </footnote>
- </p>
-
- <p>
- In the following sections, we will first describe where the
- various <tt>shlibs</tt> files are to be found, then how to
- use <prgn>dpkg-shlibdeps</prgn>, and finally the
- <tt>shlibs</tt> file format and how to create them if your
- package contains a shared library.
- </p>
-
- <sect1>
- <heading>The <tt>shlibs</tt> files present on the system</heading>
-
- <p>
- There are several places where <tt>shlibs</tt> files are
- found. The following list gives them in the order in which
- they are read by <prgn>dpkg-shlibdeps</prgn>. (The first
- one which gives the required information is used.)
- </p>
+ <p>
+ <list compact="compact">
+ <item>
+ <var>postinst</var> <tt>configure</tt>
+ <var>most-recently-configured-version</var>
+ </item>
+ <item>
+ <var>old-postinst</var> <tt>abort-upgrade</tt>
+ <var>new-version</var>
+ </item>
+ <item>
+ <var>conflictor's-postinst</var> <tt>abort-remove</tt>
+ <tt>in-favour</tt> <var>package</var>
+ <var>new-version</var>
+ </item>
+ <item>
+ <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>
+ </item>
+ </list>
<p>
- <list>
+ <list compact="compact">
<item>
- <p><file>debian/shlibs.local</file></p>
-
- <p>
- This lists overrides for this package. Its use is
- described below (see <ref id="shlibslocal">).
- </p>
+ <var>prerm</var> <tt>remove</tt>
</item>
-
<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
- administrator.
- </p>
+ <var>old-prerm</var> <tt>upgrade</tt>
+ <var>new-version</var>
</item>
-
<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
- control file area of the temporary build directory and
- given the name <file>shlibs</file>. These files give
- details of any shared libraries included in the
- package.<footnote>
- An example may help here. Let us say that the
- source package <tt>foo</tt> generates two binary
- packages, <tt>libfoo2</tt> and
- <tt>foo-runtime</tt>. When building the binary
- packages, the two packages are created in the
- directories <file>debian/libfoo2</file> and
- <file>debian/foo-runtime</file> respectively.
- (<file>debian/tmp</file> could be used instead of one
- of these.) Since <tt>libfoo2</tt> provides the
- <tt>libfoo</tt> shared library, it will require a
- <tt>shlibs</tt> file, which will be installed in
- <file>debian/libfoo2/DEBIAN/shlibs</file>, eventually
- to become
- <file>/var/lib/dpkg/info/libfoo2.shlibs</file>. Then
- when <prgn>dpkg-shlibdeps</prgn> is run on the
- executable
- <file>debian/foo-runtime/usr/bin/foo-prog</file>, it
- will examine the
- <file>debian/libfoo2/DEBIAN/shlibs</file> file to
- determine whether <tt>foo-prog</tt>'s library
- dependencies are satisfied by any of the libraries
- provided by <tt>libfoo2</tt>. For this reason,
- <prgn>dpkg-shlibdeps</prgn> must only be run once
- all of the individual binary packages'
- <tt>shlibs</tt> files have been installed into the
- build directory.
- </footnote>
- </p>
+ <var>new-prerm</var> <tt>failed-upgrade</tt>
+ <var>old-version</var>
</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
- maintained by the relevant package maintainers.
- </p>
+ <var>conflictor's-prerm</var> <tt>remove</tt>
+ <tt>in-favour</tt> <var>package</var>
+ <var>new-version</var>
</item>
-
<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.
- It was used when the <file>shlibs</file> setup was first
- introduced, but it is now normally empty. It is
- maintained by the <tt>dpkg</tt> maintainer.
- </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>
</item>
</list>
- </p>
- </sect1>
-
- <sect1>
- <heading>How to use <prgn>dpkg-shlibdeps</prgn> and the
- <file>shlibs</file> files</heading>
<p>
- Put a call to <prgn>dpkg-shlibdeps</prgn> into your
- <file>debian/rules</file> file. If your package contains only
- compiled binaries and libraries (but no scripts), you can
- use a command such as:
- <example compact="compact">
-dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* \
- debian/tmp/usr/lib/*
- </example>
- Otherwise, you will need to explicitly list the compiled
- binaries and libraries.<footnote>
- 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.
- </footnote>
- </p>
-
- <p>
- This command puts the dependency information into the
- <file>debian/substvars</file> file, which is then used by
- <prgn>dpkg-gencontrol</prgn>. You will need to place a
- <tt>${shlib:Depends}</tt> variable in the <tt>Depends</tt>
- field in the control file for this to work.
- </p>
-
- <p>
- If <prgn>dpkg-shlibdeps</prgn> doesn't complain, you're
- done. If it does complain you might need to create your own
- <file>debian/shlibs.local</file> file, as explained below (see
- <ref id="shlibslocal">).
- </p>
-
- <p>
- If you have multiple binary packages, you will need to call
- <prgn>dpkg-shlibdeps</prgn> on each one which contains
- compiled libraries or binaries. In such a case, you will
- need to use the <tt>-T</tt> option to the <tt>dpkg</tt>
- utilities to specify a different <file>substvars</file> file.
- For more details on this and other options, see <manref
- name="dpkg-shlibdeps" section="1">.
+ <list compact="compact">
+ <item>
+ <var>postrm</var> <tt>remove</tt>
+ </item>
+ <item>
+ <var>postrm</var> <tt>purge</tt>
+ </item>
+ <item>
+ <var>old-postrm</var> <tt>upgrade</tt>
+ <var>new-version</var>
+ </item>
+ <item>
+ <var>new-postrm</var> <tt>failed-upgrade</tt>
+ <var>old-version</var>
+ </item>
+ <item>
+ <var>new-postrm</var> <tt>abort-install</tt>
+ </item>
+ <item>
+ <var>new-postrm</var> <tt>abort-install</tt>
+ <var>old-version</var>
+ </item>
+ <item>
+ <var>new-postrm</var> <tt>abort-upgrade</tt>
+ <var>old-version</var>
+ </item>
+ <item>
+ <var>disappearer's-postrm</var> <tt>disappear</tt>
+ <var>overwriter</var>
+ <var>overwriter-version</var>
+ </item>
+ </list>
</p>
- </sect1>
- <sect1 id="shlibs">
- <heading>The <file>shlibs</file> File Format</heading>
- <p>
- Each <file>shlibs</file> file has the same format. Lines
- beginning with <tt>#</tt> are considered to be comments and
- are ignored. Each line is of the form:
- <example compact="compact">
-<var>library-name</var> <var>soname-version-number</var> <var>dependencies ...</var>
- </example>
- </p>
+ <sect id="unpackphase">
+ <heading>Details of unpack phase of installation or upgrade</heading>
<p>
- We will explain this by reference to the example of the
- <tt>zlib1g</tt> package, which (at the time of writing)
- installs the shared library <file>/usr/lib/libz.so.1.1.3</file>.
- </p>
+ The procedure on installation/upgrade/overwrite/disappear
+ (i.e., when running <tt>dpkg --unpack</tt>, or the unpack
+ stage of <tt>dpkg --install</tt>) is as follows. In each
+ case, if a major error occurs (unless listed below) the
+ actions are, in general, run backwards - this means that the
+ maintainer scripts are run with different arguments in
+ reverse order. These are the "error unwind" calls listed
+ below.
- <p>
- <var>library-name</var> is the name of the shared library,
- in this case <tt>libz</tt>. (This must match the name part
- of the soname, see below.)
- </p>
+ <enumlist>
+ <item>
+ <enumlist>
+ <item>
+ If a version of the package is already installed, call
+ <example compact="compact">
+<var>old-prerm</var> upgrade <var>new-version</var>
+ </example>
+ </item>
+ <item>
+ If the script runs but exits with a non-zero
+ exit status, <prgn>dpkg</prgn> will attempt:
+ <example compact="compact">
+<var>new-prerm</var> failed-upgrade <var>old-version</var>
+ </example>
+ Error unwind, for both the above cases:
+ <example compact="compact">
+<var>old-postinst</var> abort-upgrade <var>new-version</var>
+ </example>
+ </item>
+ </enumlist>
+ </item>
- <p>
- <var>soname-version-number</var> is the version part of the
- soname of the library. The soname is the thing that must
- exactly match for the library to be recognized by the
- dynamic linker, and is usually of the form
- <tt><var>name</var>.so.<var>major-version</var></tt>, in our
- example, <tt>libz.so.1</tt>.<footnote>
- This can be determined using the command
- <example compact="compact">
-objdump -p /usr/lib/libz.so.1.1.3 | grep SONAME
- </example>
- </footnote>
- The version part is the part which comes after
- <tt>.so.</tt>, so in our case, it is <tt>1</tt>.
- </p>
+ <item>
+ If a "conflicting" package is being removed at the same time:
+ <enumlist>
+ <item>
+ If any packages depended on that conflicting
+ package and <tt>--auto-deconfigure</tt> is
+ specified, call, for each such package:
+ <example compact="compact">
+<var>deconfigured's-prerm</var> deconfigure \
+ in-favour <var>package-being-installed</var> <var>version</var> \
+ removing <var>conflicting-package</var> <var>version</var>
+ </example>
+ Error unwind:
+ <example compact="compact">
+<var>deconfigured's-postinst</var> abort-deconfigure \
+ in-favour <var>package-being-installed-but-failed</var> <var>version</var> \
+ removing <var>conflicting-package</var> <var>version</var>
+ </example>
+ The deconfigured packages are marked as
+ requiring configuration, so that if
+ <tt>--install</tt> is used they will be
+ configured again if possible.
+ </item>
+ <item>
+ 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>
+ </example>
+ Error unwind:
+ <example compact="compact">
+<var>conflictor's-postinst</var> abort-remove \
+ in-favour <var>package</var> <var>new-version</var>
+ </example>
+ </item>
+ </enumlist>
+ </item>
- <p>
- <var>dependencies</var> has the same syntax as a dependency
- field in a binary package control file. It should give
- details of which packages are required to satisfy a binary
- built against the version of the library contained in the
- package. See <ref id="depsyntax"> for details.
- </p>
+ <item>
+ <enumlist>
+ <item>
+ If the package is being upgraded, call:
+ <example compact="compact">
+<var>new-preinst</var> upgrade <var>old-version</var>
+ </example>
+ </item>
+ <item>
+ Otherwise, if the package had some configuration
+ files from a previous version installed (i.e., it
+ is in the "configuration files only" state):
+ <example compact="compact">
+<var>new-preinst</var> install <var>old-version</var>
+ </example>
+ </item>
+ <item>
+ Otherwise (i.e., the package was completely purged):
+ <example compact="compact">
+<var>new-preinst</var> install
+ </example>
+ Error unwind actions, respectively:
+ <example compact="compact">
+<var>new-postrm</var> abort-upgrade <var>old-version</var>
+<var>new-postrm</var> abort-install <var>old-version</var>
+<var>new-postrm</var> abort-install
+ </example>
+ </item>
+ </enumlist>
+ </item>
- <p>
- In our example, if the first version of the <tt>zlib1g</tt>
- package which contained a minor number of at least
- <tt>1.3</tt> was <var>1:1.1.3-1</var>, then the
- <tt>shlibs</tt> entry for this library could say:
- <example compact="compact">
-libz 1 zlib1g (>= 1:1.1.3)
- </example>
- The version-specific dependency is to avoid warnings from
- the dynamic linker about using older shared libraries with
- newer binaries.
- </p>
- </sect1>
+ <item>
+ <p>
+ The new package's files are unpacked, overwriting any
+ that may be on the system already, for example any
+ from the old version of the same package or from
+ another package. Backups of the old files are kept
+ temporarily, and if anything goes wrong the package
+ management system will attempt to put them back as
+ part of the error unwind.
+ </p>
- <sect1>
- <heading>Providing a <file>shlibs</file> file</heading>
+ <p>
+ 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">).
+ <!--
+ The following paragraph is not currently the case:
+ Currently the <tt>- - force-overwrite</tt> flag is
+ enabled, downgrading it to a warning, but this may not
+ always be the case.
+ -->
+ </p>
- <p>
- If your package provides a shared library, you should create
- a <file>shlibs</file> file following the format described above.
- It is usual to call this file <file>debian/shlibs</file> (but if
- you have multiple binary packages, you might want to call it
- <file>debian/shlibs.<var>package</var></file> instead). Then
- let <file>debian/rules</file> install it in the control area:
- <example compact="compact">
-install -m644 debian/shlibs debian/tmp/DEBIAN
- </example>
- or, in the case of a multi-binary package:
- <example compact="compact">
-install -m644 debian/shlibs.<var>package</var> debian/<var>package</var>/DEBIAN/shlibs
- </example>
- An alternative way of doing this is to create the
- <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>
- This is what <prgn>dh_makeshlibs</prgn> in the
- <tt>debhelper</tt> suite does.
- </footnote>
- since the <file>debian/shlibs</file> file itself is ignored by
- <prgn>dpkg-shlibdeps</prgn>.
- </p>
-
- <p>
- As <prgn>dpkg-shlibdeps</prgn> reads the
- <file>DEBIAN/shlibs</file> files in all of the binary packages
- being built from this source package, all of the
- <file>DEBIAN/shlibs</file> files should be installed before
- <prgn>dpkg-shlibdeps</prgn> is called on any of the binary
- packages.
- </p>
- </sect1>
-
- <sect1 id="shlibslocal">
- <heading>Writing the <file>debian/shlibs.local</file> file</heading>
-
- <p>
- This file is intended only as a <em>temporary</em> fix if
- your binaries or libraries depend on a library whose package
- does not yet provide a correct <file>shlibs</file> file.
- </p>
-
- <p>
- We will assume that you are trying to package a binary
- <tt>foo</tt>. When you try running
- <prgn>dpkg-shlibdeps</prgn> you get the following error
- message (<tt>-O</tt> displays the dependency information on
- <tt>stdout</tt> instead of writing it to
- <tt>debian/substvars</tt>, and the lines have been wrapped
- for ease of reading):
- <example compact="compact">
-$ dpkg-shlibdeps -O debian/tmp/usr/bin/foo
-dpkg-shlibdeps: warning: unable to find dependency
- information for shared library libbar (soname 1,
- path /usr/lib/libbar.so.1, dependency field Depends)
-shlibs:Depends=libc6 (>= 2.2.2-2)
- </example>
- You can then run <prgn>ldd</prgn> on the binary to find the
- full location of the library concerned:
- <example compact="compact">
-$ ldd foo
-libbar.so.1 => /usr/lib/libbar.so.1 (0x4001e000)
-libc.so.6 => /lib/libc.so.6 (0x40032000)
-/lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
- </example>
- So the <prgn>foo</prgn> binary depends on the
- <prgn>libbar</prgn> shared library, but no package seems to
- provide a <file>*.shlibs</file> file handling
- <file>libbar.so.1</file> in <file>/var/lib/dpkg/info/</file>. Let's
- determine the package responsible:
- <example compact="compact">
-$ dpkg -S /usr/lib/libbar.so.1
-bar1: /usr/lib/libbar.so.1
-$ dpkg -s bar1 | grep Version
-Version: 1.0-1
- </example>
- This tells us that the <tt>bar1</tt> package, version 1.0-1,
- is the one we are using. Now we can file a bug against the
- <tt>bar1</tt> package and create our own
- <file>debian/shlibs.local</file> to locally fix the problem.
- Including the following line into your
- <file>debian/shlibs.local</file> file:
- <example compact="compact">
-libbar 1 bar1 (>= 1.0-1)
- </example>
- should allow the package build to work.
- </p>
-
- <p>
- As soon as the maintainer of <tt>bar1</tt> provides a
- correct <file>shlibs</file> file, you should remove this line
- from your <file>debian/shlibs.local</file> file. (You should
- probably also then have a versioned <tt>Build-Depends</tt>
- on <tt>bar1</tt> to help ensure that others do not have the
- same problem building your package.)
- </p>
- </sect1>
-
- </sect>
-
- </chapt>
-
- <chapt id="opersys"><heading>The Operating System</heading>
-
- <sect>
- <heading>Filesystem hierarchy</heading>
-
-
- <sect1 id="fhs">
- <heading>Filesystem Structure</heading>
-
- <p>
- The location of all installed files and directories must
- comply with the Filesystem Hierarchy Standard (FHS),
- version 2.1, except where doing so would violate other
- terms of Debian Policy. The version of this document
- referred here can be found in the <tt>debian-policy</tt>
- package or on
- <url id="http://www.debian.org/doc/packaging-manuals/fhs/"
- name="FHS (Debian copy)"> alongside this manual (or, if
- you have the <package>debian-policy</package> installed,
- you can try <url
- id="file:///usr/share/doc/debian-policy/fhs/" name="FHS
- (local copy)">). The
- latest version, which may be a more recent version, may
- be found on
- <url id="http://www.pathname.com/fhs/" name="FHS (upstream)">.
- Specific questions about following the standard may be
- asked on the <tt>debian-devel</tt> mailing list, or
- referred to the FHS mailing list (see the
- <url id="http://www.pathname.com/fhs/" name="FHS web site"> for
- more information).
- </p>
- </sect1>
-
- <sect1>
- <heading>Site-specific programs</heading>
-
- <p>
- As mandated by the FHS, packages must not place any
- files in <file>/usr/local</file>, either by putting them in
- the file system archive to be unpacked by <prgn>dpkg</prgn>
- or by manipulating them in their maintainer scripts.
- </p>
-
- <p>
- However, the package may create empty directories below
- <file>/usr/local</file> so that the system administrator knows
- where to place site-specific files. These directories
- should be removed on package removal if they are
- empty.
- </p>
-
- <p>
- Note, that this applies only to directories <em>below</em>
- <file>/usr/local</file>, not <em>in</em> <file>/usr/local</file>.
- Packages must not create sub-directories in the directory
- <file>/usr/local</file> itself, except those listed in FHS,
- section 4.5. However, you may create directories below
- them as you wish. You must not remove any of the
- directories listed in 4.5, even if you created them.
- </p>
-
- <p>
- Since <file>/usr/local</file> can be mounted read-only from a
- remote server, these directories must be created and
- removed by the <prgn>postinst</prgn> and <prgn>prerm</prgn>
- maintainer scripts and not be included in the
- <file>.deb</file> archive. These scripts must not fail if
- either of these operations fail.
- </p>
-
- <p>
- For example, the <tt>emacsen-common</tt> package could
- contain something like
- <example compact="compact">
-if [ ! -e /usr/local/share/emacs ]
-then
- if mkdir /usr/local/share/emacs 2>/dev/null
- then
- chown root:staff /usr/local/share/emacs
- chmod 2775 /usr/local/share/emacs
- fi
-fi
- </example>
- in its <prgn>postinst</prgn> script, and
- <example compact="compact">
-rmdir /usr/local/share/emacs/site-lisp 2>/dev/null || true
-rmdir /usr/local/share/emacs 2>/dev/null || true
- </example>
- in the <prgn>prerm</prgn> script. (Note that this form is
- used to ensure that if the script is interrupted, the
- directory <file>/usr/local/share/emacs</file> will still be
- removed.)
- </p>
-
- <p>
- If you do create a directory in <file>/usr/local</file> for
- local additions to a package, you should ensure that
- settings in <file>/usr/local</file> take precedence over the
- equivalents in <file>/usr</file>.
- </p>
-
- <p>
- However, because <file>/usr/local</file> and its contents are
- for exclusive use of the local administrator, a package
- must not rely on the presence or absence of files or
- directories in <file>/usr/local</file> for normal operation.
- </p>
-
- <p>
- The <file>/usr/local</file> directory itself and all the
- subdirectories created by the package should (by default) have
- permissions 2775 (group-writable and set-group-id) and be
- owned by <tt>root.staff</tt>.
- </p>
- </sect1>
-
- <sect1>
- <heading>The system-wide mail directory</heading>
- <p>
- The system-wide mail directory is <file>/var/mail</file>. This
- directory is part of the base system and should not owned
- by any particular mail agents. The use of the old
- location <file>/var/spool/mail</file> is deprecated, even
- though the spool may still be physically located there.
- To maintain partial upgrade compatibility for systems
- which have <file>/var/spool/mail</file> as their physical mail
- spool, packages using <file>/var/mail</file> must depend on
- either <package>libc6</package> (>= 2.1.3-13), or on
- <package>base-files</package> (>= 2.2.0), or on later
- versions of either one of these packages.
- </p>
- </sect1>
- </sect>
-
- <sect>
- <heading>Users and groups</heading>
-
- <sect1>
- <heading>Introduction</heading>
- <p>
- The Debian system can be configured to use either plain or
- shadow passwords.
- </p>
-
- <p>
- Some user ids (UIDs) and group ids (GIDs) are reserved
- globally for use by certain packages. Because some
- packages need to include files which are owned by these
- users or groups, or need the ids compiled into binaries,
- these ids must be used on any Debian system only for the
- purpose for which they are allocated. This is a serious
- restriction, and we should avoid getting in the way of
- local administration policies. In particular, many sites
- allocate users and/or local system groups starting at 100.
- </p>
-
- <p>
- Apart from this we should have dynamically allocated ids,
- which should by default be arranged in some sensible
- order, but the behavior should be configurable.
- </p>
-
- <p>
- Packages other than <tt>base-passwd</tt> must not modify
- <file>/etc/passwd</file>, <file>/etc/shadow</file>,
- <file>/etc/group</file> or <file>/etc/gshadow</file>.
- </p>
- </sect1>
-
- <sect1>
- <heading>UID and GID classes</heading>
- <p>
- The UID and GID numbers are divided into classes as
- follows:
- <taglist>
- <tag>0-99:</tag>
- <item>
- <p>
- Globally allocated by the Debian project, the same
- on every Debian system. These ids will appear in
- the <file>passwd</file> and <file>group</file> files of all
- Debian systems, new ids in this range being added
- automatically as the <tt>base-passwd</tt> package is
- updated.
- </p>
-
- <p>
- Packages which need a single statically allocated
- uid or gid should use one of these; their
- maintainers should ask the <tt>base-passwd</tt>
- maintainer for ids.
- </p>
- </item>
-
- <tag>100-999:</tag>
- <item>
- <p>
- Dynamically allocated system users and groups.
- Packages which need a user or group, but can have
- this user or group allocated dynamically and
- differently on each system, should use <tt>adduser
- --system</tt> to create the group and/or user.
- <prgn>adduser</prgn> will check for the existence of
- the user or group, and if necessary choose an unused
- id based on the ranges specified in
- <file>adduser.conf</file>.
- </p>
- </item>
-
- <tag>1000-29999:</tag>
- <item>
- <p>
- Dynamically allocated user accounts. By default
- <prgn>adduser</prgn> will choose UIDs and GIDs for
- user accounts in this range, though
- <file>adduser.conf</file> may be used to modify this
- behavior.
- </p>
- </item>
-
- <tag>30000-59999:</tag>
- <item>
- <p>Reserved.</p>
- </item>
-
- <tag>60000-64999:</tag>
- <item>
- <p>
- Globally allocated by the Debian project, but only
- created on demand. The ids are allocated centrally
- and statically, but the actual accounts are only
- created on users' systems on demand.
- </p>
-
- <p>
- These ids are for packages which are obscure or
- which require many statically-allocated ids. These
- packages should check for and create the accounts in
- <file>/etc/passwd</file> or <file>/etc/group</file> (using
- <prgn>adduser</prgn> if it has this facility) if
- necessary. Packages which are likely to require
- further allocations should have a "hole" left after
- them in the allocation, to give them room to
- grow.
- </p>
- </item>
-
- <tag>65000-65533:</tag>
- <item>
- <p>Reserved.</p>
- </item>
-
- <tag>65534:</tag>
- <item>
- <p>
- User <tt>nobody</tt>. The corresponding gid refers
- to the group <tt>nogroup</tt>.
- </p>
- </item>
-
- <tag>65535:</tag>
- <item>
- <p>
- <tt>(uid_t)(-1) == (gid_t)(-1)</tt> <em>must
- not</em> be used, because it is the error return
- sentinel value.
- </p>
- </item>
- </taglist>
- </p>
- </sect1>
- </sect>
-
- <sect id="sysvinit">
- <heading>System run levels and <file>init.d</file> scripts</heading>
-
- <sect1 id="/etc/init.d">
- <heading>Introduction</heading>
-
- <p>
- The <file>/etc/init.d</file> directory contains the scripts
- executed by <prgn>init</prgn> at boot time and when the
- init state (or "runlevel") is changed (see <manref
- name="init" section="8">).
- </p>
-
- <p>
- There are at least two different, yet functionally
- equivalent, ways of handling these scripts. For the sake
- of simplicity, this document describes only the symbolic
- link method. However, it must not be assumed by maintainer
- scripts that this method is being used, and any automated
- manipulation of the various runlevel behaviours by
- maintainer scripts must be performed using
- <prgn>update-rc.d</prgn> as described below and not by
- manually installing or removing symlinks. For information
- on the implementation details of the other method,
- implemented in the <tt>file-rc</tt> package, please refer
- to the documentation of that package.
- </p>
-
- <p>
- These scripts are referenced by symbolic links in the
- <file>/etc/rc<var>n</var>.d</file> directories. When changing
- runlevels, <prgn>init</prgn> looks in the directory
- <file>/etc/rc<var>n</var>.d</file> for the scripts it should
- execute, where <tt><var>n</var></tt> is the runlevel that
- is being changed to, or <tt>S</tt> for the boot-up
- scripts.
- </p>
-
- <p>
- The names of the links all have the form
- <file>S<var>mm</var><var>script</var></file> or
- <file>K<var>mm</var><var>script</var></file> where
- <var>mm</var> is a two-digit number and <var>script</var>
- is the name of the script (this should be the same as the
- name of the actual script in <file>/etc/init.d</file>).
- </p>
-
- <p>
- When <prgn>init</prgn> changes runlevel first the targets
- of the links whose names start with a <tt>K</tt> are
- executed, each with the single argument <tt>stop</tt>,
- followed by the scripts prefixed with an <tt>S</tt>, each
- with the single argument <tt>start</tt>. (The links are
- those in the <file>/etc/rc<var>n</var>.d</file> directory
- corresponding to the new runlevel.) The <tt>K</tt> links
- are responsible for killing services and the <tt>S</tt>
- link for starting services upon entering the runlevel.
- </p>
-
- <p>
- For example, if we are changing from runlevel 2 to
- runlevel 3, init will first execute all of the <tt>K</tt>
- prefixed scripts it finds in <file>/etc/rc3.d</file>, and then
- all of the <tt>S</tt> prefixed scripts in that directory.
- The links starting with <tt>K</tt> will cause the
- referred-to file to be executed with an argument of
- <tt>stop</tt>, and the <tt>S</tt> links with an argument
- of <tt>start</tt>.
- </p>
-
- <p>
- The two-digit number <var>mm</var> is used to determine
- the order in which to run the scripts: low-numbered links
- have their scripts run first. For example, the
- <tt>K20</tt> scripts will be executed before the
- <tt>K30</tt> scripts. This is used when a certain service
- must be started before another. For example, the name
- server <prgn>bind</prgn> might need to be started before
- the news server <prgn>inn</prgn> so that <prgn>inn</prgn>
- can set up its access lists. In this case, the script
- that starts <prgn>bind</prgn> would have a lower number
- than the script that starts <prgn>inn</prgn> so that it
- runs first:
- <example compact="compact">
-/etc/rc2.d/S17bind
-/etc/rc2.d/S70inn
- </example>
- </p>
-
- <p>
- The two runlevels 0 (halt) and 6 (reboot) are slightly
- different. In these runlevels, the links with an
- <tt>S</tt> prefix are still called after those with a
- <tt>K</tt> prefix, but they too are called with the single
- argument <tt>stop</tt>.
- </p>
-
- <p>
- Also, if the script name ends <tt>.sh</tt>, the script
- will be sourced in runlevel <tt>S</tt> rather that being
- run in a forked subprocess, but will be explicitly run by
- <prgn>sh</prgn> in all other runlevels.
- </p>
- </sect1>
-
- <sect1>
- <heading>Writing the scripts</heading>
-
- <p>
- Packages that include daemons for system services should
- place scripts in <file>/etc/init.d</file> to start or stop
- services at boot time or during a change of runlevel.
- These scripts should be named
- <file>/etc/init.d/<var>package</var></file>, and they should
- accept one argument, saying what to do:
-
- <taglist>
- <tag><tt>start</tt></tag>
- <item>start the service,</item>
-
- <tag><tt>stop</tt></tag>
- <item>stop the service,</item>
-
- <tag><tt>restart</tt></tag>
- <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,</item>
-
- <tag><tt>force-reload</tt></tag>
- <item>cause the configuration to be reloaded if the
- service supports this, otherwise restart the
- 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>
-
- <p>
- The <file>init.d</file> scripts should ensure that they will
- behave sensibly if invoked with <tt>start</tt> when the
- 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>
-
- <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>
+ <p>
+ It is a more serious error for a package to contain a
+ plain file or other kind of non-directory where another
+ package has a directory (again, unless
+ <tt>Replaces</tt> is used). This error can be
+ overridden if desired using
+ <tt>--force-overwrite-dir</tt>, but this is not
+ advisable.
+ </p>
- <p>
- The <file>/etc/init.d</file> scripts must be treated as
- configuration files, either (if they are present in the
- package, that is, in the .deb file) by marking them as
- <tt>conffile</tt>s, or, (if they do not exist in the .deb)
- by managing them correctly in the maintainer scripts (see
- <ref id="config-files">). This is important since we want
- to give the local system administrator the chance to adapt
- the scripts to the local system, e.g., to disable a
- service without de-installing the package, or to specify
- some special command line options when starting a service,
- while making sure her changes aren't lost during the next
- package upgrade.
- </p>
+ <p>
+ Packages which overwrite each other's files produce
+ behavior which, though deterministic, is hard for the
+ system administrator to understand. It can easily
+ lead to "missing" programs if, for example, a package
+ is installed which overwrites a file from another
+ package, and is then removed again.<footnote>
+ Part of the problem is due to what is arguably a
+ bug in <prgn>dpkg</prgn>.
+ </footnote>
+ </p>
- <p>
- These scripts should not fail obscurely when the
- configuration files remain but the package has been
- removed, as configuration files remain on the system after
- the package has been removed. Only when <prgn>dpkg</prgn>
- is executed with the <tt>--purge</tt> option will
- configuration files be removed. In particular, as the
- <file>/etc/init.d/<var>package</var></file> script itself is
- usually a <tt>conffile</tt>, it will remain on the system
- if the package is removed but not purged. Therefore, you
- should include a <tt>test</tt> statement at the top of the
- script, like this:
- <example compact="compact">
-test -f <var>program-executed-later-in-script</var> || exit 0
- </example>
- </p>
+ <p>
+ A directory will never be replaced by a symbolic link
+ to a directory or vice versa; instead, the existing
+ state (symlink or not) will be left alone and
+ <prgn>dpkg</prgn> will follow the symlink if there is
+ one.
+ </p>
+ </item>
- <p>
- Often there are some variables in the <file>init.d</file>
- scripts whose values control the behaviour of the scripts,
- and which a system administrator is likely to want to
- change. As the scripts themselves are frequently
- <tt>conffile</tt>s, modifying them requires that the
- administrator merge in their changes each time the package
- is upgraded and the <tt>conffile</tt> changes. To ease
- the burden on the system administrator, such configurable
- values should not be placed directly in the script.
- Instead, they should be placed in a file in
- <file>/etc/default</file>, which typically will have the same
- base name as the <file>init.d</file> script. This extra file
- should be sourced by the script when the script runs. It
- must contain only variable settings and comments in POSIX
- <prgn>sh</prgn> format. It may either be a
- <tt>conffile</tt> or a configuration file maintained by
- the package maintainer scripts. See <ref id="config-files">
- for more details.
- </p>
+ <item>
+ <p>
+ <enumlist>
+ <item>
+ If the package is being upgraded, call
+ <example compact="compact">
+<var>old-postrm</var> upgrade <var>new-version</var>
+ </example>
+ </item>
+ <item>
+ If this fails, <prgn>dpkg</prgn> will attempt:
+ <example compact="compact">
+<var>new-postrm</var> failed-upgrade <var>old-version</var>
+ </example>
+ Error unwind, for both cases:
+ <example compact="compact">
+<var>old-preinst</var> abort-upgrade <var>new-version</var>
+ </example>
+ </item>
+ </enumlist>
+ </p>
- <p>
- To ensure that vital configurable values are always
- available, the <file>init.d</file> script should set default
- values for each of the shell variables it uses, either
- before sourcing the <file>/etc/default/</file> file or
- afterwards using something like the <tt>:
- ${VAR:=default}</tt> syntax. Also, the <file>init.d</file>
- script must behave sensibly and not fail if the
- <file>/etc/default</file> file is deleted.
- </p>
- </sect1>
+ <p>
+ This is the point of no return - if
+ <prgn>dpkg</prgn> gets this far, it won't back off
+ past this point if an error occurs. This will
+ leave the package in a fairly bad state, which
+ will require a successful re-installation to clear
+ up, but it's when <prgn>dpkg</prgn> starts doing
+ things that are irreversible.
+ </p>
+ </item>
- <sect1>
- <heading>Interfacing with the initscript system</heading>
+ <item>
+ Any files which were in the old version of the package
+ but not in the new are removed.
+ </item>
- <p>
- Maintainers should use the abstraction layer provided by
- the <prgn>update-rc.d</prgn> and <prgn>invoke-rc.d</prgn>
- programs to deal with initscripts in their packages'
- scripts such as <prgn>postinst</prgn>, <prgn>prerm</prgn>
- and <prgn>postrm</prgn>.
- </p>
+ <item>
+ The new file list replaces the old.
+ </item>
- <p>
- Directly managing the /etc/rc?.d links and directly
- invoking the <file>/etc/init.d/</file> initscripts should
- be done only by packages providing the initscript
- subsystem (such as <prgn>sysvinit</prgn> and
- <prgn>file-rc</prgn>).
- </p>
+ <item>
+ The new maintainer scripts replace the old.
+ </item>
- <sect2>
- <heading>Managing the links</heading>
+ <item>
+ 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>
+ <prgn>dpkg</prgn> calls:
+ <example compact="compact">
+<var>disappearer's-postrm</var> disappear \
+ <var>overwriter</var> <var>overwriter-version</var>
+ </example>
+ </item>
+ <item>
+ The package's maintainer scripts are removed.
+ </item>
+ <item>
+ 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
+ removed by <prgn>dpkg</prgn>). Note that
+ disappearing packages do not have their prerm
+ called, because <prgn>dpkg</prgn> doesn't know
+ in advance that the package is going to
+ vanish.
+ </item>
+ </enumlist>
+ </item>
- <p>
- The program <prgn>update-rc.d</prgn> is provided for
- package maintainers to arrange for the proper creation and
- 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>
+ <item>
+ 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.)
+ </item>
- <p>
- You must not include any <file>/etc/rc<var>n</var>.d</file>
- symbolic links in the actual archive or manually create or
- remove the symbolic links in maintainer scripts; you must
- use the <prgn>update-rc.d</prgn> program instead. (The
- former will fail if an alternative method of maintaining
- runlevel information is being used.) You must not include
- the <file>/etc/rc<var>n</var>.d</file> directories themselves
- in the archive either. (Only the <tt>sysvinit</tt>
- package may do so.)
- </p>
+ <item>
+ The backup files made during installation, above, are
+ deleted.
+ </item>
- <p>
- By default <prgn>update-rc.d</prgn> will start services in
- each of the multi-user state runlevels (2, 3, 4, and 5)
- and stop them in the halt runlevel (0), the single-user
- runlevel (1) and the reboot runlevel (6). The system
- administrator will have the opportunity to customize
- runlevels by simply adding, moving, or removing the
- symbolic links in <file>/etc/rc<var>n</var>.d</file> if
- symbolic links are being used, or by modifying
- <file>/etc/runlevel.conf</file> if the <tt>file-rc</tt> method
- is being used.
- </p>
+ <item>
+ <p>
+ The new package's status is now sane, and recorded as
+ "unpacked".
+ </p>
- <p>
- To get the default behavior for your package, put in your
- <prgn>postinst</prgn> script
- <example compact="compact">
- update-rc.d <var>package</var> defaults
- </example>
- and in your <prgn>postrm</prgn>
- <example compact="compact">
- if [ "$1" = purge ]; then
- update-rc.d <var>package</var> remove
- fi
- </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>
+ <p>
+ Here is another point of no return - if the
+ conflicting package's removal fails we do not unwind
+ the rest of the installation; the conflicting package
+ is left in a half-removed limbo.
+ </p>
+ </item>
- <p>
- This will use a default sequence number of 20. If it does
- not matter when or in which order the <file>init.d</file>
- script is run, use this default. If it does, then you
- should talk to the maintainer of the <prgn>sysvinit</prgn>
- package or post to <tt>debian-devel</tt>, and they will
- help you choose a number.
- </p>
+ <item>
+ 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).
+ </item>
+ </enumlist>
+ </p>
+ </sect>
- <p>
- For more information about using <tt>update-rc.d</tt>,
- please consult its manpage <manref name="update-rc.d"
- section="8">.
- </p>
- </sect2>
+ <sect id="configdetails"><heading>Details of configuration</heading>
- <sect2>
- <heading>Running initscripts</heading>
- <p>
- The program <prgn>invoke-rc.d</prgn> is provided to make
- it easier for package maintainers to properly invoke an
- initscript, obeying runlevel and other locally-defined
- constraints that might limit a package's right to start,
- stop and otherwise manage services. This program may be
- used by maintainers in their packages' scripts.
- </p>
+ <p>
+ When we configure a package (this happens with <tt>dpkg
+ --install</tt> and <tt>dpkg --configure</tt>), we first
+ update any <tt>conffile</tt>s and then call:
+ <example compact="compact">
+<var>postinst</var> configure <var>most-recently-configured-version</var>
+ </example>
+ </p>
- <p>
- The use of <prgn>invoke-rc.d</prgn> to invoke the
- <file>/etc/init.d/*</file> initscripts is strongly
- recommended<footnote>
- 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.
- </footnote>, instead of calling them directly.
- </p>
+ <p>
+ No attempt is made to unwind after errors during
+ configuration.
+ </p>
- <p>
- By default, <prgn>invoke-rc.d</prgn> will pass any
- action requests (start, stop, reload, restart...) to the
- <file>/etc/init.d</file> script, filtering out requests
- to start or restart a service out of its intended
- runlevels.
- </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.
+ </p>
+ </sect>
- <p>
- Most packages will simply need to change:
- <example compact="compact">/etc/init.d/<package>
- <action></example> in their <prgn>postinst</prgn>
- and <prgn>prerm</prgn> scripts to:
- <example compact="compact">
- if [ -x /usr/sbin/invoke-rc.d ] ; then
- invoke-rc.d <var>package</var> <action>
- else
- /etc/init.d/<var>package</var> <action>
- fi
- </example>
- </p>
+ <sect id="removedetails"><heading>Details of removal and/or
+ configuration purging</heading>
- <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>
+ <enumlist>
+ <item>
+ <example compact="compact">
+<var>prerm</var> remove
+ </example>
+ </item>
+ <item>
+ The package's files are removed (except <tt>conffile</tt>s).
+ </item>
+ <item>
+ <example compact="compact">
+<var>postrm</var> remove
+ </example>
+ </item>
+ <item>
+ <p>
+ All the maintainer scripts except the <prgn>postrm</prgn>
+ are removed.
+ </p>
- <p>
- For more information about using
- <prgn>invoke-rc.d</prgn>, please consult its manpage
- <manref name="invoke-rc.d" section="8">.
- </p>
- </sect2>
- </sect1>
+ <p>
+ If we aren't purging the package we stop here. Note
+ that packages which have no <prgn>postrm</prgn> and no
+ <tt>conffile</tt>s are automatically purged when
+ removed, as there is no difference except for the
+ <prgn>dpkg</prgn> status.
+ </p>
+ </item>
+ <item>
+ 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.
+ </item>
+ <item>
+ <example compact="compact">
+<var>postrm</var> purge
+ </example>
+ </item>
+ <item>
+ The package's file list is removed.
+ </item>
+ </enumlist>
- <sect1>
- <heading>Boot-time initialization</heading>
+ No attempt is made to unwind after errors during
+ removal.
+ </p>
+ </sect>
+ </chapt>
- <p>
- There used to be another directory, <file>/etc/rc.boot</file>,
- which contained scripts which were run once per machine
- 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>
- </sect1>
- <sect1>
- <heading>Example</heading>
+ <chapt id="relationships">
+ <heading>Declaring relationships between packages</heading>
- <p>
- The <prgn>bind</prgn> DNS (nameserver) package wants to
- make sure that the nameserver is running in multiuser
- runlevels, and is properly shut down with the system. It
- puts a script in <file>/etc/init.d</file>, naming the script
- appropriately <tt>bind</tt>. As you can see, the script
- interprets the argument <tt>reload</tt> to send the
- nameserver a <tt>HUP</tt> signal (causing it to reload its
- configuration); this way the system administrator can say
- <tt>/etc/init.d/bind reload</tt> to reload the name
- server. The script has one configurable value, which can
- be used to pass parameters to the named program at
- startup; this value is read from
- <file>/etc/default/bind</file> (see below).
- </p>
+ <sect id="depsyntax">
+ <heading>Syntax of relationship fields</heading>
- <p>
- <example compact="compact">
-#!/bin/sh
-#
-# Original version by Robert Leslie
-# <rob@mars.org>, edited by iwj and cs
+ <p>
+ These fields all have a uniform syntax. They are a list of
+ package names separated by commas.
+ </p>
-test -x /usr/sbin/named || exit 0
+ <p>
+ In the <tt>Depends</tt>, <tt>Recommends</tt>,
+ <tt>Suggests</tt>, <tt>Pre-Depends</tt>,
+ <tt>Build-Depends</tt> and <tt>Build-Depends-Indep</tt>
+ control file fields of the package, which declare
+ dependencies on other packages, the package names listed may
+ also include lists of alternative package names, separated
+ by vertical bar (pipe) symbols <tt>|</tt>. In such a case,
+ if any one of the alternative packages is installed, that
+ part of the dependency is considered to be satisfied.
+ </p>
-# Source defaults file.
-PARAMS=''
-if [ -f /etc/default/bind ]; then
- . /etc/default/bind
-fi
+ <p>
+ All of the fields except for <tt>Provides</tt> may restrict
+ their applicability to particular versions of each named
+ package. This is done in parentheses after each individual
+ package name; the parentheses should contain a relation from
+ the list below followed by a version number, in the format
+ described in <ref id="f-Version">.
+ </p>
+ <p>
+ The relations allowed are <tt><<</tt>, <tt><=</tt>,
+ <tt>=</tt>, <tt>>=</tt> and <tt>>></tt> for
+ strictly earlier, earlier or equal, exactly equal, later or
+ equal and strictly later, respectively. The deprecated
+ forms <tt><</tt> and <tt>></tt> were used to mean
+ earlier/later or equal, rather than strictly earlier/later,
+ so they should not appear in new packages (though
+ <prgn>dpkg</prgn> still supports them).
+ </p>
-case "$1" in
-start)
- echo -n "Starting domain name service: named"
- start-stop-daemon --start --quiet --exec /usr/sbin/named \
- -- $PARAMS
- echo "."
- ;;
-stop)
- echo -n "Stopping domain name service: named"
- start-stop-daemon --stop --quiet \
- --pidfile /var/run/named.pid --exec /usr/sbin/named
- echo "."
- ;;
-restart)
- echo -n "Restarting domain name service: named"
- start-stop-daemon --stop --quiet \
- --pidfile /var/run/named.pid --exec /usr/sbin/named
- start-stop-daemon --start --verbose --exec /usr/sbin/named \
- -- $PARAMS
- echo "."
- ;;
-force-reload|reload)
- echo -n "Reloading configuration of domain name service: named"
- start-stop-daemon --stop --signal 1 --quiet \
- --pidfile /var/run/named.pid --exec /usr/sbin/named
- echo "."
- ;;
-*)
- echo "Usage: /etc/init.d/bind " \
- " {start|stop|restart|reload|force-reload}" >&2
- exit 1
- ;;
-esac
+ <p>
+ Whitespace may appear at any point in the version
+ specification subject to the rules in <ref
+ id="controlsyntax">, and must appear where it's necessary to
+ disambiguate; it is not otherwise significant. For
+ consistency and in case of future changes to
+ <prgn>dpkg</prgn> it is recommended that a single space be
+ used after a version relationship and before a version
+ number; it is also conventional to put a single space after
+ each comma, on either side of each vertical bar, and before
+ each open parenthesis.
+ </p>
-exit 0
- </example>
- </p>
+ <p>
+ For example, a list of dependencies might appear as:
+ <example compact="compact">
+Package: mutt
+Version: 1.3.17-1
+Depends: libc6 (>= 2.2.1), exim | mail-transport-agent
+ </example>
+ </p>
- <p>
- Complementing the above init script is a configuration
- file <file>/etc/default/bind</file>, which contains
- configurable parameters used by the script. This would be
- created by the <prgn>postinst</prgn> script if it was not
- already present, and removed on purge by the
- <prgn>postrm</prgn> script.
- <example compact="compact">
-# Specified parameters to pass to named. See named(8).
-# You may uncomment the following line, and edit to taste.
-#PARAMS="-u nobody"
- </example>
- </p>
+ <p>
+ All fields that specify build-time relationships
+ (<tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
+ <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>)
+ may be restricted to a certain set of architectures. This
+ is indicated in brackets after each individual package name and
+ the optional version specification. The brackets enclose a
+ list of Debian architecture names separated by whitespace.
+ Exclamation marks may be prepended to each of the names.
+ (It is not permitted for some names to be prepended with
+ exclamation marks and others not.) If the current Debian
+ host architecture is not in this list and there are no
+ exclamation marks in the list, or it is in the list with a
+ prepended exclamation mark, the package name and the
+ associated version specification are ignored completely for
+ the purposes of defining the relationships.
+ </p>
- <p>
- Another example on which you can base your
- <file>/etc/init.d</file> scripts is found in
- <file>/etc/init.d/skeleton</file>.
- </p>
+ <p>
+ For example:
+ <example compact="compact">
+Source: glibc
+Build-Depends-Indep: texinfo
+Build-Depends: kernel-headers-2.2.10 [!hurd-i386],
+ hurd-dev [hurd-i386], gnumach-dev [hurd-i386]
+ </example>
+ </p>
- <p>
- If this package is happy with the default setup from
- <prgn>update-rc.d</prgn>, namely an ordering number of 20
- and having named running in all runlevels, it can say in
- its <prgn>postinst</prgn>:
- <example compact="compact">
-update-rc.d bind defaults >/dev/null
- </example>
- And in its <prgn>postrm</prgn>, to remove the links when the
- package is purged:
- <example compact="compact">
-if [ "$1" = purge ]; then
- update-rc.d bind remove >/dev/null
-fi
- </example>
- </p>
- </sect1>
+ <p>
+ Note that the binary package relationship fields such as
+ <tt>Depends</tt> appear in one of the binary package
+ sections of the control file, whereas the build-time
+ relationships such as <tt>Build-Depends</tt> appear in the
+ source package section of the control file (which is the
+ first section).
+ </p>
</sect>
- <sect>
- <heading>Console messages from <file>init.d</file> scripts</heading>
+ <sect id="binarydeps">
+ <heading>Binary Dependencies - <tt>Depends</tt>,
+ <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
+ <tt>Pre-Depends</tt>
+ </heading>
+
+ <p>
+ Packages can declare in their control file that they have
+ certain relationships to other packages - for example, that
+ they may not be installed at the same time as certain other
+ 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
+ <tt>Conflicts</tt> control file fields.
+ </p>
<p>
- This section describes the formats to be used for messages
- written to standard output by the <file>/etc/init.d</file>
- scripts. The intent is to improve the consistency of
- Debian's startup and shutdown look and feel. For this
- reason, please look very carefully at the details. We want
- the messages to have the same format in terms of wording,
- spaces, punctuation and case of letters.
+ These six fields are used to declare a dependency
+ relationship by one package on another. Except for
+ <tt>Enhances</tt>, they appear in the depending (binary)
+ package's control file. (<tt>Enhances</tt> appears in the
+ recommending package's control file.)
</p>
<p>
- Here is a list of overall rules that you should use when you
- create output messages. They can be useful if you have a
- non-standard message that is not covered specifically in the
- sections below.
+ A <tt>Depends</tt> field takes effect <em>only</em> when a
+ package is to be configured. It does not prevent a package
+ being on the system in an unconfigured state while its
+ dependencies are unsatisfied, and it is possible to replace
+ a package whose dependencies are satisfied and which is
+ properly installed with a different version whose
+ dependencies are not and cannot be satisfied; when this is
+ done the depending package will be left unconfigured (since
+ attempts to configure it will give errors) and will not
+ function properly. If it is necessary, a
+ <tt>Pre-Depends</tt> field can be used, which has a partial
+ effect even when a package is being unpacked, as explained
+ in detail below. (The other three dependency fields,
+ <tt>Recommends</tt>, <tt>Suggests</tt> and
+ <tt>Enhances</tt>, are only used by the various front-ends
+ to <prgn>dpkg</prgn> such as <prgn>dselect</prgn>.)
</p>
<p>
- <list>
- <item>
- Every message should fit in one line (fewer than 80
- characters), start with a capital letter and end with
- a period (<tt>.</tt>) and line feed (<tt>"\n"</tt>).
- </item>
-
- <item>
- 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.
- </item>
-
- <item>
- Design your messages as if the computer is telling you
- what he is doing (let him be polite :-), but don't
- mention "him" directly. For example, if you think of
- saying
- <example compact="compact">
-I'm starting network daemons: nfsd mountd.
- </example>
- just say
- <example compact="compact">
-Starting network daemons: nfsd mountd.
- </example>
- </item>
- </list>
+ For this reason packages in an installation run are usually
+ all unpacked first and all configured later; this gives
+ later versions of packages with dependencies on later
+ versions of other packages the opportunity to have their
+ dependencies satisfied.
</p>
<p>
- There are standard message formats for the following
- situations. They should be used by the <tt>init.d</tt>
- scripts.
+ The <tt>Depends</tt> field thus allows package maintainers
+ to impose an order in which packages should be configured.
</p>
<p>
- <list>
+ The meaning of the five dependency fields is as follows:
+ <taglist>
+ <tag><tt>Depends</tt></tag>
<item>
- <p>When daemons are started</p>
-
<p>
- If your script starts one or more daemons, the output
- should look like this (a single line, no leading
- spaces):
- <example compact="compact">
-Starting <var>description</var>: <var>daemon-1</var> ... <var>daemon-n</var>.
- </example>
- The <var>description</var> should describe the
- subsystem the daemon or set of daemons are part of,
- while <var>daemon-1</var> up to <var>daemon-n</var>
- denote each daemon's name (typically the file name of
- the program).
+ This declares an absolute dependency. A package will
+ not be configured unless all of the packages listed in
+ its <tt>Depends</tt> field have been correctly
+ configured.
</p>
<p>
- For example, the output of <file>/etc/init.d/lpd</file>
- would look like:
- <example compact="compact">
-Starting printer spooler: lpd.
- </example>
+ The <tt>Depends</tt> field should be used if the
+ depended-on package is required for the depending
+ package to provide a significant amount of
+ functionality.
</p>
<p>
- This can be achieved by saying
- <example compact="compact">
-echo -n "Starting printer spooler: lpd"
-start-stop-daemon --start --quiet --exec /usr/sbin/lpd
-echo "."
- </example>
- in the script. If you have more than one daemon to
- start, you should do the following:
- <example compact="compact">
-echo -n "Starting remote file system services:"
-echo -n " nfsd"; start-stop-daemon --start --quiet nfsd
-echo -n " mountd"; start-stop-daemon --start --quiet mountd
-echo -n " ugidd"; start-stop-daemon --start --quiet ugidd
-echo "."
- </example>
- This makes it possible for the user to see what takes
- so long and when the final daemon has been started.
- You should be careful where to put spaces: in the
- example above the system administrator can easily
- comment out a line if he don't wants to start a
- specific daemon, while the displayed message still
- looks good.
- </p>
+ The <tt>Depends</tt> field should also be used if the
+ <prgn>postinst</prgn>, <prgn>prerm</prgn> or
+ <prgn>postrm</prgn> scripts require the package to be
+ present in order to run. Note, however, that the
+ <prgn>postrm</prgn> cannot rely on any non-essential
+ packages to be present during the <tt>purge</tt>
+ phase.
</item>
+ <tag><tt>Recommends</tt></tag>
<item>
- <p>When a system parameter is being set</p>
-
- <p>
- If you have to set up different system parameters
- during the system boot, you should use this format:
- <example compact="compact">
-Setting <var>parameter</var> to "<var>value</var>".
- </example>
- </p>
-
<p>
- You can use a statement such as the following to get
- the quotes right:
- <example compact="compact">
-echo "Setting DNS domainname to \"$domainname\"."
- </example>
+ This declares a strong, but not absolute, dependency.
</p>
<p>
- Note that the same symbol (<tt>"</tt>) is used for the left
- and right quotation marks. A grave accent (<tt>`</tt>) is
- not a quote character; neither is an apostrophe
- (<tt>'</tt>).
+ The <tt>Recommends</tt> field should list packages
+ that would be found together with this one in all but
+ unusual installations.
</p>
</item>
+ <tag><tt>Suggests</tt></tag>
<item>
- <p>When a daemon is stopped or restarted</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.
+ </item>
+
+ <tag><tt>Enhances</tt></tag>
+ <item>
+ 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.
+ </item>
+ <tag><tt>Pre-Depends</tt></tag>
+ <item>
<p>
- When you stop or restart a daemon, you should issue a
- message identical to the startup message, except that
- <tt>Starting</tt> is replaced with <tt>Stopping</tt>
- or <tt>Restarting</tt> respectively.
+ This field is like <tt>Depends</tt>, except that it
+ also forces <prgn>dpkg</prgn> to complete installation
+ of the packages named before even starting the
+ installation of the package which declares the
+ pre-dependency, as follows:
</p>
<p>
- For example, stopping the printer daemon will like
- like this:
- <example compact="compact">
-Stopping printer spooler: lpd.
- </example>
+ When a package declaring a pre-dependency is about to
+ be <em>unpacked</em> the pre-dependency can be
+ satisfied if the depended-on package is either fully
+ configured, <em>or even if</em> the depended-on
+ package(s) are only unpacked or half-configured,
+ provided that they have been configured correctly at
+ some point in the past (and not removed or partially
+ removed since). In this case, both the
+ previously-configured and currently unpacked or
+ half-configured versions must satisfy any version
+ clause in the <tt>Pre-Depends</tt> field.
</p>
- </item>
-
- <item>
- <p>When something is executed</p>
<p>
- There are several examples where you have to run a
- program at system startup or shutdown to perform a
- specific task, for example, setting the system's clock
- using <prgn>netdate</prgn> or killing all processes
- when the system shuts down. Your message should look
- like this:
- <example compact="compact">
-Doing something very useful...done.
- </example>
- You should print the <tt>done.</tt> immediately after
- the job has been completed, so that the user is
- informed why she has to wait. You can get this
- behavior by saying
- <example compact="compact">
-echo -n "Doing something very useful..."
-do_something
-echo "done."
- </example>
- in your script.
+ When the package declaring a pre-dependency is about
+ to be <em>configured</em>, the pre-dependency will be
+ treated as a normal <tt>Depends</tt>, that is, it will
+ be considered satisfied only if the depended-on
+ package has been correctly configured.
</p>
- </item>
- <item>
- <p>When the configuration is reloaded</p>
+ <p>
+ <tt>Pre-Depends</tt> should be used sparingly,
+ preferably only by packages whose premature upgrade or
+ installation would hamper the ability of the system to
+ continue with any upgrade that might be in progress.
+ </p>
<p>
- When a daemon is forced to reload its configuration
- files you should use the following format:
- <example compact="compact">
-Reloading <var>description</var> configuration...done.
- </example>
- where <var>description</var> is the same as in the
- daemon starting message.
+ <tt>Pre-Depends</tt> are also required if the
+ <prgn>preinst</prgn> script depends on the named
+ package. It is best to avoid this situation if
+ possible.
</p>
</item>
- </list>
+ </taglist>
</p>
- </sect>
-
- <sect>
- <heading>Cron jobs</heading>
-
- <p>
- Packages must not modify the configuration file
- <file>/etc/crontab</file>, and they must not modify the files in
- <file>/var/spool/cron/crontabs</file>.</p>
-
- <p>
- If a package wants to install a job that has to be executed
- via cron, it should place a file with the name of the
- package in one or more of the following directories:
- <example compact="compact">
-/etc/cron.daily
-/etc/cron.weekly
-/etc/cron.monthly
- </example>
- As these directory names imply, the files within them are
- executed on a daily, weekly, or monthly basis,
- respectively. The exact times are listed in
- <file>/etc/crontab</file>.</p>
<p>
- All files installed in any of these directories must be
- scripts (e.g., shell scripts or Perl scripts) so that they
- can easily be modified by the local system administrator.
- In addition, they should be treated as configuration
- files.
+ When selecting which level of dependency to use you should
+ consider how important the depended-on package is to the
+ functionality of the one declaring the dependency. Some
+ packages are composed of components of varying degrees of
+ importance. Such a package should list using
+ <tt>Depends</tt> the package(s) which are required by the
+ more important components. The other components'
+ requirements may be mentioned as Suggestions or
+ Recommendations, as appropriate to the components' relative
+ importance.
</p>
-
- <p>
- If a certain job has to be executed more frequently than
- daily, the package should install a file
- <file>/etc/cron.d/<var>package</var></file>. This file uses the
- same syntax as <file>/etc/crontab</file> and is processed by
- <prgn>cron</prgn> automatically. The file must also be
- treated as a configuration file. (Note that entries in the
- <file>/etc/cron.d</file> directory are not handled by
- <prgn>anacron</prgn>. Thus, you should only use this
- directory for jobs which may be skipped if the system is not
- running.)</p>
-
- <p>
- The scripts or crontab entries in these directories should
- check if all necessary programs are installed before they
- try to execute them. Otherwise, problems will arise when a
- package was removed but not purged since configuration files
- are kept on the system in this situation.</p>
</sect>
- <sect id="menus">
- <heading>Menus</heading>
+ <sect id="conflicts">
+ <heading>Conflicting binary packages - <tt>Conflicts</tt></heading>
<p>
- The Debian <tt>menu</tt> package provides a standard
- interface between packages providing applications and
- documents, and <em>menu programs</em> (either X window
- managers or text-based menu programs such as
- <prgn>pdmenu</prgn>).
+ When one binary package declares a conflict with another
+ using a <tt>Conflicts</tt> field, <prgn>dpkg</prgn> will
+ refuse to allow them to be installed on the system at the
+ same time.
</p>
<p>
- All packages that provide applications that need not be
- passed any special command line arguments for normal
- 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>.
+ If one package is to be installed, the other must be removed
+ first - if the package being installed is marked as
+ replacing (see <ref id="replaces">) the one on the system,
+ or the one on the system is marked as deselected, or both
+ packages are marked <tt>Essential</tt>, then
+ <prgn>dpkg</prgn> will automatically remove the package
+ which is causing the conflict, otherwise it will halt the
+ installation of the new package with an error. This
+ mechanism is specifically designed to produce an error when
+ the installed package is <tt>Essential</tt>, but the new
+ package is not.
</p>
<p>
- Menu entries should follow the current menu policy.
+ A package will not cause a conflict merely because its
+ configuration files are still installed; it must be at least
+ half-installed.
</p>
<p>
- The menu policy can be found in the <tt>menu-policy</tt>
- files in the <tt>debian-policy</tt> package.
- They are also available from the Debian web mirrors at
- <tt><url name="/doc/packaging-manuals/menu-policy/"
- id="http://www.debian.org/doc/packaging-manuals/menu-policy/"></tt>
- and from the Debian archive mirrors at
- <tt><url name="/doc/package-developer/menu-policy.txt.gz"
- id="http://ftp.debian.org/debian/doc/package-developer/menu-policy.txt.gz"></tt>.
+ A special exception is made for packages which declare a
+ conflict with their own package name, or with a virtual
+ package which they provide (see below): this does not
+ prevent their installation, and allows a package to conflict
+ with others providing a replacement for it. You use this
+ feature when you want the package in question to be the only
+ package providing some feature.
</p>
<p>
- Please also refer to the <em>Debian Menu System</em>
- documentation that comes with the <tt>menu</tt> package for
- information about how to register your applications and web
- documents.
+ A <tt>Conflicts</tt> entry should almost never have an
+ "earlier than" version clause. This would prevent
+ <prgn>dpkg</prgn> from upgrading or installing the package
+ which declared such a conflict until the upgrade or removal
+ of the conflicted-with package had been completed.
</p>
</sect>
- <sect id="mime">
- <heading>Multimedia handlers</heading>
+ <sect id="virtual"><heading>Virtual packages - <tt>Provides</tt>
+ </heading>
- <p>
- MIME (Multipurpose Internet Mail Extensions, RFCs 2045-2049)
- is a mechanism for encoding files and data streams and
- providing meta-information about them, in particular their
- type (e.g. audio or video) and format (e.g. PNG, HTML,
- MP3).
+ <p>
+ As well as the names of actual ("concrete") packages, the
+ package relationship fields <tt>Depends</tt>,
+ <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
+ <tt>Pre-Depends</tt>, <tt>Conflicts</tt>,
+ <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
+ <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>
+ may mention "virtual packages".
</p>
<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.
+ A <em>virtual package</em> is one which appears in the
+ <tt>Provides</tt> control file field of another package.
+ The effect is as if the package(s) which provide a
+ particular virtual package name had been listed by name
+ everywhere the virtual package name appears. (See also <ref
+ id="virtual_pkg">)
</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.
+ If there are both concrete and virtual packages of the same
+ name, then the dependency may be satisfied (or the conflict
+ caused) by either the concrete package with the name in
+ question or any other concrete package which provides the
+ virtual package with the name in question. This is so that,
+ for example, supposing we have
+ <example compact="compact">
+Package: foo
+Depends: bar
+ </example>
+ and someone else releases an enhanced version of the
+ <tt>bar</tt> package (for example, a non-US variant), they
+ can say:
+ <example compact="compact">
+Package: bar-plus
+Provides: bar
+ </example>
+ and the <tt>bar-plus</tt> package will now also satisfy the
+ dependency for the <tt>foo</tt> package.
</p>
<p>
- The MIME support policy can be found in the <tt>mime-policy</tt>
- files in the <tt>debian-policy</tt> package.
- They are also available from the Debian web mirrors at
- <tt><url name="/doc/packaging-manuals/mime-policy/"
- id="http://www.debian.org/doc/packaging-manuals/mime-policy/"></tt>
- and from the Debian archive mirrors at
- <tt><url name="/doc/package-developer/mime-policy.txt.gz"
- id="http://ftp.debian.org/debian/doc/package-developer/mime-policy.txt.gz"></tt>.
+ If a dependency or a conflict has a version number attached
+ then only real packages will be considered to see whether
+ the relationship is satisfied (or the prohibition violated,
+ for a conflict) - it is assumed that a real package which
+ provides the virtual package is not of the "right" version.
+ So, a <tt>Provides</tt> field may not contain version
+ numbers, and the version number of the concrete package
+ which provides a particular virtual package will not be
+ looked at when considering a dependency on or conflict with
+ the virtual package name.
</p>
- </sect>
-
- <sect>
- <heading>Keyboard configuration</heading>
-
<p>
- To achieve a consistent keyboard configuration so that all
- applications interpret a keyboard event the same way, all
- programs in the Debian distribution must be configured to
- comply with the following guidelines.
+ It is likely that the ability will be added in a future
+ release of <prgn>dpkg</prgn> to specify a version number for
+ each virtual package it provides. This feature is not yet
+ present, however, and is expected to be used only
+ infrequently.
</p>
<p>
- The following keys must have the specified interpretations:
-
- <taglist>
- <tag><tt><--</tt></tag>
- <item>delete the character to the left of the cursor</item>
-
- <tag><tt>Delete</tt></tag>
- <item>delete the character to the right of the cursor</item>
+ If you want to specify which of a set of real packages
+ should be the default to satisfy a particular dependency on
+ a virtual package, you should list the real package as an
+ alternative before the virtual one.
+ </p>
+ </sect>
- <tag><tt>Control+H</tt></tag>
- <item>emacs: the help prefix</item>
- </taglist>
- The interpretation of any keyboard events should be
- independent of the terminal that is used, be it a virtual
- console, an X terminal emulator, an rlogin/telnet session,
- etc.
- </p>
+ <sect id="replaces"><heading>Overwriting files and replacing
+ packages - <tt>Replaces</tt></heading>
<p>
- The following list explains how the different programs
- should be set up to achieve this:
+ Packages can declare in their control file that they should
+ overwrite files in certain other packages, or completely
+ replace other packages. The <tt>Replaces</tt> control file
+ field has these two distinct purposes.
</p>
- <p>
- <list>
- <item>
- <tt><--</tt> generates <tt>KB_BackSpace</tt> in X.
- </item>
+ <sect1><heading>Overwriting files in other packages</heading>
- <item>
- <tt>Delete</tt> generates <tt>KB_Delete</tt> in X.
- </item>
+ <p>
+ Firstly, as mentioned before, it is usually an error for a
+ package to contain files which are on the system in
+ another package.
+ </p>
- <item>
- X translations are set up to make
- <tt>KB_Backspace</tt> generate ASCII DEL, and to make
- <tt>KB_Delete</tt> generate <tt>ESC [ 3 ~</tt> (this
- is the vt220 escape code for the "delete character"
- key). This must be done by loading the X resources
- using <prgn>xrdb</prgn> on all local X displays, not
- using the application defaults, so that the
- translation resources used correspond to the
- <prgn>xmodmap</prgn> settings.
- </item>
+ <p>
+ However, if the overwriting package declares that it
+ <tt>Replaces</tt> the one containing the file being
+ overwritten, then <prgn>dpkg</prgn> will replace the file
+ from the old package with that from the new. The file
+ will no longer be listed as "owned" by the old package.
+ </p>
- <item>
- The Linux console is configured to make
- <tt><--</tt> generate DEL, and <tt>Delete</tt>
- generate <tt>ESC [ 3 ~</tt>.
- </item>
+ <p>
+ If a package is completely replaced in this way, so that
+ <prgn>dpkg</prgn> does not know of any files it still
+ contains, it is considered to have "disappeared". It will
+ be marked as not wanted on the system (selected for
+ removal) and not installed. Any <tt>conffile</tt>s
+ details noted for the package will be ignored, as they
+ will have been taken over by the overwriting package. The
+ package's <prgn>postrm</prgn> script will be run with a
+ special argument to allow the package to do any final
+ cleanup required. See <ref id="mscriptsinstact">.
+ </p>
- <item>
- X applications are configured so that <tt><</tt>
- deletes left, and <tt>Delete</tt> deletes right. Motif
- applications already work like this.
- </item>
+ <p>
+ If an installed package, <tt>foo</tt> say, declares that
+ it replaces another, <tt>bar</tt>, and an attempt is made
+ to install <tt>bar</tt>, <prgn>dpkg</prgn> will discard
+ files in the <tt>bar</tt> package which would overwrite
+ those already present in <tt>foo</tt>. This is so that
+ you can install an older version of a package without
+ problems.
+ </p>
- <item>
- Terminals should have <tt>stty erase ^?</tt> .
- </item>
+ <p>
+ For this usage of <tt>Replaces</tt>, virtual packages (see
+ <ref id="virtual">) are not considered when looking at a
+ <tt>Replaces</tt> field - the packages declared as being
+ replaced must be mentioned by their real names.
+ </p>
- <item>
- 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>.
- </item>
+ <p>
+ Furthermore, this usage of <tt>Replaces</tt> only takes
+ effect when both packages are at least partially on the
+ system at once, so that it can only happen if they do not
+ conflict or if the conflict has been overridden.
+ </p>
- <item>
- 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.
- </item>
+ </sect1>
- <item>
- 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".
- </item>
+ <sect1><heading>Replacing whole packages, forcing their
+ removal</heading>
- </list>
- </p>
+ <p>
+ Secondly, <tt>Replaces</tt> allows the packaging system to
+ resolve which package should be removed when there is a
+ conflict - see <ref id="conflicts">. This usage only
+ takes effect when the two packages <em>do</em> conflict,
+ so that the two usages of this field do not interfere with
+ each other.
+ </p>
+
+ <p>
+ In this situation, the package declared as being replaced
+ can be a virtual package, so for example, all mail
+ transport agents (MTAs) would have the following fields in
+ their control files:
+ <example compact="compact">
+Provides: mail-transport-agent
+Conflicts: mail-transport-agent
+Replaces: mail-transport-agent
+ </example>
+ ensuring that only one MTA can be installed at any one
+ time.
+ </sect1>
+ </sect>
+
+ <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>
<p>
- This will solve the problem except for the following
- cases:
+ Source packages that require certain binary packages to be
+ 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
+ <tt>Build-Conflicts-Indep</tt> control file fields.
+ </p>
+
+ <p>
+ Build-dependencies on "build-essential" binary packages can be
+ omitted. Please see <ref id="pkg-relations"> for more information.
</p>
<p>
- <list>
- <item>
- 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.
- </item>
-
- <item>
- 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.
- </item>
+ The dependencies and conflicts they define must be satisfied
+ (as defined earlier for binary packages) in order to invoke
+ the targets in <tt>debian/rules</tt>, as follows:<footnote>
+ <p>
+ If you make "build-arch" or "binary-arch", you need
+ Build-Depends. If you make "build-indep" or
+ "binary-indep", you need Build-Depends and
+ Build-Depends-Indep. If you make "build" or "binary",
+ you need both.
+ </p>
+ <p>
+ There is no Build-Depends-Arch; the autobuilders will
+ only need the Build-Depends if they know how to build
+ only build-arch and binary-arch. Anyone building the
+ build-indep/binary-indep targets is basically assumed to
+ be building the whole package and so installs all build
+ dependencies.
+ </p>
+ <p>
+ The purpose of the original split, I recall, was so that
+ the autobuilders wouldn't need to install extra packages
+ needed only for the binary-indep targets. But without a
+ build-arch/build-indep split, this didn't work, since
+ most of the work is done in the build target, not in the
+ binary target.
+ </p>
+ </footnote>
+ <taglist>
+ <tag><tt>Build-Depends</tt>, <tt>Build-Conflicts</tt></tag>
<item>
- Some systems (including previous Debian versions) use
- <prgn>xmodmap</prgn> to arrange for both
- <tt><--</tt> and <tt>Delete</tt> to generate
- <tt>KB_Delete</tt>. We can change the behavior of
- their X clients using the same X resources that we use
- to do it for our own clients, or configure our clients
- using their resources when things are the other way
- around. On displays configured like this
- <tt>Delete</tt> will not work, but <tt><--</tt>
- will.
+ 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>.
</item>
-
+ <tag><tt>Build-Depends-Indep</tt>,
+ <tt>Build-Conflicts-Indep</tt></tag>
<item>
- 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.
+ 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>.
</item>
- </list>
+ </taglist>
</p>
+
</sect>
- <sect>
- <heading>Environment variables</heading>
+ </chapt>
- <p>
- A program must not depend on environment variables to get
- 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>
+
+ <chapt id="sharedlibs"><heading>Shared libraries</heading>
+
+ <p>
+ Packages containing shared libraries must be constructed with
+ a little care to make sure that the shared library is always
+ available. This is especially important for packages whose
+ shared libraries are vitally important, such as the C library
+ (currently <tt>libc6</tt>).
+ </p>
+
+ <p>
+ Packages involving shared libraries should be split up into
+ several binary packages. This section mostly deals with how
+ this separation is to be accomplished; rules for files within
+ the shared library packages are in <ref id="libraries"> instead.
+ </p>
+
+ <sect id="sharedlibs-runtime">
+ <heading>Run-time shared libraries</heading>
+
+ <p>
+ The run-time shared library needs to be placed in a package called
+ <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>
+ 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>.
+ </footnote>.
+ Alternatively, if it would be confusing to directly append
+ <var>soversion</var> to <var>libraryname</var> (e.g. because
+ <var>libraryname</var> itself ends in a number), you may use
+ <package><var>libraryname</var>-<var>soversion</var></package> and
+ <package><var>libraryname</var>-<var>soversion</var>-dev</package>
+ instead.
+ </p>
+
+ <p>
+ If you have several shared libraries built from the same
+ source tree you may lump them all together into a single
+ shared library package, provided that you change all of
+ their sonames at once (so that you don't get filename
+ clashes if you try to install different versions of the
+ combined shared libraries package).
+ </p>
+
+ <p>
+ 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
+ renamed or re-linked by any <prgn>prerm</prgn> or
+ <prgn>postrm</prgn> scripts; <prgn>dpkg</prgn> will take care
+ of renaming things safely without affecting running programs,
+ and attempts to interfere with this are likely to lead to
+ problems.
+ </p>
+
+ <p>
+ Shared libraries should not be installed executable, since
+ the dynamic linker does not require this and trying to
+ execute a shared library usually results in a core dump.
+ </p>
+
+ <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
+ 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>
+ 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
+ <prgn>dpkg</prgn> comes to install the symlink
+ (overwriting the previous symlink pointing at an older
+ version of the library), the new shared library is already
+ in place. In the past, this was achieved by creating the
+ library in the temporary packaging directory before
+ creating the symlink. Unfortunately, this was not always
+ effective, since the building of the tar file in the
+ <file>.deb</file> depended on the behavior of the underlying
+ file system. Some file systems (such as reiserfs) reorder
+ the files so that the order of creation is forgotten.
+ Since version 1.7.0, <prgn>dpkg</prgn>
+ 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.
+ </footnote>
+ </p>
+
+ <sect1 id="ldconfig">
+ <heading><tt>ldconfig</tt></heading>
<p>
- If a program usually depends on environment variables for its
- configuration, the program should be changed to fall back to
- a reasonable default configuration if these environment
- variables are not present. If this cannot be done easily
- (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.
+ 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>/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>
+ </footnote>
+ must use <prgn>ldconfig</prgn> to update the shared library
+ system.
</p>
<p>
- Here is an example of a wrapper script for this purpose:
+ 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>
- <example compact="compact">
-#!/bin/sh
-BAR=${BAR:-/var/lib/fubar}
-export BAR
-exec /usr/lib/foo/foo "$@"
- </example>
- </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>
- 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>
+ 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>
- </chapt>
+ <sect id="sharedlibs-runtime-progs">
+ <heading>Run-time support programs</heading>
+ <p>
+ If your package has some run-time support programs which use
+ the shared library you must not put them in the shared
+ library package. If you do that then you won't be able to
+ install several versions of the shared library without
+ getting filename clashes.
+ </p>
- <chapt id="files">
- <heading>Files</heading>
+ <p>
+ Instead, either create another package for the runtime binaries
+ (this package might typically be named
+ <package><var>libraryname</var>-runtime</package>; note the absence
+ of the <var>soversion</var> in the package name), or if the
+ development package is small, include them in there.
+ </p>
+ </sect>
- <sect>
- <heading>Binaries</heading>
+ <sect id="sharedlibs-static">
+ <heading>Static libraries</heading>
- <p>
- Two different packages must not install programs with
- different functionality but with the same filenames. (The
- case of two programs having the same functionality but
- different implementations is handled via "alternatives" or
- the "Conflicts" mechanism. See <ref id="maintscripts"> and
- <ref id="conflicts"> respectively.) If this case happens,
- one of the programs must be renamed. The maintainers should
- report this to the <tt>debian-devel</tt> mailing list and
- try to find a consensus about which program will have to be
- renamed. If a consensus cannot be reached, <em>both</em>
- programs must be renamed.
- </p>
+ <p>
+ The static library (<file><var>libraryname.a</var></file>)
+ is usually provided in addition to the shared version.
+ It is placed into the development package (see below).
+ </p>
- <p>
- By default, when a package is being built, any binaries
- created should include debugging information, as well as
- being compiled with optimization. You should also turn on
- as many reasonable compilation warnings as possible; this
- makes life easier for porters, who can then look at build
- logs for possible problems. For the C programming language,
- this means the following compilation parameters should be
- used:
- <example compact="compact">
-CC = gcc
-CFLAGS = -O2 -g -Wall # sane warning options vary between programs
-LDFLAGS = # none
-install -s # (or use strip on the files in debian/tmp)
- </example>
- </p>
+ <p>
+ In some cases, it is acceptable for a library to be
+ available in static form only; these cases include:
+ <list>
+ <item>libraries for languages whose shared library support
+ is immature or unstable</item>
+ <item>libraries whose interfaces are in flux or under
+ development (commonly the case when the library's
+ major version number is zero, or where the ABI breaks
+ across patchlevels)</item>
+ <item>libraries which are explicitly intended to be
+ available only in static form by their upstream
+ author(s)</item>
+ </list>
+ </p>
- <p>
- Note that by default all installed binaries should be stripped,
- either by using the <tt>-s</tt> flag to
- <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>
+ <sect id="sharedlibs-dev">
+ <heading>Development files</heading>
- <p>
- Although binaries in the build tree should be compiled with
- debugging information by default, it can often be difficult
- to debug programs if they are also subjected to compiler
- optimization. For this reason, it is recommended to support
- the standardized environment
- variable <tt>DEB_BUILD_OPTIONS</tt>. This variable can
- contain several flags to change how a package is compiled
- and built.
- </p>
+ <p>
+ The development files associated to a shared library need to be
+ placed in a package called
+ <package><var>libraryname</var><var>soversion</var>-dev</package>,
+ or if you prefer only to support one development version at a
+ time, <package><var>libraryname</var>-dev</package>.
+ </p>
- <p>
- <taglist>
- <tag>noopt</tag>
- <item>
- The presence of this string means that the package
- 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.
- </item>
- <tag>nostrip</tag>
- <item>
- 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.
- </item>
- </taglist>
- </p>
+ <p>
+ In case several development versions of a library exist, you may
+ need to use <prgn>dpkg</prgn>'s Conflicts mechanism (see
+ <ref id="conflicts">) to ensure that the user only installs one
+ development version at a time (as different development versions are
+ likely to have the same header files in them, which would cause a
+ filename clash if both were installed).
+ </p>
- <p>
- The following makefile snippet is an example of how one may
- implement the build options; you will probably have to
- massage this example in order to make it work for your
- package.
- <example compact="compact">
-CFLAGS = -Wall -g
-INSTALL = install
-INSTALL_FILE = $(INSTALL) -p -o root -g root -m 644
-INSTALL_PROGRAM = $(INSTALL) -p -o root -g root -m 755
-INSTALL_SCRIPT = $(INSTALL) -p -o root -g root -m 755
-INSTALL_DIR = $(INSTALL) -p -d -o root -g root -m 755
+ <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
+ from <file>/usr/lib/libgdbm.so</file> to
+ <file>libgdbm.so.1.7.3</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>
+ </sect>
-ifneq (,$(findstring noopt,$(DEB_BUILD_OPTIONS)))
-CFLAGS += -O0
-else
-CFLAGS += -O2
-endif
-ifeq (,$(findstring nostrip,$(DEB_BUILD_OPTIONS)))
-INSTALL_PROGRAM += -s
-endif
- </example>
- </p>
+ <sect id="sharedlibs-intradeps">
+ <heading>Dependencies between the packages of the same library</heading>
<p>
- It is up to the package maintainer to decide what
- compilation options are best for the package. Certain
- binaries (such as computationally-intensive programs) will
- function better with certain flags (<tt>-O3</tt>, for
- example); feel free to use them. Please use good judgment
- here. Don't use flags for the sake of it; only use them
- if there is good reason to do so. Feel free to override
- the upstream author's ideas about which compilation
- options are best: they are often inappropriate for our
- environment.
+ 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>
</sect>
-
- <sect id="libraries">
- <heading>Libraries</heading>
+ <sect id="sharedlibs-shlibdeps">
+ <heading>Dependencies between the library and other packages -
+ the <tt>shlibs</tt> system</heading>
<p>
- The shared version of a library must be compiled with
- <tt>-fPIC</tt>, and the static version must not be. In other
- words, each source unit (<tt>*.c</tt>, for example, for C files)
- will need to be compiled twice.
+ If a package contains a binary or library which links to a
+ shared library, we must ensure that when the package is
+ installed on the system, all of the libraries needed are
+ also installed. This requirement led to the creation of the
+ <tt>shlibs</tt> system, which is very simple in its design:
+ any package which <em>provides</em> a shared library also
+ provides information on the package dependencies required to
+ ensure the presence of this library, and any package which
+ <em>uses</em> a shared library uses this information to
+ determine the dependencies it requires. The files which
+ contain the mapping from shared libraries to the necessary
+ dependency information are called <file>shlibs</file> files.
</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>
+ Thus, when a package is built which contains any shared
+ libraries, it must provide a <file>shlibs</file> file for other
+ packages to use, and when a package is built which contains
+ any shared libraries or compiled binaries, it must run
+ <prgn>dpkg-shlibdeps</prgn> on these to determine the
+ libraries used and hence the dependencies needed by this
+ package.<footnote>
+ <p>
+ In the past, the shared libraries linked to were
+ determined by calling <prgn>ldd</prgn>, but now
+ <prgn>objdump</prgn> is used to do this. The only
+ change this makes to package building is that
+ <prgn>dpkg-shlibdeps</prgn> must also be run on shared
+ libraries, whereas in the past this was unnecessary.
+ The rest of this footnote explains the advantage that
+ this method gives.
+ </p>
- <p>
- All installed shared libraries should be stripped with
- <example compact="compact">
-strip --strip-unneeded <var>your-lib</var>
- </example>
- (The option <tt>--strip-unneeded</tt> makes
- <prgn>strip</prgn> remove only the symbols which aren't
- needed for relocation processing.) Shared libraries can
- function perfectly well when stripped, since the symbols for
- dynamic linking are in a separate part of the ELF object
- file.<footnote>
- 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
+ <p>
+ We say that a binary <tt>foo</tt> <em>directly</em> uses
+ a library <tt>libbar</tt> if it is explicitly linked
+ with that library (that is, it uses the flag
+ <tt>-lbar</tt> during the linking stage). Other
+ libraries that are needed by <tt>libbar</tt> are linked
+ <em>indirectly</em> to <tt>foo</tt>, and the dynamic
+ linker will load them automatically when it loads
+ <tt>libbar</tt>. A package should depend on
+ the libraries it directly uses, and the dependencies for
+ those libraries should automatically pull in the other
libraries.
- </footnote>
- </p>
+ </p>
- <p>
- Note that under some circumstances it may be useful to
- install a shared library unstripped, for example when
- building a separate package to support debugging.
- </p>
+ <p>
+ Unfortunately, the <prgn>ldd</prgn> program shows both
+ the directly and indirectly used libraries, meaning that
+ the dependencies determined included both direct and
+ indirect dependencies. The use of <prgn>objdump</prgn>
+ avoids this problem by determining only the directly
+ used libraries.
+ </p>
- <p>
- Shared object files (often <file>.so</file> files) that are not
- public libraries, that is, they are not meant to be linked
- to by third party executables (binaries of other packages),
- should be installed in subdirectories of the
- <file>/usr/lib</file> directory. Such files are exempt from the
- rules that govern ordinary shared libraries, except that
- they must not be installed executable and should be
- stripped.<footnote>
- 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>
+ A good example of where this helps is the following. We
+ could update <tt>libimlib</tt> with a new version that
+ supports a new graphics format called dgf (but retaining
+ the same major version number). If we used the old
+ <prgn>ldd</prgn> method, every package that uses
+ <tt>libimlib</tt> would need to be recompiled so it
+ would also depend on <tt>libdgf</tt> or it wouldn't run
+ due to missing symbols. However with the new system,
+ packages using <tt>libimlib</tt> can rely on
+ <tt>libimlib</tt> itself having the dependency on
+ <tt>libdgf</tt> and so they would not need rebuilding.
+ </p>
</footnote>
</p>
<p>
- Packages containing shared libraries that may be linked to
- by other packages' binaries, but which for some
- <em>compelling</em> reason can not be installed in
- <file>/usr/lib</file> directory, may install the shared library
- files in subdirectories of the <file>/usr/lib</file> directory,
- in which case they should arrange to add that directory in
- <file>/etc/ld.so.conf</file> in the package's post-installation
- script, and remove it in the package's post-removal script.
+ In the following sections, we will first describe where the
+ various <tt>shlibs</tt> files are to be found, then how to
+ use <prgn>dpkg-shlibdeps</prgn>, and finally the
+ <tt>shlibs</tt> file format and how to create them if your
+ package contains a shared library.
</p>
- <p>
- An ever increasing number of packages are using
- <prgn>libtool</prgn> to do their linking. The latest GNU
- libtools (>= 1.3a) can take advantage of the metadata in the
- installed <prgn>libtool</prgn> archive files (<file>*.la</file>
- files). The main advantage of <prgn>libtool</prgn>'s
- <file>.la</file> files is that it allows <prgn>libtool</prgn> to
- store and subsequently access metadata with respect to the
- libraries it builds. <prgn>libtool</prgn> will search for
- those files, which contain a lot of useful information about
- a library (such as library dependency information for static
- linking). Also, they're <em>essential</em> for programs
- using <tt>libltdl</tt>.<footnote>
- Although <prgn>libtool</prgn> is fully capable of
- linking against shared libraries which don't have
- <tt>.la</tt> files, as it is a mere shell script it can
- add considerably to the build time of a
- <prgn>libtool</prgn>-using package if that shell script
- has to derive all this information from first principles
- for each library every time it is linked. With the
- advent of <prgn>libtool</prgn> version 1.4 (and to a
- lesser extent <prgn>libtool</prgn> version 1.3), the
- <file>.la</file> files also store information about
- inter-library dependencies which cannot necessarily be
- derived after the <file>.la</file> file is deleted.
- </footnote>
- </p>
+ <sect1>
+ <heading>The <tt>shlibs</tt> files present on the system</heading>
<p>
- Packages that use <prgn>libtool</prgn> to create shared
- libraries should include the <file>.la</file> files in the
- <tt>-dev</tt> package, unless the package relies on
- <tt>libtool</tt>'s <tt>libltdl</tt> library, in which case
- the <tt>.la</tt> files must go in the run-time library
- package.
+ There are several places where <tt>shlibs</tt> files are
+ found. The following list gives them in the order in which
+ they are read by <prgn>dpkg-shlibdeps</prgn>. (The first
+ one which gives the required information is used.)
</p>
<p>
- You must make sure that you use only released versions of
- shared libraries to build your packages; otherwise other
- users will not be able to run your binaries
- properly. Producing source packages that depend on
- unreleased compilers is also usually a bad
- idea.
- </p>
- </sect>
+ <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">).
+ </p>
+ </item>
- <sect>
- <heading>Shared libraries</heading>
- <p>
- This section has moved to <ref id="sharedlibs">.
- </p>
- </sect>
+ <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
+ administrator.
+ </p>
+ </item>
- <sect id="scripts">
- <heading>Scripts</heading>
+ <item>
+ <p><file>DEBIAN/shlibs</file> files in the "build directory"</p>
- <p>
- All command scripts, including the package maintainer
- scripts inside the package and used by <prgn>dpkg</prgn>,
- should have a <tt>#!</tt> line naming the shell to be used
- to interpret them.
- </p>
+ <p>
+ When packages are being built, any
+ <file>debian/shlibs</file> files are copied into the
+ control file area of the temporary build directory and
+ given the name <file>shlibs</file>. These files give
+ details of any shared libraries included in the
+ package.<footnote>
+ An example may help here. Let us say that the
+ source package <tt>foo</tt> generates two binary
+ packages, <tt>libfoo2</tt> and
+ <tt>foo-runtime</tt>. When building the binary
+ packages, the two packages are created in the
+ directories <file>debian/libfoo2</file> and
+ <file>debian/foo-runtime</file> respectively.
+ (<file>debian/tmp</file> could be used instead of one
+ of these.) Since <tt>libfoo2</tt> provides the
+ <tt>libfoo</tt> shared library, it will require a
+ <tt>shlibs</tt> file, which will be installed in
+ <file>debian/libfoo2/DEBIAN/shlibs</file>, eventually
+ to become
+ <file>/var/lib/dpkg/info/libfoo2.shlibs</file>. Then
+ when <prgn>dpkg-shlibdeps</prgn> is run on the
+ executable
+ <file>debian/foo-runtime/usr/bin/foo-prog</file>, it
+ will examine the
+ <file>debian/libfoo2/DEBIAN/shlibs</file> file to
+ determine whether <tt>foo-prog</tt>'s library
+ dependencies are satisfied by any of the libraries
+ provided by <tt>libfoo2</tt>. For this reason,
+ <prgn>dpkg-shlibdeps</prgn> must only be run once
+ all of the individual binary packages'
+ <tt>shlibs</tt> files have been installed into the
+ build directory.
+ </footnote>
+ </p>
+ </item>
- <p>
- In the case of Perl scripts this should be
- <tt>#!/usr/bin/perl</tt>.
+ <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
+ maintained by the relevant package maintainers.
+ </p>
+ </item>
+
+ <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.
+ It was used when the <file>shlibs</file> setup was first
+ introduced, but it is now normally empty. It is
+ maintained by the <tt>dpkg</tt> maintainer.
+ </p>
+ </item>
+ </list>
</p>
+ </sect1>
+
+ <sect1>
+ <heading>How to use <prgn>dpkg-shlibdeps</prgn> and the
+ <file>shlibs</file> files</heading>
<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.
+ Put a call to <prgn>dpkg-shlibdeps</prgn> into your
+ <file>debian/rules</file> file. If your package contains only
+ compiled binaries and libraries (but no scripts), you can
+ use a command such as:
+ <example compact="compact">
+dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* \
+ debian/tmp/usr/lib/*
+ </example>
+ Otherwise, you will need to explicitly list the compiled
+ binaries and libraries.<footnote>
+ 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.
+ </footnote>
</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>
- 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
- policy, the Linux kernel source, many Debian scripts,
- etc.). This <tt>echo -n</tt> mechanism is valid but not
- required under POSIX, hence this explicit addition.
- Also, rumour has it that this shall be mandated under
- the LSB anyway.
- </footnote>
- Thus, shell scripts specifying <file>/bin/sh</file> as
- interpreter should only use POSIX features. If a script
- requires non-POSIX features from the shell interpreter, the
- appropriate shell must be specified in the first line of the
- script (e.g., <tt>#!/bin/bash</tt>) and the package must
- depend on the package providing the shell (unless the shell
- package is marked "Essential", as in the case of
- <prgn>bash</prgn>).
+ This command puts the dependency information into the
+ <file>debian/substvars</file> file, which is then used by
+ <prgn>dpkg-gencontrol</prgn>. You will need to place a
+ <tt>${shlib:Depends}</tt> variable in the <tt>Depends</tt>
+ field in the control file for this to work.
</p>
<p>
- You may wish to restrict your script to POSIX features when
- possible so that it may use <file>/bin/sh</file> as its
- interpreter. If your script works with <prgn>dash</prgn>
- (originally called <prgn>ash</prgn>), it's probably POSIX
- compliant, but if you are in doubt, use
- <file>/bin/bash</file>.
+ If <prgn>dpkg-shlibdeps</prgn> doesn't complain, you're
+ done. If it does complain you might need to create your own
+ <file>debian/shlibs.local</file> file, as explained below (see
+ <ref id="shlibslocal">).
</p>
<p>
- Perl scripts should check for errors when making any
- system calls, including <tt>open</tt>, <tt>print</tt>,
- <tt>close</tt>, <tt>rename</tt> and <tt>system</tt>.
+ If you have multiple binary packages, you will need to call
+ <prgn>dpkg-shlibdeps</prgn> on each one which contains
+ compiled libraries or binaries. In such a case, you will
+ need to use the <tt>-T</tt> option to the <tt>dpkg</tt>
+ utilities to specify a different <file>substvars</file> file.
+ For more details on this and other options, see <manref
+ name="dpkg-shlibdeps" section="1">.
</p>
+ </sect1>
+
+ <sect1 id="shlibs">
+ <heading>The <file>shlibs</file> File Format</heading>
<p>
- <prgn>csh</prgn> and <prgn>tcsh</prgn> should be avoided as
- scripting languages. See <em>Csh Programming Considered
- Harmful</em>, one of the <tt>comp.unix.*</tt> FAQs, which
- 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
- <prgn>c-shell</prgn> virtual package.
+ Each <file>shlibs</file> file has the same format. Lines
+ beginning with <tt>#</tt> are considered to be comments and
+ are ignored. Each line is of the form:
+ <example compact="compact">
+<var>library-name</var> <var>soname-version-number</var> <var>dependencies ...</var>
+ </example>
</p>
<p>
- 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.
+ We will explain this by reference to the example of the
+ <tt>zlib1g</tt> package, which (at the time of writing)
+ installs the shared library <file>/usr/lib/libz.so.1.1.3</file>.
</p>
<p>
- The Debian base system provides the <prgn>tempfile</prgn>
- and <prgn>mktemp</prgn> utilities for use by scripts for
- this purpose.
+ <var>library-name</var> is the name of the shared library,
+ in this case <tt>libz</tt>. (This must match the name part
+ of the soname, see below.)
</p>
- </sect>
-
-
- <sect>
- <heading>Symbolic links</heading>
<p>
- In general, symbolic links within a top-level directory
- should be relative, and symbolic links pointing from one
- top-level directory into another should be absolute. (A
- top-level directory is a sub-directory of the root
- directory <file>/</file>.)
+ <var>soname-version-number</var> is the version part of the
+ soname of the library. The soname is the thing that must
+ exactly match for the library to be recognized by the
+ dynamic linker, and is usually of the form
+ <tt><var>name</var>.so.<var>major-version</var></tt>, in our
+ example, <tt>libz.so.1</tt>.<footnote>
+ This can be determined using the command
+ <example compact="compact">
+objdump -p /usr/lib/libz.so.1.1.3 | grep SONAME
+ </example>
+ </footnote>
+ The version part is the part which comes after
+ <tt>.so.</tt>, so in our case, it is <tt>1</tt>.
</p>
<p>
- In addition, symbolic links should be specified as short as
- possible, i.e., link targets like <file>foo/../bar</file> are
- deprecated.
+ <var>dependencies</var> has the same syntax as a dependency
+ field in a binary package control file. It should give
+ details of which packages are required to satisfy a binary
+ built against the version of the library contained in the
+ package. See <ref id="depsyntax"> for details.
</p>
<p>
- Note that when creating a relative link using
- <prgn>ln</prgn> it is not necessary for the target of the
- link to exist relative to the working directory you're
- running <prgn>ln</prgn> from, nor is it necessary to change
- directory to the directory where the link is to be made.
- Simply include the string that should appear as the target
- of the link (this will be a pathname relative to the
- directory in which the link resides) as the first argument
- to <prgn>ln</prgn>.
+ In our example, if the first version of the <tt>zlib1g</tt>
+ package which contained a minor number of at least
+ <tt>1.3</tt> was <var>1:1.1.3-1</var>, then the
+ <tt>shlibs</tt> entry for this library could say:
+ <example compact="compact">
+libz 1 zlib1g (>= 1:1.1.3)
+ </example>
+ The version-specific dependency is to avoid warnings from
+ the dynamic linker about using older shared libraries with
+ newer binaries.
</p>
+ </sect1>
+
+ <sect1>
+ <heading>Providing a <file>shlibs</file> file</heading>
<p>
- For example, in your <prgn>Makefile</prgn> or
- <file>debian/rules</file>, you can do things like:
+ If your package provides a shared library, you should create
+ a <file>shlibs</file> file following the format described above.
+ It is usual to call this file <file>debian/shlibs</file> (but if
+ you have multiple binary packages, you might want to call it
+ <file>debian/shlibs.<var>package</var></file> instead). Then
+ let <file>debian/rules</file> install it in the control area:
<example compact="compact">
-ln -fs gcc $(prefix)/bin/cc
-ln -fs gcc debian/tmp/usr/bin/cc
-ln -fs ../sbin/sendmail $(prefix)/bin/runq
-ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
+install -m644 debian/shlibs debian/tmp/DEBIAN
+ </example>
+ or, in the case of a multi-binary package:
+ <example compact="compact">
+install -m644 debian/shlibs.<var>package</var> debian/<var>package</var>/DEBIAN/shlibs
</example>
+ An alternative way of doing this is to create the
+ <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>
+ This is what <prgn>dh_makeshlibs</prgn> in the
+ <tt>debhelper</tt> suite does.
+ </footnote>
+ since the <file>debian/shlibs</file> file itself is ignored by
+ <prgn>dpkg-shlibdeps</prgn>.
</p>
<p>
- A symbolic link pointing to a compressed file should always
- have the same file extension as the referenced file. (For
- example, if a file <file>foo.gz</file> is referenced by a
- symbolic link, the filename of the link has to end with
- "<file>.gz</file>" too, as in <file>bar.gz</file>.)
+ As <prgn>dpkg-shlibdeps</prgn> reads the
+ <file>DEBIAN/shlibs</file> files in all of the binary packages
+ being built from this source package, all of the
+ <file>DEBIAN/shlibs</file> files should be installed before
+ <prgn>dpkg-shlibdeps</prgn> is called on any of the binary
+ packages.
</p>
- </sect>
+ </sect1>
- <sect>
- <heading>Device files</heading>
+ <sect1 id="shlibslocal">
+ <heading>Writing the <file>debian/shlibs.local</file> file</heading>
<p>
- Packages must not include device files in the package file
- tree.
+ This file is intended only as a <em>temporary</em> fix if
+ your binaries or libraries depend on a library whose package
+ does not yet provide a correct <file>shlibs</file> file.
</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>
- This notification could be done via a (low-priority)
- debconf message, or an echo (printf) statement.
- </footnote>.
+ We will assume that you are trying to package a binary
+ <tt>foo</tt>. When you try running
+ <prgn>dpkg-shlibdeps</prgn> you get the following error
+ message (<tt>-O</tt> displays the dependency information on
+ <tt>stdout</tt> instead of writing it to
+ <tt>debian/substvars</tt>, and the lines have been wrapped
+ for ease of reading):
+ <example compact="compact">
+$ dpkg-shlibdeps -O debian/tmp/usr/bin/foo
+dpkg-shlibdeps: warning: unable to find dependency
+ information for shared library libbar (soname 1,
+ path /usr/lib/libbar.so.1, dependency field Depends)
+shlibs:Depends=libc6 (>= 2.2.2-2)
+ </example>
+ You can then run <prgn>ldd</prgn> on the binary to find the
+ full location of the library concerned:
+ <example compact="compact">
+$ ldd foo
+libbar.so.1 => /usr/lib/libbar.so.1 (0x4001e000)
+libc.so.6 => /lib/libc.so.6 (0x40032000)
+/lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
+ </example>
+ So the <prgn>foo</prgn> binary depends on the
+ <prgn>libbar</prgn> shared library, but no package seems to
+ provide a <file>*.shlibs</file> file handling
+ <file>libbar.so.1</file> in <file>/var/lib/dpkg/info/</file>. Let's
+ determine the package responsible:
+ <example compact="compact">
+$ dpkg -S /usr/lib/libbar.so.1
+bar1: /usr/lib/libbar.so.1
+$ dpkg -s bar1 | grep Version
+Version: 1.0-1
+ </example>
+ This tells us that the <tt>bar1</tt> package, version 1.0-1,
+ is the one we are using. Now we can file a bug against the
+ <tt>bar1</tt> package and create our own
+ <file>debian/shlibs.local</file> to locally fix the problem.
+ Including the following line into your
+ <file>debian/shlibs.local</file> file:
+ <example compact="compact">
+libbar 1 bar1 (>= 1.0-1)
+ </example>
+ should allow the package build to work.
</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.
+ As soon as the maintainer of <tt>bar1</tt> provides a
+ correct <file>shlibs</file> file, you should remove this line
+ from your <file>debian/shlibs.local</file> file. (You should
+ probably also then have a versioned <tt>Build-Depends</tt>
+ on <tt>bar1</tt> to help ensure that others do not have the
+ same problem building your package.)
</p>
+ </sect1>
- <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>
</sect>
- <sect id="config-files">
- <heading>Configuration files</heading>
+ </chapt>
+
+
+ <chapt id="opersys"><heading>The Operating System</heading>
+
+ <sect>
+ <heading>Filesystem hierarchy</heading>
+
+
+ <sect1 id="fhs">
+ <heading>Filesystem Structure</heading>
+
+ <p>
+ The location of all installed files and directories must
+ comply with the Filesystem Hierarchy Standard (FHS),
+ version 2.1, except where doing so would violate other
+ terms of Debian Policy. The version of this document
+ referred here can be found in the <tt>debian-policy</tt>
+ package or on
+ <url id="http://www.debian.org/doc/packaging-manuals/fhs/"
+ name="FHS (Debian copy)"> alongside this manual (or, if
+ you have the <package>debian-policy</package> installed,
+ you can try <url
+ id="file:///usr/share/doc/debian-policy/fhs/" name="FHS
+ (local copy)">). The
+ latest version, which may be a more recent version, may
+ be found on
+ <url id="http://www.pathname.com/fhs/" name="FHS (upstream)">.
+ Specific questions about following the standard may be
+ asked on the <tt>debian-devel</tt> mailing list, or
+ referred to the FHS mailing list (see the
+ <url id="http://www.pathname.com/fhs/" name="FHS web site"> for
+ more information).
+ </p>
+ </sect1>
<sect1>
- <heading>Definitions</heading>
+ <heading>Site-specific programs</heading>
+
+ <p>
+ As mandated by the FHS, packages must not place any
+ files in <file>/usr/local</file>, either by putting them in
+ the file system archive to be unpacked by <prgn>dpkg</prgn>
+ or by manipulating them in their maintainer scripts.
+ </p>
+
+ <p>
+ However, the package may create empty directories below
+ <file>/usr/local</file> so that the system administrator knows
+ where to place site-specific files. These directories
+ should be removed on package removal if they are
+ empty.
+ </p>
+
+ <p>
+ Note, that this applies only to directories <em>below</em>
+ <file>/usr/local</file>, not <em>in</em> <file>/usr/local</file>.
+ Packages must not create sub-directories in the directory
+ <file>/usr/local</file> itself, except those listed in FHS,
+ section 4.5. However, you may create directories below
+ them as you wish. You must not remove any of the
+ directories listed in 4.5, even if you created them.
+ </p>
+
+ <p>
+ Since <file>/usr/local</file> can be mounted read-only from a
+ remote server, these directories must be created and
+ removed by the <prgn>postinst</prgn> and <prgn>prerm</prgn>
+ maintainer scripts and not be included in the
+ <file>.deb</file> archive. These scripts must not fail if
+ either of these operations fail.
+ </p>
+
+ <p>
+ For example, the <tt>emacsen-common</tt> package could
+ contain something like
+ <example compact="compact">
+if [ ! -e /usr/local/share/emacs ]
+then
+ if mkdir /usr/local/share/emacs 2>/dev/null
+ then
+ chown root:staff /usr/local/share/emacs
+ chmod 2775 /usr/local/share/emacs
+ fi
+fi
+ </example>
+ in its <prgn>postinst</prgn> script, and
+ <example compact="compact">
+rmdir /usr/local/share/emacs/site-lisp 2>/dev/null || true
+rmdir /usr/local/share/emacs 2>/dev/null || true
+ </example>
+ in the <prgn>prerm</prgn> script. (Note that this form is
+ used to ensure that if the script is interrupted, the
+ directory <file>/usr/local/share/emacs</file> will still be
+ removed.)
+ </p>
<p>
- <taglist>
- <tag>configuration file</tag>
- <item>
- A file that affects the operation of a program, or
- provides site- or host-specific information, or
- otherwise customizes the behavior of a program.
- Typically, configuration files are intended to be
- modified by the system administrator (if needed or
- desired) to conform to local policy or to provide
- more useful site-specific behavior.
- </item>
+ If you do create a directory in <file>/usr/local</file> for
+ local additions to a package, you should ensure that
+ settings in <file>/usr/local</file> take precedence over the
+ equivalents in <file>/usr</file>.
+ </p>
- <tag><tt>conffile</tt></tag>
- <item>
- A file listed in a package's <tt>conffiles</tt>
- file, and is treated specially by <prgn>dpkg</prgn>
- (see <ref id="configdetails">).
- </item>
- </taglist>
+ <p>
+ However, because <file>/usr/local</file> and its contents are
+ for exclusive use of the local administrator, a package
+ must not rely on the presence or absence of files or
+ directories in <file>/usr/local</file> for normal operation.
</p>
<p>
- The distinction between these two is important; they are
- not interchangeable concepts. Almost all
- <tt>conffile</tt>s are configuration files, but many
- configuration files are not <tt>conffiles</tt>.
+ The <file>/usr/local</file> directory itself and all the
+ subdirectories created by the package should (by default) have
+ permissions 2775 (group-writable and set-group-id) and be
+ owned by <tt>root.staff</tt>.
</p>
+ </sect1>
+ <sect1>
+ <heading>The system-wide mail directory</heading>
<p>
- Note that a script that embeds configuration information
- (such as most of the files in <file>/etc/default</file> and
- <file>/etc/cron.{daily,weekly,monthly}</file>) is de-facto a
- configuration file and should be treated as such.
+ The system-wide mail directory is <file>/var/mail</file>. This
+ directory is part of the base system and should not owned
+ by any particular mail agents. The use of the old
+ location <file>/var/spool/mail</file> is deprecated, even
+ though the spool may still be physically located there.
+ To maintain partial upgrade compatibility for systems
+ which have <file>/var/spool/mail</file> as their physical mail
+ spool, packages using <file>/var/mail</file> must depend on
+ either <package>libc6</package> (>= 2.1.3-13), or on
+ <package>base-files</package> (>= 2.2.0), or on later
+ versions of either one of these packages.
</p>
</sect1>
+ </sect>
+
+ <sect>
+ <heading>Users and groups</heading>
<sect1>
- <heading>Location</heading>
+ <heading>Introduction</heading>
+ <p>
+ The Debian system can be configured to use either plain or
+ shadow passwords.
+ </p>
<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.
+ Some user ids (UIDs) and group ids (GIDs) are reserved
+ globally for use by certain packages. Because some
+ packages need to include files which are owned by these
+ users or groups, or need the ids compiled into binaries,
+ these ids must be used on any Debian system only for the
+ purpose for which they are allocated. This is a serious
+ restriction, and we should avoid getting in the way of
+ local administration policies. In particular, many sites
+ allocate users and/or local system groups starting at 100.
</p>
<p>
- 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.
+ Apart from this we should have dynamically allocated ids,
+ which should by default be arranged in some sensible
+ order, but the behavior should be configurable.
+ </p>
+
+ <p>
+ Packages other than <tt>base-passwd</tt> must not modify
+ <file>/etc/passwd</file>, <file>/etc/shadow</file>,
+ <file>/etc/group</file> or <file>/etc/gshadow</file>.
</p>
</sect1>
<sect1>
- <heading>Behavior</heading>
-
+ <heading>UID and GID classes</heading>
<p>
- Configuration file handling must conform to the following
- behavior:
- <list compact="compact">
+ The UID and GID numbers are divided into classes as
+ follows:
+ <taglist>
+ <tag>0-99:</tag>
<item>
- local changes must be preserved during a package
- upgrade, and
+ <p>
+ Globally allocated by the Debian project, the same
+ on every Debian system. These ids will appear in
+ the <file>passwd</file> and <file>group</file> files of all
+ Debian systems, new ids in this range being added
+ automatically as the <tt>base-passwd</tt> package is
+ updated.
+ </p>
+
+ <p>
+ Packages which need a single statically allocated
+ uid or gid should use one of these; their
+ maintainers should ask the <tt>base-passwd</tt>
+ maintainer for ids.
+ </p>
</item>
+
+ <tag>100-999:</tag>
<item>
- configuration files must be preserved when the
- package is removed, and only deleted when the
- package is purged.
+ <p>
+ Dynamically allocated system users and groups.
+ Packages which need a user or group, but can have
+ this user or group allocated dynamically and
+ differently on each system, should use <tt>adduser
+ --system</tt> to create the group and/or user.
+ <prgn>adduser</prgn> will check for the existence of
+ the user or group, and if necessary choose an unused
+ id based on the ranges specified in
+ <file>adduser.conf</file>.
+ </p>
</item>
- </list>
+
+ <tag>1000-29999:</tag>
+ <item>
+ <p>
+ Dynamically allocated user accounts. By default
+ <prgn>adduser</prgn> will choose UIDs and GIDs for
+ user accounts in this range, though
+ <file>adduser.conf</file> may be used to modify this
+ behavior.
+ </p>
+ </item>
+
+ <tag>30000-59999:</tag>
+ <item>
+ <p>Reserved.</p>
+ </item>
+
+ <tag>60000-64999:</tag>
+ <item>
+ <p>
+ Globally allocated by the Debian project, but only
+ created on demand. The ids are allocated centrally
+ and statically, but the actual accounts are only
+ created on users' systems on demand.
+ </p>
+
+ <p>
+ These ids are for packages which are obscure or
+ which require many statically-allocated ids. These
+ packages should check for and create the accounts in
+ <file>/etc/passwd</file> or <file>/etc/group</file> (using
+ <prgn>adduser</prgn> if it has this facility) if
+ necessary. Packages which are likely to require
+ further allocations should have a "hole" left after
+ them in the allocation, to give them room to
+ grow.
+ </p>
+ </item>
+
+ <tag>65000-65533:</tag>
+ <item>
+ <p>Reserved.</p>
+ </item>
+
+ <tag>65534:</tag>
+ <item>
+ <p>
+ User <tt>nobody</tt>. The corresponding gid refers
+ to the group <tt>nogroup</tt>.
+ </p>
+ </item>
+
+ <tag>65535:</tag>
+ <item>
+ <p>
+ <tt>(uid_t)(-1) == (gid_t)(-1)</tt> <em>must
+ not</em> be used, because it is the error return
+ sentinel value.
+ </p>
+ </item>
+ </taglist>
</p>
+ </sect1>
+ </sect>
+
+ <sect id="sysvinit">
+ <heading>System run levels and <file>init.d</file> scripts</heading>
+
+ <sect1 id="/etc/init.d">
+ <heading>Introduction</heading>
<p>
- The easy way to achieve this behavior is to make the
- configuration file a <tt>conffile</tt>. This is
- appropriate only if it is possible to distribute a default
- version that will work for most installations, although
- some system administrators may choose to modify it. This
- implies that the default version will be part of the
- package distribution, and must not be modified by the
- maintainer scripts during installation (or at any other
- time).
+ The <file>/etc/init.d</file> directory contains the scripts
+ executed by <prgn>init</prgn> at boot time and when the
+ init state (or "runlevel") is changed (see <manref
+ name="init" section="8">).
+ </p>
+
+ <p>
+ There are at least two different, yet functionally
+ equivalent, ways of handling these scripts. For the sake
+ of simplicity, this document describes only the symbolic
+ link method. However, it must not be assumed by maintainer
+ scripts that this method is being used, and any automated
+ manipulation of the various runlevel behaviours by
+ maintainer scripts must be performed using
+ <prgn>update-rc.d</prgn> as described below and not by
+ manually installing or removing symlinks. For information
+ on the implementation details of the other method,
+ implemented in the <tt>file-rc</tt> package, please refer
+ to the documentation of that package.
+ </p>
+
+ <p>
+ These scripts are referenced by symbolic links in the
+ <file>/etc/rc<var>n</var>.d</file> directories. When changing
+ runlevels, <prgn>init</prgn> looks in the directory
+ <file>/etc/rc<var>n</var>.d</file> for the scripts it should
+ execute, where <tt><var>n</var></tt> is the runlevel that
+ is being changed to, or <tt>S</tt> for the boot-up
+ scripts.
</p>
- <p>
- In order to ensure that local changes are preserved
- correctly, no package may contain or make hard links to
- conffiles.<footnote>
- 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.
- </footnote>
+ <p>
+ The names of the links all have the form
+ <file>S<var>mm</var><var>script</var></file> or
+ <file>K<var>mm</var><var>script</var></file> where
+ <var>mm</var> is a two-digit number and <var>script</var>
+ is the name of the script (this should be the same as the
+ name of the actual script in <file>/etc/init.d</file>).
+ </p>
+
+ <p>
+ When <prgn>init</prgn> changes runlevel first the targets
+ of the links whose names start with a <tt>K</tt> are
+ executed, each with the single argument <tt>stop</tt>,
+ followed by the scripts prefixed with an <tt>S</tt>, each
+ with the single argument <tt>start</tt>. (The links are
+ those in the <file>/etc/rc<var>n</var>.d</file> directory
+ corresponding to the new runlevel.) The <tt>K</tt> links
+ are responsible for killing services and the <tt>S</tt>
+ link for starting services upon entering the runlevel.
</p>
<p>
- The other way to do it is via the maintainer scripts. In
- this case, the configuration file must not be listed as a
- <tt>conffile</tt> and must not be part of the package
- distribution. If the existence of a file is required for
- the package to be sensibly configured it is the
- responsibility of the package maintainer to provide
- maintainer scripts which correctly create, update and
- maintain the file and remove it on purge. (See <ref
- id="maintainerscripts"> for more information.) These
- scripts must be idempotent (i.e., must work correctly if
- <prgn>dpkg</prgn> needs to re-run them due to errors
- during installation or removal), must cope with all the
- variety of ways <prgn>dpkg</prgn> can call maintainer
- scripts, must not overwrite or otherwise mangle the user's
- configuration without asking, must not ask unnecessary
- questions (particularly during upgrades), and otherwise be
- good citizens.
+ For example, if we are changing from runlevel 2 to
+ runlevel 3, init will first execute all of the <tt>K</tt>
+ prefixed scripts it finds in <file>/etc/rc3.d</file>, and then
+ all of the <tt>S</tt> prefixed scripts in that directory.
+ The links starting with <tt>K</tt> will cause the
+ referred-to file to be executed with an argument of
+ <tt>stop</tt>, and the <tt>S</tt> links with an argument
+ of <tt>start</tt>.
</p>
<p>
- The scripts are not required to configure every possible
- option for the package, but only those necessary to get
- the package running on a given system. Ideally the
- sysadmin should not have to do any configuration other
- than that done (semi-)automatically by the
- <prgn>postinst</prgn> script.
+ The two-digit number <var>mm</var> is used to determine
+ the order in which to run the scripts: low-numbered links
+ have their scripts run first. For example, the
+ <tt>K20</tt> scripts will be executed before the
+ <tt>K30</tt> scripts. This is used when a certain service
+ must be started before another. For example, the name
+ server <prgn>bind</prgn> might need to be started before
+ the news server <prgn>inn</prgn> so that <prgn>inn</prgn>
+ can set up its access lists. In this case, the script
+ that starts <prgn>bind</prgn> would have a lower number
+ than the script that starts <prgn>inn</prgn> so that it
+ runs first:
+ <example compact="compact">
+/etc/rc2.d/S17bind
+/etc/rc2.d/S70inn
+ </example>
</p>
<p>
- A common practice is to create a script called
- <file><var>package</var>-configure</file> and have the
- package's <prgn>postinst</prgn> call it if and only if the
- configuration file does not already exist. In certain
- cases it is useful for there to be an example or template
- file which the maintainer scripts use. Such files should
- be in <file>/usr/share/<var>package</var></file> or
- <file>/usr/lib/<var>package</var></file> (depending on whether
- they are architecture-independent or not). There should
- be symbolic links to them from
- <file>/usr/share/doc/<var>package</var>/examples</file> if
- they are examples, and should be perfectly ordinary
- <prgn>dpkg</prgn>-handled files (<em>not</em>
- configuration files).
+ The two runlevels 0 (halt) and 6 (reboot) are slightly
+ different. In these runlevels, the links with an
+ <tt>S</tt> prefix are still called after those with a
+ <tt>K</tt> prefix, but they too are called with the single
+ argument <tt>stop</tt>.
</p>
<p>
- These two styles of configuration file handling must
- not be mixed, for that way lies madness:
- <prgn>dpkg</prgn> will ask about overwriting the file
- every time the package is upgraded.
+ Also, if the script name ends <tt>.sh</tt>, the script
+ will be sourced in runlevel <tt>S</tt> rather that being
+ run in a forked subprocess, but will be explicitly run by
+ <prgn>sh</prgn> in all other runlevels.
</p>
</sect1>
<sect1>
- <heading>Sharing configuration files</heading>
+ <heading>Writing the scripts</heading>
<p>
- Packages which specify the same file as a
- <tt>conffile</tt> must be tagged as <em>conflicting</em>
- with each other. (This is an instance of the general rule
- about not sharing files. Note that neither alternatives
- nor diversions are likely to be appropriate in this case;
- in particular, <prgn>dpkg</prgn> does not handle diverted
- <tt>conffile</tt>s well.)
- </p>
+ Packages that include daemons for system services should
+ place scripts in <file>/etc/init.d</file> to start or stop
+ services at boot time or during a change of runlevel.
+ These scripts should be named
+ <file>/etc/init.d/<var>package</var></file>, and they should
+ accept one argument, saying what to do:
- <p>
- The maintainer scripts must not alter a <tt>conffile</tt>
- of <em>any</em> package, including the one the scripts
- belong to.
+ <taglist>
+ <tag><tt>start</tt></tag>
+ <item>start the service,</item>
+
+ <tag><tt>stop</tt></tag>
+ <item>stop the service,</item>
+
+ <tag><tt>restart</tt></tag>
+ <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,</item>
+
+ <tag><tt>force-reload</tt></tag>
+ <item>cause the configuration to be reloaded if the
+ service supports this, otherwise restart the
+ 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>
<p>
- If two or more packages use the same configuration file
- and it is reasonable for both to be installed at the same
- time, one of these packages must be defined as
- <em>owner</em> of the configuration file, i.e., it will be
- the package which handles that file as a configuration
- file. Other packages that use the configuration file must
- depend on the owning package if they require the
- configuration file to operate. If the other package will
- use the configuration file if present, but is capable of
- operating without it, no dependency need be declared.
+ The <file>init.d</file> scripts should ensure that they will
+ behave sensibly if invoked with <tt>start</tt> when the
+ 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>
<p>
- If it is desirable for two or more related packages to
- share a configuration file <em>and</em> for all of the
- related packages to be able to modify that configuration
- file, then the following should be done:
- <enumlist compact="compact">
- <item>
- One of the related packages (the "owning" package)
- will manage the configuration file with maintainer
- scripts as described in the previous section.
- </item>
- <item>
- The owning package should also provide a program
- that the other packages may use to modify the
- configuration file.
- </item>
- <item>
- The related packages must use the provided program
- to make any desired modifications to the
- configuration file. They should either depend on
- the core package to guarantee that the configuration
- modifier program is available or accept gracefully
- that they cannot modify the configuration file if it
- is not. (This is in addition to the fact that the
- configuration file may not even be present in the
- latter scenario.)
- </item>
- </enumlist>
+ 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>
<p>
- Sometimes it's appropriate to create a new package which
- provides the basic infrastructure for the other packages
- and which manages the shared configuration files. (The
- <tt>sgml-base</tt> package is a good example.)
+ The <file>/etc/init.d</file> scripts must be treated as
+ configuration files, either (if they are present in the
+ package, that is, in the .deb file) by marking them as
+ <tt>conffile</tt>s, or, (if they do not exist in the .deb)
+ by managing them correctly in the maintainer scripts (see
+ <ref id="config-files">). This is important since we want
+ to give the local system administrator the chance to adapt
+ the scripts to the local system, e.g., to disable a
+ service without de-installing the package, or to specify
+ some special command line options when starting a service,
+ while making sure her changes aren't lost during the next
+ package upgrade.
</p>
- </sect1>
-
- <sect1>
- <heading>User configuration files ("dotfiles")</heading>
<p>
- The files in <file>/etc/skel</file> will automatically be
- copied into new user accounts by <prgn>adduser</prgn>.
- No other program should reference the files in
- <file>/etc/skel</file>.
+ These scripts should not fail obscurely when the
+ configuration files remain but the package has been
+ removed, as configuration files remain on the system after
+ the package has been removed. Only when <prgn>dpkg</prgn>
+ is executed with the <tt>--purge</tt> option will
+ configuration files be removed. In particular, as the
+ <file>/etc/init.d/<var>package</var></file> script itself is
+ usually a <tt>conffile</tt>, it will remain on the system
+ if the package is removed but not purged. Therefore, you
+ should include a <tt>test</tt> statement at the top of the
+ script, like this:
+ <example compact="compact">
+test -f <var>program-executed-later-in-script</var> || exit 0
+ </example>
</p>
<p>
- Therefore, if a program needs a dotfile to exist in
- advance in <file>$HOME</file> to work sensibly, that dotfile
- should be installed in <file>/etc/skel</file> and treated as a
- configuration file.
+ Often there are some variables in the <file>init.d</file>
+ scripts whose values control the behaviour of the scripts,
+ and which a system administrator is likely to want to
+ change. As the scripts themselves are frequently
+ <tt>conffile</tt>s, modifying them requires that the
+ administrator merge in their changes each time the package
+ is upgraded and the <tt>conffile</tt> changes. To ease
+ the burden on the system administrator, such configurable
+ values should not be placed directly in the script.
+ Instead, they should be placed in a file in
+ <file>/etc/default</file>, which typically will have the same
+ base name as the <file>init.d</file> script. This extra file
+ should be sourced by the script when the script runs. It
+ must contain only variable settings and comments in POSIX
+ <prgn>sh</prgn> format. It may either be a
+ <tt>conffile</tt> or a configuration file maintained by
+ the package maintainer scripts. See <ref id="config-files">
+ for more details.
</p>
<p>
- However, programs that require dotfiles in order to
- operate sensibly are a bad thing, unless they do create
- the dotfiles themselves automatically.
+ To ensure that vital configurable values are always
+ available, the <file>init.d</file> script should set default
+ values for each of the shell variables it uses, either
+ before sourcing the <file>/etc/default/</file> file or
+ afterwards using something like the <tt>:
+ ${VAR:=default}</tt> syntax. Also, the <file>init.d</file>
+ script must behave sensibly and not fail if the
+ <file>/etc/default</file> file is deleted.
</p>
+ </sect1>
- <p>
- Furthermore, programs should be configured by the Debian
- default installation to behave as closely to the upstream
- default behaviour as possible.
- </p>
+ <sect1>
+ <heading>Interfacing with the initscript system</heading>
<p>
- Therefore, if a program in a Debian package needs to be
- configured in some way in order to operate sensibly, that
- should be done using a site-wide configuration file placed
- in <file>/etc</file>. Only if the program doesn't support a
- site-wide default configuration and the package maintainer
- doesn't have time to add it may a default per-user file be
- placed in <file>/etc/skel</file>.
+ Maintainers should use the abstraction layer provided by
+ the <prgn>update-rc.d</prgn> and <prgn>invoke-rc.d</prgn>
+ programs to deal with initscripts in their packages'
+ scripts such as <prgn>postinst</prgn>, <prgn>prerm</prgn>
+ and <prgn>postrm</prgn>.
</p>
<p>
- <file>/etc/skel</file> should be as empty as we can make it.
- This is particularly true because there is no easy (or
- necessarily desirable) mechanism for ensuring that the
- appropriate dotfiles are copied into the accounts of
- existing users when a package is installed.
+ Directly managing the /etc/rc?.d links and directly
+ invoking the <file>/etc/init.d/</file> initscripts should
+ be done only by packages providing the initscript
+ subsystem (such as <prgn>sysvinit</prgn> and
+ <prgn>file-rc</prgn>).
</p>
- </sect1>
- </sect>
- <sect>
- <heading>Log files</heading>
- <p>
- Log files should usually be named
- <file>/var/log/<var>package</var>.log</file>. If you have many
- log files, or need a separate directory for permission
- reasons (<file>/var/log</file> is writable only by
- <file>root</file>), you should usually create a directory named
- <file>/var/log/<var>package</var></file> and place your log
- files there.
- </p>
+ <sect2>
+ <heading>Managing the links</heading>
- <p>
- Log files must be rotated occasionally so that they don't
- grow indefinitely; the best way to do this is to drop a log
- rotation configuration file into the directory
- <file>/etc/logrotate.d</file> and use the facilities provided by
- logrotate.<footnote>
<p>
- The traditional approach to log files has been to set up
- <em>ad hoc</em> log rotation schemes using simple shell
- scripts and cron. While this approach is highly
- customizable, it requires quite a lot of sysadmin work.
- Even though the original Debian system helped a little
- by automatically installing a system which can be used
- as a template, this was deemed not enough.
+ The program <prgn>update-rc.d</prgn> is provided for
+ package maintainers to arrange for the proper creation and
+ 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>
<p>
- The use of <prgn>logrotate</prgn>, a program developed
- by Red Hat, is better, as it centralizes log management.
- It has both a configuration file
- (<file>/etc/logrotate.conf</file>) and a directory where
- packages can drop their individual log rotation
- configurations (<file>/etc/logrotate.d</file>).
+ You must not include any <file>/etc/rc<var>n</var>.d</file>
+ symbolic links in the actual archive or manually create or
+ remove the symbolic links in maintainer scripts; you must
+ use the <prgn>update-rc.d</prgn> program instead. (The
+ former will fail if an alternative method of maintaining
+ runlevel information is being used.) You must not include
+ the <file>/etc/rc<var>n</var>.d</file> directories themselves
+ in the archive either. (Only the <tt>sysvinit</tt>
+ package may do so.)
</p>
- </footnote>
- Here is a good example for a logrotate config
- file (for more information see <manref name="logrotate"
- section="8">):
- <example compact="compact">
-/var/log/foo/*.log {
-rotate 12
-weekly
-compress
-postrotate
-/etc/init.d/foo force-reload
-endscript
-}
- </example>
- This rotates all files under <file>/var/log/foo</file>, saves 12
- compressed generations, and forces the daemon to reload its
- configuration information after the log rotation.
- </p>
- <p>
- Log files should be removed when the package is
- purged (but not when it is only removed). This should be
- done by the <prgn>postrm</prgn> script when it is called
- with the argument <tt>purge</tt> (see <ref
- id="removedetails">).
- </p>
- </sect>
-
- <sect>
- <heading>Permissions and owners</heading>
-
- <p>
- The rules in this section are guidelines for general use.
- If necessary you may deviate from the details below.
- However, if you do so you must make sure that what is done
- is secure and you should try to be as consistent as possible
- with the rest of the system. You should probably also
- discuss it on <prgn>debian-devel</prgn> first.
- </p>
+ <p>
+ By default <prgn>update-rc.d</prgn> will start services in
+ each of the multi-user state runlevels (2, 3, 4, and 5)
+ and stop them in the halt runlevel (0), the single-user
+ runlevel (1) and the reboot runlevel (6). The system
+ administrator will have the opportunity to customize
+ runlevels by simply adding, moving, or removing the
+ symbolic links in <file>/etc/rc<var>n</var>.d</file> if
+ symbolic links are being used, or by modifying
+ <file>/etc/runlevel.conf</file> if the <tt>file-rc</tt> method
+ is being used.
+ </p>
- <p>
- Files should be owned by <tt>root.root</tt>, and made
- writable only by the owner and universally readable (and
- executable, if appropriate), that is mode 644 or 755.
- </p>
+ <p>
+ To get the default behavior for your package, put in your
+ <prgn>postinst</prgn> script
+ <example compact="compact">
+ update-rc.d <var>package</var> defaults
+ </example>
+ and in your <prgn>postrm</prgn>
+ <example compact="compact">
+ if [ "$1" = purge ]; then
+ update-rc.d <var>package</var> remove
+ fi
+ </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>
- <p>
- Directories should be mode 755 or (for group-writability)
- mode 2775. The ownership of the directory should be
- consistent with its mode: if a directory is mode 2775, it
- should be owned by the group that needs write access to
- it.
- </p>
+ <p>
+ This will use a default sequence number of 20. If it does
+ not matter when or in which order the <file>init.d</file>
+ script is run, use this default. If it does, then you
+ should talk to the maintainer of the <prgn>sysvinit</prgn>
+ package or post to <tt>debian-devel</tt>, and they will
+ help you choose a number.
+ </p>
- <p>
- Setuid and setgid executables should be mode 4755 or 2755
- respectively, and owned by the appropriate user or group.
- They should not be made unreadable (modes like 4711 or
- 2711 or even 4111); doing so achieves no extra security,
- because anyone can find the binary in the freely available
- Debian package; it is merely inconvenient. For the same
- reason you should not restrict read or execute permissions
- on non-set-id executables.
- </p>
+ <p>
+ For more information about using <tt>update-rc.d</tt>,
+ please consult its manpage <manref name="update-rc.d"
+ section="8">.
+ </p>
+ </sect2>
- <p>
- Some setuid programs need to be restricted to particular
- sets of users, using file permissions. In this case they
- should be owned by the uid to which they are set-id, and by
- the group which should be allowed to execute them. They
- should have mode 4754; again there is no point in making
- them unreadable to those users who must not be allowed to
- execute them.
- </p>
+ <sect2>
+ <heading>Running initscripts</heading>
+ <p>
+ The program <prgn>invoke-rc.d</prgn> is provided to make
+ it easier for package maintainers to properly invoke an
+ initscript, obeying runlevel and other locally-defined
+ constraints that might limit a package's right to start,
+ stop and otherwise manage services. This program may be
+ used by maintainers in their packages' scripts.
+ </p>
- <p>
- It is possible to arrange that the system administrator can
- reconfigure the package to correspond to their local
- security policy by changing the permissions on a binary:
- they can do this by using <prgn>dpkg-statoverride</prgn>, as
- described below.<footnote>
- Ordinary files installed by <prgn>dpkg</prgn> (as
- opposed to <tt>conffile</tt>s and other similar objects)
- normally have their permissions reset to the distributed
- permissions when the package is reinstalled. However,
- the use of <prgn>dpkg-statoverride</prgn> overrides this
- default behaviour. If you use this method, you should
- remember to describe <prgn>dpkg-statoverride</prgn> in
- the package documentation; being a relatively new
- addition to Debian, it is probably not yet well-known.
- </footnote>
- Another method you should consider is to create a group for
- people allowed to use the program(s) and make any setuid
- executables executable only by that group.
- </p>
+ <p>
+ The use of <prgn>invoke-rc.d</prgn> to invoke the
+ <file>/etc/init.d/*</file> initscripts is strongly
+ recommended<footnote>
+ 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.
+ </footnote>, instead of calling them directly.
+ </p>
- <p>
- If you need to create a new user or group for your package
- there are two possibilities. Firstly, you may need to
- make some files in the binary package be owned by this
- user or group, or you may need to compile the user or
- group id (rather than just the name) into the binary
- (though this latter should be avoided if possible, as in
- this case you need a statically allocated id).</p>
+ <p>
+ By default, <prgn>invoke-rc.d</prgn> will pass any
+ action requests (start, stop, reload, restart...) to the
+ <file>/etc/init.d</file> script, filtering out requests
+ to start or restart a service out of its intended
+ runlevels.
+ </p>
- <p>
- If you need a statically allocated id, you must ask for a
- user or group id from the <tt>base-passwd</tt> maintainer,
- and must not release the package until you have been
- allocated one. Once you have been allocated one you must
- either make the package depend on a version of the
- <tt>base-passwd</tt> package with the id present in
- <file>/etc/passwd</file> or <file>/etc/group</file>, or arrange for
- your package to create the user or group itself with the
- correct id (using <tt>adduser</tt>) in its
- <prgn>preinst</prgn> or <prgn>postinst</prgn>. (Doing it in
- the <prgn>postinst</prgn> is to be preferred if it is
- possible, otherwise a pre-dependency will be needed on the
- <tt>adduser</tt> package.)
- </p>
+ <p>
+ Most packages will simply need to change:
+ <example compact="compact">/etc/init.d/<package>
+ <action></example> in their <prgn>postinst</prgn>
+ and <prgn>prerm</prgn> scripts to:
+ <example compact="compact">
+ if [ -x /usr/sbin/invoke-rc.d ] ; then
+ invoke-rc.d <var>package</var> <action>
+ else
+ /etc/init.d/<var>package</var> <action>
+ fi
+ </example>
+ </p>
- <p>
- On the other hand, the program might be able to determine
- the uid or gid from the user or group name at runtime, so
- that a dynamically allocated id can be used. In this case
- you should choose an appropriate user or group name,
- discussing this on <prgn>debian-devel</prgn> and checking
- with the <package/base-passwd/ maintainer that it is unique and that
- they do not wish you to use a statically allocated id
- instead. When this has been checked you must arrange for
- your package to create the user or group if necessary using
- <prgn>adduser</prgn> in the <prgn>preinst</prgn> or
- <prgn>postinst</prgn> script (again, the latter is to be
- preferred if it is possible).
- </p>
+ <p>
+ 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>
- Note that changing the numeric value of an id associated
- with a name is very difficult, and involves searching the
- file system for all appropriate files. You need to think
- carefully whether a static or dynamic id is required, since
- changing your mind later will cause problems.
- </p>
+ For more information about using
+ <prgn>invoke-rc.d</prgn>, please consult its manpage
+ <manref name="invoke-rc.d" section="8">.
+ </p>
+ </sect2>
+ </sect1>
- <sect1><heading>The use of <prgn>dpkg-statoverride</prgn></heading>
- <p>
- This section is not intended as policy, but as a
- description of the use of <prgn>dpkg-statoverride</prgn>.
+ <sect1>
+ <heading>Boot-time initialization</heading>
+
+ <p>
+ There used to be another directory, <file>/etc/rc.boot</file>,
+ which contained scripts which were run once per machine
+ 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>
+ </sect1>
+
+ <sect1>
+ <heading>Example</heading>
<p>
- <prgn>dpkg-statoverride</prgn> is a replacement for the
- deprecated <tt>suidmanager</tt> package. Packages which
- previously used <tt>suidmanager</tt> should have a
- <tt>Conflicts: suidmanager (<< 0.50)</tt> entry (or even
- <tt>(<< 0.52)</tt>), and calls to <tt>suidregister</tt>
- and <tt>suidunregister</tt> should now be simply removed
- from the maintainer scripts.
+ The <prgn>bind</prgn> DNS (nameserver) package wants to
+ make sure that the nameserver is running in multiuser
+ runlevels, and is properly shut down with the system. It
+ puts a script in <file>/etc/init.d</file>, naming the script
+ appropriately <tt>bind</tt>. As you can see, the script
+ interprets the argument <tt>reload</tt> to send the
+ nameserver a <tt>HUP</tt> signal (causing it to reload its
+ configuration); this way the system administrator can say
+ <tt>/etc/init.d/bind reload</tt> to reload the name
+ server. The script has one configurable value, which can
+ be used to pass parameters to the named program at
+ startup; this value is read from
+ <file>/etc/default/bind</file> (see below).
</p>
<p>
- If a system administrator wishes to have a file (or
- directory or other such thing) installed with owner and
- permissions different from those in the distributed Debian
- package, he can use the <prgn>dpkg-statoverride</prgn>
- program to instruct <prgn>dpkg</prgn> to use the different
- settings every time the file is installed. Thus the
- package maintainer should distribute the files with their
- normal permissions, and leave it for the system
- administrator to make any desired changes. For example, a
- daemon which is normally required to be setuid root, but
- in certain situations could be used without being setuid,
- should be installed setuid in the <tt>.deb</tt>. Then the
- local system administrator can change this if they wish.
- If there are two standard ways of doing it, the package
- maintainer can use <tt>debconf</tt> to find out the
- preference, and call <prgn>dpkg-statoverride</prgn> in the
- maintainer script if necessary to accommodate the system
- administrator's choice.
+ <example compact="compact">
+#!/bin/sh
+#
+# Original version by Robert Leslie
+# <rob@mars.org>, edited by iwj and cs
+
+test -x /usr/sbin/named || exit 0
+
+# Source defaults file.
+PARAMS=''
+if [ -f /etc/default/bind ]; then
+ . /etc/default/bind
+fi
+
+
+case "$1" in
+start)
+ echo -n "Starting domain name service: named"
+ start-stop-daemon --start --quiet --exec /usr/sbin/named \
+ -- $PARAMS
+ echo "."
+ ;;
+stop)
+ echo -n "Stopping domain name service: named"
+ start-stop-daemon --stop --quiet \
+ --pidfile /var/run/named.pid --exec /usr/sbin/named
+ echo "."
+ ;;
+restart)
+ echo -n "Restarting domain name service: named"
+ start-stop-daemon --stop --quiet \
+ --pidfile /var/run/named.pid --exec /usr/sbin/named
+ start-stop-daemon --start --verbose --exec /usr/sbin/named \
+ -- $PARAMS
+ echo "."
+ ;;
+force-reload|reload)
+ echo -n "Reloading configuration of domain name service: named"
+ start-stop-daemon --stop --signal 1 --quiet \
+ --pidfile /var/run/named.pid --exec /usr/sbin/named
+ echo "."
+ ;;
+*)
+ echo "Usage: /etc/init.d/bind " \
+ " {start|stop|restart|reload|force-reload}" >&2
+ exit 1
+ ;;
+esac
+
+exit 0
+ </example>
</p>
<p>
- Given the above, <prgn>dpkg-statoverride</prgn> is
- essentially a tool for system administrators and would not
- normally be needed in the maintainer scripts. There is
- one type of situation, though, where calls to
- <prgn>dpkg-statoverride</prgn> would be needed in the
- maintainer scripts, and that involves packages which use
- dynamically allocated user or group ids. In such a
- situation, something like the following idiom can be very
- helpful in the package's <prgn>postinst</prgn>, where
- <tt>sysuser</tt> is a dynamically allocated id:
- <example>
-for i in /usr/bin/foo /usr/sbin/bar
-do
- if ! dpkg-statoverride --list $i >/dev/null
- then
- dpkg-statoverride --update --add sysuser root 4755 $i
- fi
-done
+ Complementing the above init script is a configuration
+ file <file>/etc/default/bind</file>, which contains
+ configurable parameters used by the script. This would be
+ created by the <prgn>postinst</prgn> script if it was not
+ already present, and removed on purge by the
+ <prgn>postrm</prgn> script.
+ <example compact="compact">
+# Specified parameters to pass to named. See named(8).
+# You may uncomment the following line, and edit to taste.
+#PARAMS="-u nobody"
</example>
- The corresponding <tt>dpkg-statoverride --remove</tt>
- calls can then be made unconditionally when the package is
- purged.
</p>
- </sect1>
- </sect>
- </chapt>
-
- <chapt id="customized-programs">
- <heading>Customized programs</heading>
-
- <sect id="arch-spec">
- <heading>Architecture specification strings</heading>
- <p>
- If a program needs to specify an <em>architecture specification
- string</em> in some place, the following format should be
- used: <var>arch</var>-<var>os</var><footnote>
- The following architectures and operating systems are
- currently recognised by <prgn>dpkg-archictecture</prgn>.
- The architecture, <tt><var>arch</var></tt>, is one of
- the following: <tt>alpha</tt>, <tt>arm</tt>,
- <tt>hppa</tt>, <tt>i386</tt>, <tt>ia64</tt>,
- <tt>m68k</tt>, <tt>mips</tt>, <tt>mipsel</tt>,
- <tt>powerpc</tt>, <tt>s390</tt>, <tt>sh</tt>,
- <tt>sheb</tt>, <tt>sparc</tt> and <tt>sparc64</tt>. The
- operating system, <tt><var>os</var></tt>, is one of:
- <tt>linux</tt>, <tt>gnu</tt>, <tt>freebsd</tt> and
- <tt>openbsd</tt>. Use of <tt>gnu</tt> in this string is
- reserved for the GNU/Hurd operating system.
- </footnote>.
- </p>
+ <p>
+ Another example on which you can base your
+ <file>/etc/init.d</file> scripts is found in
+ <file>/etc/init.d/skeleton</file>.
+ </p>
- <p>
- Note that we don't want to use
- <tt><var>arch</var>-debian-linux</tt> to apply to the rule
- <tt><var>architecture</var>-<var>vendor</var>-<var>os</var></tt>
- since this would make our programs incompatible with other
- Linux distributions. We also don't use something like
- <tt><var>arch</var>-unknown-linux</tt>, since the
- <tt>unknown</tt> does not look very good.
- </p>
+ <p>
+ If this package is happy with the default setup from
+ <prgn>update-rc.d</prgn>, namely an ordering number of 20
+ and having named running in all runlevels, it can say in
+ its <prgn>postinst</prgn>:
+ <example compact="compact">
+update-rc.d bind defaults >/dev/null
+ </example>
+ And in its <prgn>postrm</prgn>, to remove the links when the
+ package is purged:
+ <example compact="compact">
+if [ "$1" = purge ]; then
+ update-rc.d bind remove >/dev/null
+fi
+ </example>
+ </p>
+ </sect1>
</sect>
<sect>
- <heading>Daemons</heading>
-
- <p>
- The configuration files <file>/etc/services</file>,
- <file>/etc/protocols</file>, and <file>/etc/rpc</file> are managed
- by the <prgn>netbase</prgn> package and must not be modified
- by other packages.
- </p>
+ <heading>Console messages from <file>init.d</file> scripts</heading>
<p>
- If a package requires a new entry in one of these files, the
- maintainer should get in contact with the
- <prgn>netbase</prgn> maintainer, who will add the entries
- and release a new version of the <prgn>netbase</prgn>
- package.
+ This section describes the formats to be used for messages
+ written to standard output by the <file>/etc/init.d</file>
+ scripts. The intent is to improve the consistency of
+ Debian's startup and shutdown look and feel. For this
+ reason, please look very carefully at the details. We want
+ the messages to have the same format in terms of wording,
+ spaces, punctuation and case of letters.
</p>
<p>
- The configuration file <file>/etc/inetd.conf</file> must not be
- modified by the package's scripts except via the
- <prgn>update-inetd</prgn> script or the
- <file>DebianNet.pm</file> Perl module. See their documentation
- for details on how to add entries.
+ Here is a list of overall rules that you should use when you
+ create output messages. They can be useful if you have a
+ non-standard message that is not covered specifically in the
+ sections below.
</p>
<p>
- If a package wants to install an example entry into
- <file>/etc/inetd.conf</file>, the entry must be preceded with
- exactly one hash character (<tt>#</tt>). Such lines are
- treated as "commented out by user" by the
- <prgn>update-inetd</prgn> script and are not changed or
- activated during package updates.
- </p>
- </sect>
-
- <sect>
- <heading>Using pseudo-ttys and modifying wtmp, utmp and
- lastlog</heading>
+ <list>
+ <item>
+ Every message should fit in one line (fewer than 80
+ characters), start with a capital letter and end with
+ a period (<tt>.</tt>) and line feed (<tt>"\n"</tt>).
+ </item>
- <p>
- Some programs need to create pseudo-ttys. This should be done
- using Unix98 ptys if the C library supports it. The resulting
- program must not be installed setuid root, unless that
- is required for other functionality.
- </p>
+ <item>
+ 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.
+ </item>
- <p>
- The files <file>/var/run/utmp</file>, <file>/var/log/wtmp</file> and
- <file>/var/log/lastlog</file> must be installed writeable by
- group <tt>utmp</tt>. Programs which need to modify those
- files must be installed setgid <tt>utmp</tt>.
+ <item>
+ Design your messages as if the computer is telling you
+ what he is doing (let him be polite :-), but don't
+ mention "him" directly. For example, if you think of
+ saying
+ <example compact="compact">
+I'm starting network daemons: nfsd mountd.
+ </example>
+ just say
+ <example compact="compact">
+Starting network daemons: nfsd mountd.
+ </example>
+ </item>
+ </list>
</p>
- </sect>
-
- <sect>
- <heading>Editors and pagers</heading>
<p>
- Some programs have the ability to launch an editor or pager
- program to edit or display a text document. Since there are
- lots of different editors and pagers available in the Debian
- distribution, the system administrator and each user should
- have the possibility to choose his/her preferred editor and
- pager.
+ There are standard message formats for the following
+ situations. They should be used by the <tt>init.d</tt>
+ scripts.
</p>
<p>
- In addition, every program should choose a good default
- editor/pager if none is selected by the user or system
- administrator.
- </p>
+ <list>
+ <item>
+ <p>When daemons are started</p>
- <p>
- Thus, every program that launches an editor or pager must
- use the EDITOR or PAGER environment variable to determine
- the editor or pager the user wishes to use. If these
- variables are not set, the programs <file>/usr/bin/editor</file>
- and <file>/usr/bin/pager</file> should be used, respectively.
- </p>
+ <p>
+ If your script starts one or more daemons, the output
+ should look like this (a single line, no leading
+ spaces):
+ <example compact="compact">
+Starting <var>description</var>: <var>daemon-1</var> ... <var>daemon-n</var>.
+ </example>
+ The <var>description</var> should describe the
+ subsystem the daemon or set of daemons are part of,
+ while <var>daemon-1</var> up to <var>daemon-n</var>
+ denote each daemon's name (typically the file name of
+ the program).
+ </p>
- <p>
- These two files are managed through the <prgn>dpkg</prgn>
- "alternatives" mechanism. Thus every package providing an
- editor or pager must call the
- <prgn>update-alternatives</prgn> script to register these
- programs.
- </p>
+ For example, the output of <file>/etc/init.d/lpd</file>
+ would look like:
+ <example compact="compact">
+Starting printer spooler: lpd.
+ </example>
+ </p>
- <p>
- If it is very hard to adapt a program to make use of the
- EDITOR or PAGER variables, that program may be configured to
- use <file>/usr/bin/sensible-editor</file> and
- <file>/usr/bin/sensible-pager</file> as the editor or pager
- program respectively. These are two scripts provided in the
- Debian base system that check the EDITOR and PAGER variables
- and launch the appropriate program, and fall back to
- <file>/usr/bin/editor</file> and <file>/usr/bin/pager</file> if the
- variable is not set.
- </p>
+ <p>
+ This can be achieved by saying
+ <example compact="compact">
+echo -n "Starting printer spooler: lpd"
+start-stop-daemon --start --quiet --exec /usr/sbin/lpd
+echo "."
+ </example>
+ in the script. If you have more than one daemon to
+ start, you should do the following:
+ <example compact="compact">
+echo -n "Starting remote file system services:"
+echo -n " nfsd"; start-stop-daemon --start --quiet nfsd
+echo -n " mountd"; start-stop-daemon --start --quiet mountd
+echo -n " ugidd"; start-stop-daemon --start --quiet ugidd
+echo "."
+ </example>
+ This makes it possible for the user to see what takes
+ so long and when the final daemon has been started.
+ You should be careful where to put spaces: in the
+ example above the system administrator can easily
+ comment out a line if he don't wants to start a
+ specific daemon, while the displayed message still
+ looks good.
+ </p>
+ </item>
- <p>
- A program may also use the VISUAL environment variable to
- determine the user's choice of editor. If it exists, it
- should take precedence over EDITOR. This is in fact what
- <file>/usr/bin/sensible-editor</file> does.
- </p>
+ <item>
+ <p>When a system parameter is being set</p>
- <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>
- The Debian base system already provides an editor and a
- pager program.
- </footnote>
- </p>
- </sect>
+ <p>
+ If you have to set up different system parameters
+ during the system boot, you should use this format:
+ <example compact="compact">
+Setting <var>parameter</var> to "<var>value</var>".
+ </example>
+ </p>
- <sect id="web-appl">
- <heading>Web servers and applications</heading>
+ <p>
+ You can use a statement such as the following to get
+ the quotes right:
+ <example compact="compact">
+echo "Setting DNS domainname to \"$domainname\"."
+ </example>
+ </p>
- <p>
- This section describes the locations and URLs that should
- be used by all web servers and web applications in the
- Debian system.
- </p>
+ <p>
+ Note that the same symbol (<tt>"</tt>) is used for the left
+ and right quotation marks. A grave accent (<tt>`</tt>) is
+ not a quote character; neither is an apostrophe
+ (<tt>'</tt>).
+ </p>
+ </item>
- <p>
- <enumlist>
<item>
- Cgi-bin executable files are installed in the
- directory
+ <p>When a daemon is stopped or restarted</p>
+
+ <p>
+ When you stop or restart a daemon, you should issue a
+ message identical to the startup message, except that
+ <tt>Starting</tt> is replaced with <tt>Stopping</tt>
+ or <tt>Restarting</tt> respectively.
+ </p>
+
+ <p>
+ For example, stopping the printer daemon will like
+ like this:
<example compact="compact">
-/usr/lib/cgi-bin/<var>cgi-bin-name</var>
+Stopping printer spooler: lpd.
</example>
- and should be referred to as
+ </p>
+ </item>
+
+ <item>
+ <p>When something is executed</p>
+
+ <p>
+ There are several examples where you have to run a
+ program at system startup or shutdown to perform a
+ specific task, for example, setting the system's clock
+ using <prgn>netdate</prgn> or killing all processes
+ when the system shuts down. Your message should look
+ like this:
<example compact="compact">
-http://localhost/cgi-bin/<var>cgi-bin-name</var>
+Doing something very useful...done.
</example>
- </item>
-
- <item>
- <p>Access to HTML documents</p>
-
- <p>
- HTML documents for a package are stored in
- <file>/usr/share/doc/<var>package</var></file>
- and can be referred to as
+ You should print the <tt>done.</tt> immediately after
+ the job has been completed, so that the user is
+ informed why she has to wait. You can get this
+ behavior by saying
<example compact="compact">
-http://localhost/doc/<var>package</var>/<var>filename</var>
+echo -n "Doing something very useful..."
+do_something
+echo "done."
</example>
- </p>
-
- <p>
- The web server should restrict access to the document
- tree so that only clients on the same host can read
- the documents. If the web server does not support such
- access controls, then it should not provide access at
- all, or ask about providing access during installation.
+ in your script.
</p>
</item>
<item>
- <p>Web Document Root</p>
+ <p>When the configuration is reloaded</p>
<p>
- Web Applications should try to avoid storing files in
- the Web Document Root. Instead they should use the
- /usr/share/doc/<var>package</var> directory for
- documents and register the Web Application via the
- menu package. If access to the web document root is
- unavoidable then use
+ When a daemon is forced to reload its configuration
+ files you should use the following format:
<example compact="compact">
-/var/www
+Reloading <var>description</var> configuration...done.
</example>
- as the Document Root. This might be just a symbolic
- link to the location where the system administrator
- has put the real document root.
+ where <var>description</var> is the same as in the
+ daemon starting message.
</p>
</item>
-
- </enumlist>
+ </list>
</p>
</sect>
- <sect id="mail-transport-agents">
- <heading>Mail transport, delivery and user agents</heading>
+ <sect>
+ <heading>Cron jobs</heading>
<p>
- Debian packages which process electronic mail, whether mail
- user agents (MUAs) or mail transport agents (MTAs), must
- ensure that they are compatible with the configuration
- decisions below. Failure to do this may result in lost
- mail, broken <tt>From:</tt> lines, and other serious brain
- damage!
- </p>
+ Packages must not modify the configuration file
+ <file>/etc/crontab</file>, and they must not modify the files in
+ <file>/var/spool/cron/crontabs</file>.</p>
<p>
- The mail spool is <file>/var/mail</file> and the interface to
- send a mail message is <file>/usr/sbin/sendmail</file> (as per
- the FHS). On older systems, the mail spool may be
- physically located in <file>/var/spool/mail</file>, but all
- access to the mail spool should be via the
- <file>/var/mail</file> symlink. The mail spool is part of the
- base system and not part of the MTA package.
- </p>
+ If a package wants to install a job that has to be executed
+ via cron, it should place a file with the name of the
+ package in one or more of the following directories:
+ <example compact="compact">
+/etc/cron.daily
+/etc/cron.weekly
+/etc/cron.monthly
+ </example>
+ As these directory names imply, the files within them are
+ executed on a daily, weekly, or monthly basis,
+ respectively. The exact times are listed in
+ <file>/etc/crontab</file>.</p>
<p>
- All Debian MUAs, MTAs, MDAs and other mailbox accessing
- programs (such as IMAP daemons) must lock the mailbox in an
- NFS-safe way. This means that <tt>fcntl()</tt> locking must
- be combined with dot locking. To avoid deadlocks, a program
- should use <tt>fcntl()</tt> first and dot locking after
- this, or alternatively implement the two locking methods in
- a non blocking way<footnote>
- 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.
- </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>
- </footnote> packages is the recommended way to realize this.
+ All files installed in any of these directories must be
+ scripts (e.g., shell scripts or Perl scripts) so that they
+ can easily be modified by the local system administrator.
+ In addition, they should be treated as configuration
+ files.
</p>
<p>
- Mailboxes are generally mode 660
- <tt><var>user</var>.mail</tt> unless the system
- administrator has chosen otherwise. A MUA may remove a
- mailbox (unless it has nonstandard permissions) in which
- case the MTA or another MUA must recreate it if needed.
- Mailboxes must be writable by group mail.
- </p>
+ If a certain job has to be executed more frequently than
+ daily, the package should install a file
+ <file>/etc/cron.d/<var>package</var></file>. This file uses the
+ same syntax as <file>/etc/crontab</file> and is processed by
+ <prgn>cron</prgn> automatically. The file must also be
+ treated as a configuration file. (Note that entries in the
+ <file>/etc/cron.d</file> directory are not handled by
+ <prgn>anacron</prgn>. Thus, you should only use this
+ directory for jobs which may be skipped if the system is not
+ running.)</p>
<p>
- The mail spool is 2775 <tt>root.mail</tt>, and MUAs should
- be setgid mail to do the locking mentioned above (and
- must obviously avoid accessing other users' mailboxes
- using this privilege).</p>
+ The scripts or crontab entries in these directories should
+ check if all necessary programs are installed before they
+ try to execute them. Otherwise, problems will arise when a
+ package was removed but not purged since configuration files
+ are kept on the system in this situation.</p>
+ </sect>
+
+ <sect id="menus">
+ <heading>Menus</heading>
<p>
- <file>/etc/aliases</file> is the source file for the system mail
- aliases (e.g., postmaster, usenet, etc.), it is the one
- which the sysadmin and <prgn>postinst</prgn> scripts may
- edit. After <file>/etc/aliases</file> is edited the program or
- human editing it must call <prgn>newaliases</prgn>. All MTA
- packages must come with a <prgn>newaliases</prgn> program,
- even if it does nothing, but older MTA packages did not do
- this so programs should not fail if <prgn>newaliases</prgn>
- cannot be found. Note that because of this, all MTA
- packages must have <tt>Provides</tt>, <tt>Conflicts</tt> and
- <tt>Replaces: mail-transport-agent</tt> control file
- fields.
+ The Debian <tt>menu</tt> package provides a standard
+ interface between packages providing applications and
+ documents, and <em>menu programs</em> (either X window
+ managers or text-based menu programs such as
+ <prgn>pdmenu</prgn>).
</p>
<p>
- The convention of writing <tt>forward to
- <var>address</var></tt> in the mailbox itself is not
- supported. Use a <tt>.forward</tt> file instead.</p>
+ All packages that provide applications that need not be
+ passed any special command line arguments for normal
+ 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>
<p>
- The <prgn>rmail</prgn> program used by UUCP
- for incoming mail should be <file>/usr/sbin/rmail</file>.
- Likewise, <prgn>rsmtp</prgn>, for receiving
- batch-SMTP-over-UUCP, should be <file>/usr/sbin/rsmtp</file> if it
- is supported.</p>
+ Menu entries should follow the current menu policy.
+ </p>
<p>
- If your package needs to know what hostname to use on (for
- example) outgoing news and mail messages which are generated
- locally, you should use the file <file>/etc/mailname</file>. It
- will contain the portion after the username and <tt>@</tt>
- (at) sign for email addresses of users on the machine
- (followed by a newline).
+ 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>
- Such package should check for the existence of this file
- when it is being configured. If it exists, it should be
- used without comment, although an MTA's configuration script
- may wish to prompt the user even if it finds that this file
- exists. If the file does not exist, the package should
- prompt the user for the value (preferably using
- <prgn>debconf</prgn>) and store it in <file>/etc/mailname</file>
- as well as using it in the package's configuration. The
- prompt should make it clear that the name will not just be
- used by that package. For example, in this situation the
- <tt>inn</tt> package could say something like:
- <example compact="compact">
-Please enter the "mail name" of your system. This is the
-hostname portion of the address to be shown on outgoing
-news and mail messages. The default is
-<var>syshostname</var>, your system's host name. Mail
-name ["<var>syshostname</var>"]:
- </example>
- where <var>syshostname</var> is the output of <tt>hostname
- --fqdn</tt>.
+ Please also refer to the <em>Debian Menu System</em>
+ documentation that comes with the <tt>menu</tt> package for
+ information about how to register your applications and web
+ documents.
</p>
</sect>
- <sect>
- <heading>News system configuration</heading>
+ <sect id="mime">
+ <heading>Multimedia handlers</heading>
<p>
- All the configuration files related to the NNTP (news)
- servers and clients should be located under
- <file>/etc/news</file>.</p>
+ MIME (Multipurpose Internet Mail Extensions, RFCs 2045-2049)
+ is a mechanism for encoding files and data streams and
+ providing meta-information about them, in particular their
+ type (e.g. audio or video) and format (e.g. PNG, HTML,
+ MP3).
+ </p>
<p>
- There are some configuration issues that apply to a number
- of news clients and server packages on the machine. These
- are:
-
- <taglist>
- <tag><file>/etc/news/organization</file></tag>
- <item>
- A string which should appear as the
- organization header for all messages posted
- by NNTP clients on the machine
- </item>
+ 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.
+ </p>
- <tag><file>/etc/news/server</file></tag>
- <item>
- Contains the FQDN of the upstream NNTP
- server, or localhost if the local machine is
- an NNTP server.
- </item>
- </taglist>
+ <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>
- Other global files may be added as required for cross-package news
- configuration.
+ <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>
<sect>
- <heading>Programs for the X Window System</heading>
+ <heading>Keyboard configuration</heading>
- <sect1>
- <heading>Providing X support and package priorities</heading>
+ <p>
+ To achieve a consistent keyboard configuration so that all
+ applications interpret a keyboard event the same way, all
+ programs in the Debian distribution must be configured to
+ comply with the following guidelines.
+ </p>
- <p>
- Programs that can be configured with support for the X
- Window System must be configured to do so and must declare
- any package dependencies necessary to satisfy their
- runtime requirements when using the X Window System. If
- such a package is of higher priority than the X packages
- on which it depends, it is required that either the
- X-specific components be split into a separate package, or
- that an alternative version of the package, which includes
- X support, be provided, or that the package's priority be
- lowered.
- </p>
- </sect1>
+ <p>
+ The following keys must have the specified interpretations:
- <sect1>
- <heading>Packages providing an X server</heading>
+ <taglist>
+ <tag><tt><--</tt></tag>
+ <item>delete the character to the left of the cursor</item>
- <p>
- Packages that provide an X server that, directly or
- indirectly, communicates with real input and display
- hardware should declare in their control data that they
- provide the virtual package <tt>xserver</tt>.<footnote>
- This implements current practice, and provides an
- actual policy for usage of the <tt>xserver</tt>
- virtual package which appears in the virtual packages
- list. In a nutshell, X servers that interface
- directly with the display and input hardware or via
- another subsystem (e.g., GGI) should provide
- <tt>xserver</tt>. Things like <tt>Xvfb</tt>,
- <tt>Xnest</tt>, and <tt>Xprt</tt> should not.
- </footnote>
- </p>
- </sect1>
+ <tag><tt>Delete</tt></tag>
+ <item>delete the character to the right of the cursor</item>
- <sect1>
- <heading>Packages providing a terminal emulator</heading>
+ <tag><tt>Control+H</tt></tag>
+ <item>emacs: the help prefix</item>
+ </taglist>
- <p>
- Packages that provide a terminal emulator for the X Window
- System which meet the criteria listed below should declare
- in their control data that they provide the virtual
- package <tt>x-terminal-emulator</tt>. They should also
- register themselves as an alternative for
- <file>/usr/bin/x-terminal-emulator</file>, with a priority of
- 20.
- </p>
+ The interpretation of any keyboard events should be
+ independent of the terminal that is used, be it a virtual
+ console, an X terminal emulator, an rlogin/telnet session,
+ etc.
+ </p>
- <p>
- To be an <tt>x-terminal-emulator</tt>, a program must:
- <list compact="compact">
- <item>
- Be able to emulate a DEC VT100 terminal, or a
- compatible terminal.
- </item>
+ <p>
+ The following list explains how the different programs
+ should be set up to achieve this:
+ </p>
- <item>
- Support the command-line option <tt>-e
- <var>command</var></tt>, which creates a new
- terminal window<footnote>
- "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).
- </footnote>
- 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>
+ <p>
+ <list>
+ <item>
+ <tt><--</tt> generates <tt>KB_BackSpace</tt> in X.
+ </item>
- <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>.
- </item>
- </list>
- </p>
- </sect1>
+ <item>
+ <tt>Delete</tt> generates <tt>KB_Delete</tt> in X.
+ </item>
- <sect1>
- <heading>Packages providing a window manager</heading>
+ <item>
+ X translations are set up to make
+ <tt>KB_Backspace</tt> generate ASCII DEL, and to make
+ <tt>KB_Delete</tt> generate <tt>ESC [ 3 ~</tt> (this
+ is the vt220 escape code for the "delete character"
+ key). This must be done by loading the X resources
+ using <prgn>xrdb</prgn> on all local X displays, not
+ using the application defaults, so that the
+ translation resources used correspond to the
+ <prgn>xmodmap</prgn> settings.
+ </item>
- <p>
- Packages that provide a window manager should declare in
- their control data that they provide the virtual package
- <tt>x-window-manager</tt>. They should also register
- themselves as an alternative for
- <file>/usr/bin/x-window-manager</file>, with a priority
- calculated as follows:
- <list compact="compact">
- <item>
- Start with a priority of 20.
- </item>
+ <item>
+ The Linux console is configured to make
+ <tt><--</tt> generate DEL, and <tt>Delete</tt>
+ generate <tt>ESC [ 3 ~</tt>.
+ </item>
- <item>
- If the window manager supports the Debian menu
- system, add 20 points if this support is available
- in the package's default configuration (i.e., no
- configuration files belonging to the system or user
- have to be edited to activate the feature); if
- configuration files must be modified, add only 10
- points.
- </item>
+ <item>
+ X applications are configured so that <tt><</tt>
+ deletes left, and <tt>Delete</tt> deletes right. Motif
+ applications already work like this.
+ </item>
- <item>
- 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 40 points.
- </item>
+ <item>
+ Terminals should have <tt>stty erase ^?</tt> .
+ </item>
- <item>
- If the window manager permits the X session to be
- restarted using a <em>different</em> window manager
- (without killing the X server) in its default
- configuration, add 10 points; otherwise add none.
- </item>
- </list>
- </p>
- </sect1>
+ <item>
+ 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>.
+ </item>
- <sect1>
- <heading>Packages providing fonts</heading>
+ <item>
+ 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.
+ </item>
- <p>
- Packages that provide fonts for the X Window
- System<footnote>
- For the purposes of Debian Policy, a "font for the X
- Window System" is one which is accessed via X protocol
- requests. Fonts for the Linux console, for PostScript
- renderers, or any other purpose, do not fit this
- definition. Any tool which makes such fonts available
- to the X Window System, however, must abide by this
- font policy.
- </footnote>
- must do a number of things to ensure that they are both
- available without modification of the X or font server
- configuration, and that they do not corrupt files used by
- other font packages to register information about
- themselves.
- <enumlist>
- <item>
- Fonts of any type supported by the X Window System
- must be in a separate binary package from any
- executables, libraries, or documentation (except
- that specific to the fonts shipped, such as their
- license information). If one or more of the fonts
- so packaged are necessary for proper operation of
- the package with which they are associated the font
- package may be Recommended; if the fonts merely
- provide an enhancement, a Suggests relationship may
- be used. Packages must not Depend on font
- packages.<footnote>
- 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.
- </footnote>
- </item>
+ <item>
+ 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".
+ </item>
- <item>
- 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>
- 100 dpi fonts must be placed in
- <file>/usr/X11R6/lib/X11/fonts/100dpi/</file>.
- </item>
+ </list>
+ </p>
+
+ <p>
+ This will solve the problem except for the following
+ cases:
+ </p>
+
+ <p>
+ <list>
+ <item>
+ 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.
+ </item>
- <item>
- 75 dpi fonts must be placed in
- <file>/usr/X11R6/lib/X11/fonts/75dpi/</file>.
- </item>
+ <item>
+ 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.
+ </item>
- <item>
- Character-cell fonts, cursor fonts, and other
- low-resolution fonts must be placed in
- <file>/usr/X11R6/lib/X11/fonts/misc/</file>.
- </item>
- </list>
- </item>
+ <item>
+ Some systems (including previous Debian versions) use
+ <prgn>xmodmap</prgn> to arrange for both
+ <tt><--</tt> and <tt>Delete</tt> to generate
+ <tt>KB_Delete</tt>. We can change the behavior of
+ their X clients using the same X resources that we use
+ to do it for our own clients, or configure our clients
+ using their resources when things are the other way
+ around. On displays configured like this
+ <tt>Delete</tt> will not work, but <tt><--</tt>
+ will.
+ </item>
- <item>
- Speedo fonts must be placed in
- <file>/usr/X11R6/lib/X11/fonts/Speedo/</file>.
- </item>
+ <item>
+ 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.
+ </item>
+ </list>
+ </p>
+ </sect>
- <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.
- </item>
+ <sect>
+ <heading>Environment variables</heading>
- <item>
- 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.)
- </item>
+ <p>
+ A program must not depend on environment variables to get
+ 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>
- <item>
- 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.
- </item>
+ <p>
+ If a program usually depends on environment variables for its
+ configuration, the program should be changed to fall back to
+ a reasonable default configuration if these environment
+ variables are not present. If this cannot be done easily
+ (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>
- <item>
- Font packages should not contain both 75dpi and
- 100dpi versions of a font. If both are available,
- they should be provided in separate binary packages
- with <tt>-75dpi</tt> or <tt>-100dpi</tt> appended to
- the names of the packages containing the
- corresponding fonts.
- </item>
+ <p>
+ Here is an example of a wrapper script for this purpose:
- <item>
- 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.
- </item>
+ <example compact="compact">
+#!/bin/sh
+BAR=${BAR:-/var/lib/fubar}
+export BAR
+exec /usr/lib/foo/foo "$@"
+ </example>
+ </p>
- <item>
- 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>
- <file>fonts.dir</file> files must not be provided at all.
- </item>
+ <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>
+ </sect>
- <item>
- <file>fonts.alias</file> and <file>fonts.scale</file>
- files, if needed, should be provided in the
- directory
- <file>/etc/X11/fonts/<var>fontdir</var>/<var>package</var>.<var>extension</var></file>,
- where <var>fontdir</var> is the name of the
- subdirectory of
- <file>/usr/X11R6/lib/X11/fonts/</file> where the
- package's corresponding fonts are stored
- (e.g., <tt>75dpi</tt> or <tt>misc</tt>),
- <var>package</var> is the name of the package
- that provides these fonts, and
- <var>extension</var> is either <tt>scale</tt>
- or <tt>alias</tt>, whichever corresponds to
- the file contents.
- </item>
- </list>
- </item>
+ </chapt>
- <item>
- Font packages must declare a dependency on
- <tt>xutils (>> 4.0.3)</tt> in their control
- data.
- </item>
- <item>
- Font packages that provide one or more
- <file>fonts.scale</file> files as described above must
- invoke <prgn>update-fonts-scale</prgn> on each
- directory into which they installed fonts
- <em>before</em> invoking
- <prgn>update-fonts-dir</prgn> on that directory.
- This invocation must occur in both the
- <prgn>postinst</prgn> (for all arguments) and
- <prgn>postrm</prgn> (for all arguments except
- <tt>upgrade</tt>) scripts.
- </item>
+ <chapt id="files">
+ <heading>Files</heading>
- <item>
- Font packages that provide one or more
- <file>fonts.alias</file> files as described above must
- invoke <prgn>update-fonts-alias</prgn> on each
- directory into which they installed fonts. This
- invocation must occur in both the
- <prgn>postinst</prgn> (for all arguments) and
- <prgn>postrm</prgn> (for all arguments except
- <tt>upgrade</tt>) scripts.
- </item>
+ <sect>
+ <heading>Binaries</heading>
- <item>
- 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.
- </item>
+ <p>
+ Two different packages must not install programs with
+ different functionality but with the same filenames. (The
+ case of two programs having the same functionality but
+ different implementations is handled via "alternatives" or
+ the "Conflicts" mechanism. See <ref id="maintscripts"> and
+ <ref id="conflicts"> respectively.) If this case happens,
+ one of the programs must be renamed. The maintainers should
+ report this to the <tt>debian-devel</tt> mailing list and
+ try to find a consensus about which program will have to be
+ renamed. If a consensus cannot be reached, <em>both</em>
+ programs must be renamed.
+ </p>
- <item>
- Font packages must not provide alias names for the
- fonts they include which collide with alias names
- already in use by fonts already packaged.
- </item>
+ <p>
+ By default, when a package is being built, any binaries
+ created should include debugging information, as well as
+ being compiled with optimization. You should also turn on
+ as many reasonable compilation warnings as possible; this
+ makes life easier for porters, who can then look at build
+ logs for possible problems. For the C programming language,
+ this means the following compilation parameters should be
+ used:
+ <example compact="compact">
+CC = gcc
+CFLAGS = -O2 -g -Wall # sane warning options vary between programs
+LDFLAGS = # none
+install -s # (or use strip on the files in debian/tmp)
+ </example>
+ </p>
- <item>
- Font packages must not provide fonts with the same
- XLFD registry name as another font already packaged.
- </item>
- </enumlist>
- </p>
- </sect1>
+ <p>
+ Note that by default all installed binaries should be stripped,
+ either by using the <tt>-s</tt> flag to
+ <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>
- <sect1>
- <heading>Application defaults files</heading>
+ <p>
+ Although binaries in the build tree should be compiled with
+ debugging information by default, it can often be difficult
+ to debug programs if they are also subjected to compiler
+ optimization. For this reason, it is recommended to support
+ the standardized environment
+ variable <tt>DEB_BUILD_OPTIONS</tt>. This variable can
+ contain several flags to change how a package is compiled
+ and built.
+ </p>
- <p>
- Application defaults files must be installed in the
- directory <file>/etc/X11/app-defaults/</file> (use of a
- localized subdirectory of <file>/etc/X11/</file> as described
- in the <em>X Toolkit Intrinsics - C Language
- Interface</em> manual is also permitted). They must be
- registered as <tt>conffile</tt>s or handled as
- configuration files. Packages must not provide the
- directory <file>/usr/X11R6/lib/X11/app-defaults/</file>.
- </p>
+ <p>
+ <taglist>
+ <tag>noopt</tag>
+ <item>
+ The presence of this string means that the package
+ 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.
+ </item>
+ <tag>nostrip</tag>
+ <item>
+ 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.
+ </item>
+ </taglist>
+ </p>
- <p>
- Customization of programs' X resources may also be
- supported with the provision of a file with the same name
- as that of the package placed in the
- <file>/etc/X11/Xresources/</file> directory, which must
- registered as a <tt>conffile</tt> or handled as a
- configuration file.<footnote>
- 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.
- </footnote>
- <em>Important:</em> packages that install files into the
- <file>/etc/X11/Xresources/</file> directory must conflict with
- <tt>xbase (<< 3.3.2.3a-2)</tt>; if this is not done
- it is possible for the installing package to destroy a
- previously-existing <file>/etc/X11/Xresources</file> file
- which had been customized by the system administrator.
- </p>
- </sect1>
+ <p>
+ The following makefile snippet is an example of how one may
+ implement the build options; you will probably have to
+ massage this example in order to make it work for your
+ package.
+ <example compact="compact">
+CFLAGS = -Wall -g
+INSTALL = install
+INSTALL_FILE = $(INSTALL) -p -o root -g root -m 644
+INSTALL_PROGRAM = $(INSTALL) -p -o root -g root -m 755
+INSTALL_SCRIPT = $(INSTALL) -p -o root -g root -m 755
+INSTALL_DIR = $(INSTALL) -p -d -o root -g root -m 755
- <sect1>
- <heading>Installation directory issues</heading>
+ifneq (,$(findstring noopt,$(DEB_BUILD_OPTIONS)))
+CFLAGS += -O0
+else
+CFLAGS += -O2
+endif
+ifeq (,$(findstring nostrip,$(DEB_BUILD_OPTIONS)))
+INSTALL_PROGRAM += -s
+endif
+ </example>
+ </p>
- <p>
- Packages using the X Window System should not be
- configured to install files under the <file>/usr/X11R6/</file>
- directory unless they use <prgn>imake</prgn>. The
- <file>/usr/X11R6/</file> directory hierarchy should be
- regarded as deprecated for all packages except the X
- Window System itself, and those which use the
- <prgn>imake</prgn> program it provides, in which case the
- packages may transition out of the <file>/usr/X11R6/</file>
- directory at the maintainer's discretion.<footnote>
- <prgn>Imake</prgn>-using programs are exempt because,
- as long as they are written correctly, the pathnames
- they use to locate resources and install themselves
- are derived wholly from the X Window System
- configuration. Thus, in the event that the X Window
- System moves to <file>/usr/X11R7/</file>,
- <file>/usr/X12/</file>, or just plain <file>/usr/</file>, all
- that is required for these programs is a recompile
- against the corresponding X Window System library
- development packages.
- </footnote>
- </p>
+ <p>
+ It is up to the package maintainer to decide what
+ compilation options are best for the package. Certain
+ binaries (such as computationally-intensive programs) will
+ function better with certain flags (<tt>-O3</tt>, for
+ example); feel free to use them. Please use good judgment
+ here. Don't use flags for the sake of it; only use them
+ if there is good reason to do so. Feel free to override
+ the upstream author's ideas about which compilation
+ options are best: they are often inappropriate for our
+ environment.
+ </p>
+ </sect>
- <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
- <file>/usr/X11R6/</file>, and this should be done whenever
- possible. Configuration files for window managers and
- display managers should be placed in a subdirectory of
- <file>/etc/X11/</file> corresponding to the package name due
- to these programs' tight integration with the mechanisms
- of the X Window System. Application-level programs should
- use the <file>/etc/</file> directory unless otherwise mandated
- 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
- <file>/usr/lib/</file> and <file>/usr/share/</file> can be used
- 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.)
- </p>
+ <sect id="libraries">
+ <heading>Libraries</heading>
- <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
- their <tt>X11R6</tt>-named counterparts
- <file>/usr/X11R6/bin/</file>, <file>/usr/X11R6/include/X11/</file>
- and <file>/usr/X11R6/lib/X11/</file>, if the resources being
- referred to have not been moved to other FHS-compliant
- locations.
- </p>
- </sect1>
+ <p>
+ The shared version of a library must be compiled with
+ <tt>-fPIC</tt>, and the static version must not be. In other
+ words, each source unit (<tt>*.c</tt>, for example, for C files)
+ will need to be compiled twice.
+ </p>
- <sect1>
- <heading>The OSF/Motif and OpenMotif libraries</heading>
+ <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>
- <em>Programs that require the non-DFSG-compliant OSF/Motif or
- OpenMotif libraries</em><footnote>
- OSF/Motif and OpenMotif are collectively referred to as
- "Motif" in this policy document.
- </footnote>
- should be compiled against and tested with LessTif (a free
- re-implementation of Motif) instead. If the maintainer
- judges that the program or programs do not work
- sufficiently well with LessTif to be distributed and
- supported, but do so when compiled against Motif, then two
- versions of the package should be created; one linked
- statically against Motif and with <tt>-smotif</tt>
- appended to the package name, and one linked dynamically
- against Motif and with <tt>-dmotif</tt> appended to the
- package name.
- </p>
+ <p>
+ All installed shared libraries should be stripped with
+ <example compact="compact">
+strip --strip-unneeded <var>your-lib</var>
+ </example>
+ (The option <tt>--strip-unneeded</tt> makes
+ <prgn>strip</prgn> remove only the symbols which aren't
+ needed for relocation processing.) Shared libraries can
+ function perfectly well when stripped, since the symbols for
+ dynamic linking are in a separate part of the ELF object
+ file.<footnote>
+ 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.
+ </footnote>
+ </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
- the <em>contrib</em> distribution. While known existing
- versions of Motif permit unlimited redistribution of
- binaries linked against the library (whether statically or
- dynamically), it is the package maintainer's
- responsibility to determine whether this is permitted by
- the license of the copy of Motif in his or her possession.
- </p>
- </sect1>
- </sect>
+ <p>
+ Note that under some circumstances it may be useful to
+ install a shared library unstripped, for example when
+ building a separate package to support debugging.
+ </p>
- <sect id="perl">
- <heading>Perl programs and modules</heading>
+ <p>
+ Shared object files (often <file>.so</file> files) that are not
+ public libraries, that is, they are not meant to be linked
+ to by third party executables (binaries of other packages),
+ should be installed in subdirectories of the
+ <file>/usr/lib</file> directory. Such files are exempt from the
+ rules that govern ordinary shared libraries, except that
+ they must not be installed executable and should be
+ stripped.<footnote>
+ A common example are the so-called "plug-ins",
+ internal shared objects that are dynamically loaded by
+ programs using <manref name="dlopen" section="3">.
+ </footnote>
+ </p>
<p>
- Perl programs and modules should follow the current Perl policy.
+ Packages containing shared libraries that may be linked to
+ by other packages' binaries, but which for some
+ <em>compelling</em> reason can not be installed in
+ <file>/usr/lib</file> directory, may install the shared library
+ files in subdirectories of the <file>/usr/lib</file> directory,
+ in which case they should arrange to add that directory in
+ <file>/etc/ld.so.conf</file> in the package's post-installation
+ script, and remove it in the package's post-removal script.
</p>
<p>
- The Perl policy can be found in the <tt>perl-policy</tt>
- files in the <tt>debian-policy</tt> package.
- They are also available from the Debian web mirrors at
- <tt><url name="/doc/packaging-manuals/perl-policy/"
- id="http://www.debian.org/doc/packaging-manuals/perl-policy/"></tt>
- and from the Debian archive mirrors at
- <tt><url name="/doc/package-developer/perl-policy.txt.gz"
- id="http://ftp.debian.org/debian/doc/package-developer/perl-policy.txt.gz"></tt>.
+ An ever increasing number of packages are using
+ <prgn>libtool</prgn> to do their linking. The latest GNU
+ libtools (>= 1.3a) can take advantage of the metadata in the
+ installed <prgn>libtool</prgn> archive files (<file>*.la</file>
+ files). The main advantage of <prgn>libtool</prgn>'s
+ <file>.la</file> files is that it allows <prgn>libtool</prgn> to
+ store and subsequently access metadata with respect to the
+ libraries it builds. <prgn>libtool</prgn> will search for
+ those files, which contain a lot of useful information about
+ a library (such as library dependency information for static
+ linking). Also, they're <em>essential</em> for programs
+ using <tt>libltdl</tt>.<footnote>
+ Although <prgn>libtool</prgn> is fully capable of
+ linking against shared libraries which don't have
+ <tt>.la</tt> files, as it is a mere shell script it can
+ add considerably to the build time of a
+ <prgn>libtool</prgn>-using package if that shell script
+ has to derive all this information from first principles
+ for each library every time it is linked. With the
+ advent of <prgn>libtool</prgn> version 1.4 (and to a
+ lesser extent <prgn>libtool</prgn> version 1.3), the
+ <file>.la</file> files also store information about
+ inter-library dependencies which cannot necessarily be
+ derived after the <file>.la</file> file is deleted.
+ </footnote>
</p>
- </sect>
-
- <sect id="emacs">
- <heading>Emacs lisp programs</heading>
<p>
- Please refer to the "Debian Emacs Policy" for details of how to
- package emacs lisp programs.
+ Packages that use <prgn>libtool</prgn> to create shared
+ libraries should include the <file>.la</file> files in the
+ <tt>-dev</tt> package, unless the package relies on
+ <tt>libtool</tt>'s <tt>libltdl</tt> library, in which case
+ the <tt>.la</tt> files must go in the run-time library
+ package.
</p>
<p>
- 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>.
+ You must make sure that you use only released versions of
+ shared libraries to build your packages; otherwise other
+ users will not be able to run your binaries
+ properly. Producing source packages that depend on
+ unreleased compilers is also usually a bad
+ idea.
</p>
</sect>
- <sect>
- <heading>Games</heading>
+ <sect>
+ <heading>Shared libraries</heading>
<p>
- The permissions on <file>/var/games</file> are mode 755, owner
- <tt>root</tt> and group <tt>root</tt>.
+ This section has moved to <ref id="sharedlibs">.
</p>
+ </sect>
- <p>
- Each game decides on its own security policy.</p>
- <p>
- Games which require protected, privileged access to
- high-score files, savegames, etc., may be made
- set-<em>group</em>-id (mode 2755) and owned by
- <tt>root.games</tt>, and use files and directories with
- appropriate permissions (770 <tt>root.games</tt>, for
- example). They must not be made
- set-<em>user</em>-id, as this causes security problems. (If
- an attacker can subvert any set-user-id game they can
- overwrite the executable of any other, causing other players
- of these games to run a Trojan horse program. With a
- set-group-id game the attacker only gets access to less
- important game data, and if they can get at the other
- players' accounts at all it will take considerably more
- effort.)</p>
+ <sect id="scripts">
+ <heading>Scripts</heading>
<p>
- Some packages, for example some fortune cookie programs, are
- configured by the upstream authors to install with their
- data files or other static information made unreadable so
- that they can only be accessed through set-id programs
- provided. You should not do this in a Debian package: anyone can
- download the <file>.deb</file> file and read the data from it,
- so there is no point making the files unreadable. Not
- making the files unreadable also means that you don't have
- to make so many programs set-id, which reduces the risk of a
- security hole.</p>
+ All command scripts, including the package maintainer
+ scripts inside the package and used by <prgn>dpkg</prgn>,
+ should have a <tt>#!</tt> line naming the shell to be used
+ to interpret them.
+ </p>
<p>
- As described in the FHS, binaries of games should be
- installed in the directory <file>/usr/games</file>. This also
- applies to games that use the X Window System. Manual pages
- for games (X and non-X games) should be installed in
- <file>/usr/share/man/man6</file>.</p>
- </sect>
- </chapt>
-
- <chapt id="docs"><heading>Documentation</heading>
-
+ In the case of Perl scripts this should be
+ <tt>#!/usr/bin/perl</tt>.
+ </p>
- <sect>
- <heading>Manual pages</heading>
+ <p>
+ Shell scripts (<prgn>sh</prgn> and <prgn>bash</prgn>)
+ should almost certainly start with <tt>set -e</tt> so that
+ errors are detected. Every script should use
+ <tt>set -e</tt> or check the exit status of <em>every</em>
+ command.
+ </p>
<p>
- You should install manual pages in <prgn>nroff</prgn> source
- form, in appropriate places under <file>/usr/share/man</file>.
- You should only use sections 1 to 9 (see the FHS for more
- details). You must not install a preformatted "cat page".
+ 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>
+ 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
+ policy, the Linux kernel source, many Debian scripts,
+ etc.). This <tt>echo -n</tt> mechanism is valid but not
+ required under POSIX, hence this explicit addition.
+ Also, rumour has it that this shall be mandated under
+ the LSB anyway.
+ </footnote>
+ Thus, shell scripts specifying <file>/bin/sh</file> as
+ interpreter should only use POSIX features. If a script
+ requires non-POSIX features from the shell interpreter, the
+ appropriate shell must be specified in the first line of the
+ script (e.g., <tt>#!/bin/bash</tt>) and the package must
+ depend on the package providing the shell (unless the shell
+ package is marked "Essential", as in the case of
+ <prgn>bash</prgn>).
</p>
<p>
- Each program, utility, and function should have an
- associated manual page included in the same package. It is
- suggested that all configuration files also have a manual
- page included as well. Manual pages for protocols and other
- auxiliary things are optional.
+ You may wish to restrict your script to POSIX features when
+ possible so that it may use <file>/bin/sh</file> as its
+ interpreter. If your script works with <prgn>dash</prgn>
+ (originally called <prgn>ash</prgn>), it's probably POSIX
+ compliant, but if you are in doubt, use
+ <file>/bin/bash</file>.
</p>
<p>
- If no manual page is available, this is considered as a bug
- and should be reported to the Debian Bug Tracking System (the
- 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>
- 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">,
- <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>.
- </footnote>
+ Perl scripts should check for errors when making any
+ system calls, including <tt>open</tt>, <tt>print</tt>,
+ <tt>close</tt>, <tt>rename</tt> and <tt>system</tt>.
</p>
<p>
- You may forward a complaint about a missing manpage to the
- upstream authors, and mark the bug as forwarded in the
- Debian bug tracking system. Even though the GNU Project do
- not in general consider the lack of a manpage to be a bug,
- we do; if they tell you that they don't consider it a bug
- you should leave the bug in our bug tracking system open
- anyway.
- </p>
+ <prgn>csh</prgn> and <prgn>tcsh</prgn> should be avoided as
+ scripting languages. See <em>Csh Programming Considered
+ Harmful</em>, one of the <tt>comp.unix.*</tt> FAQs, which
+ 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
+ <prgn>c-shell</prgn> virtual package.
+ </p>
<p>
- Manual pages should be installed compressed using <tt>gzip -9</tt>.
- </p>
+ 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>
<p>
- If one manpage needs to be accessible via several names it
- is better to use a symbolic link than the <file>.so</file>
- feature, but there is no need to fiddle with the relevant
- parts of the upstream source to change from <file>.so</file> to
- symlinks: don't do it unless it's easy. You should not
- create hard links in the manual page directories, nor put
- absolute filenames in <file>.so</file> directives. The filename
- in a <file>.so</file> in a manpage should be relative to the
- base of the manpage tree (usually
- <file>/usr/share/man</file>). If you do not create any links
- (whether symlinks, hard links, or <tt>.so</tt> directives)
- in the filesystem to the alternate names of the manpage,
- then you should not rely on <prgn>man</prgn> finding your
- manpage under those names based solely on the information in
- the manpage's header.<footnote>
- 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.
- </footnote>
- </p>
+ The Debian base system provides the <prgn>tempfile</prgn>
+ and <prgn>mktemp</prgn> utilities for use by scripts for
+ this purpose.
+ </p>
</sect>
+
<sect>
- <heading>Info documents</heading>
+ <heading>Symbolic links</heading>
<p>
- Info documents should be installed in <file>/usr/share/info</file>.
- They should be compressed with <tt>gzip -9</tt>.
- </p>
+ In general, symbolic links within a top-level directory
+ should be relative, and symbolic links pointing from one
+ top-level directory into another should be absolute. (A
+ top-level directory is a sub-directory of the root
+ directory <file>/</file>.)
+ </p>
<p>
- Your package should call <prgn>install-info</prgn> to update
- the Info <file>dir</file> file in its <prgn>postinst</prgn>
- script when called with a <tt>configure</tt> argument, for
- example:
- <example compact="compact">
-install-info --quiet --section Development Development \
- /usr/share/info/foobar.info
- </example></p>
+ In addition, symbolic links should be specified as short as
+ possible, i.e., link targets like <file>foo/../bar</file> are
+ deprecated.
+ </p>
<p>
- It is a good idea to specify a section for the location of
- your program; this is done with the <tt>--section</tt>
- switch. To determine which section to use, you should look
- at <file>/usr/share/info/dir</file> on your system and choose the most
- relevant (or create a new section if none of the current
- sections are relevant). Note that the <tt>--section</tt>
- flag takes two arguments; the first is a regular expression
- to match (case-insensitively) against an existing section,
- the second is used when creating a new one.</p>
+ Note that when creating a relative link using
+ <prgn>ln</prgn> it is not necessary for the target of the
+ link to exist relative to the working directory you're
+ running <prgn>ln</prgn> from, nor is it necessary to change
+ directory to the directory where the link is to be made.
+ Simply include the string that should appear as the target
+ of the link (this will be a pathname relative to the
+ directory in which the link resides) as the first argument
+ to <prgn>ln</prgn>.
+ </p>
<p>
- You should remove the entries in the <prgn>prerm</prgn>
- script when called with a <tt>remove</tt> argument:
+ For example, in your <prgn>Makefile</prgn> or
+ <file>debian/rules</file>, you can do things like:
<example compact="compact">
-install-info --quiet --remove /usr/share/info/foobar.info
- </example></p>
-
- <p>
- If <prgn>install-info</prgn> cannot find a description entry
- in the Info file you must supply one. See <manref
- name="install-info" section="8"> for details.</p>
- </sect>
-
- <sect>
- <heading>Additional documentation</heading>
+ln -fs gcc $(prefix)/bin/cc
+ln -fs gcc debian/tmp/usr/bin/cc
+ln -fs ../sbin/sendmail $(prefix)/bin/runq
+ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
+ </example>
+ </p>
<p>
- Any additional documentation that comes with the package may
- be installed at the discretion of the package maintainer.
- Text documentation should be installed in the directory
- <file>/usr/share/doc/<var>package</var></file>, where
- <var>package</var> is the name of the package, and
- compressed with <tt>gzip -9</tt> unless it is small.
- </p>
+ A symbolic link pointing to a compressed file should always
+ have the same file extension as the referenced file. (For
+ example, if a file <file>foo.gz</file> is referenced by a
+ symbolic link, the filename of the link has to end with
+ "<file>.gz</file>" too, as in <file>bar.gz</file>.)
+ </p>
+ </sect>
- <p>
- If a package comes with large amounts of documentation which
- many users of the package will not require you should create
- a separate binary package to contain it, so that it does not
- take up disk space on the machines of users who do not need
- or want it installed.</p>
+ <sect>
+ <heading>Device files</heading>
<p>
- It is often a good idea to put text information files
- (<file>README</file>s, changelogs, and so forth) that come with
- the source package in <file>/usr/share/doc/<var>package</var></file>
- in the binary package. However, you don't need to install
- the instructions for building and installing the package, of
- course!</p>
+ Packages must not include device files in the package file
+ tree.
+ </p>
<p>
- Packages must not require the existence of any files in
- <file>/usr/share/doc/</file> in order to function
- <footnote>
- The system administrator should be able to
- delete files in <file>/usr/share/doc/</file> without causing
- any programs to break.
+ 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>
+ This notification could be done via a (low-priority)
+ debconf message, or an echo (printf) statement.
</footnote>.
- Any files that are referenced by programs but are also
- useful as standalone documentation should be installed under
- <file>/usr/share/<var>package</var>/</file> with symbolic links from
- <file>/usr/share/doc/<var>package</var></file>.
</p>
<p>
- <file>/usr/share/doc/<var>package</var></file> may be a symbolic
- link to another directory in <file>/usr/share/doc</file> only if
- the two packages both come from the same source and the
- first package Depends on the second.
+ Packages must not remove any device files in the
+ <prgn>postrm</prgn> or any other script. This is left to the
+ system administrator.
</p>
<p>
- Former Debian releases placed all additional documentation
- in <file>/usr/doc/<var>package</var></file>. This has been
- 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>
- 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.
- </footnote>
+ 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>
</sect>
- <sect>
- <heading>Preferred documentation formats</heading>
+ <sect id="config-files">
+ <heading>Configuration files</heading>
+
+ <sect1>
+ <heading>Definitions</heading>
+
+ <p>
+ <taglist>
+ <tag>configuration file</tag>
+ <item>
+ A file that affects the operation of a program, or
+ provides site- or host-specific information, or
+ otherwise customizes the behavior of a program.
+ Typically, configuration files are intended to be
+ modified by the system administrator (if needed or
+ desired) to conform to local policy or to provide
+ more useful site-specific behavior.
+ </item>
+
+ <tag><tt>conffile</tt></tag>
+ <item>
+ A file listed in a package's <tt>conffiles</tt>
+ file, and is treated specially by <prgn>dpkg</prgn>
+ (see <ref id="configdetails">).
+ </item>
+ </taglist>
+ </p>
+
+ <p>
+ The distinction between these two is important; they are
+ not interchangeable concepts. Almost all
+ <tt>conffile</tt>s are configuration files, but many
+ configuration files are not <tt>conffiles</tt>.
+ </p>
+
+ <p>
+ Note that a script that embeds configuration information
+ (such as most of the files in <file>/etc/default</file> and
+ <file>/etc/cron.{daily,weekly,monthly}</file>) is de-facto a
+ configuration file and should be treated as such.
+ </p>
+ </sect1>
+
+ <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>
+
+ <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>
+ </sect1>
+
+ <sect1>
+ <heading>Behavior</heading>
+
+ <p>
+ Configuration file handling must conform to the following
+ behavior:
+ <list compact="compact">
+ <item>
+ local changes must be preserved during a package
+ upgrade, and
+ </item>
+ <item>
+ configuration files must be preserved when the
+ package is removed, and only deleted when the
+ package is purged.
+ </item>
+ </list>
+ </p>
+
+ <p>
+ The easy way to achieve this behavior is to make the
+ configuration file a <tt>conffile</tt>. This is
+ appropriate only if it is possible to distribute a default
+ version that will work for most installations, although
+ some system administrators may choose to modify it. This
+ implies that the default version will be part of the
+ package distribution, and must not be modified by the
+ maintainer scripts during installation (or at any other
+ time).
+ </p>
+
+ <p>
+ In order to ensure that local changes are preserved
+ correctly, no package may contain or make hard links to
+ conffiles.<footnote>
+ 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.
+ </footnote>
+ </p>
+
+ <p>
+ The other way to do it is via the maintainer scripts. In
+ this case, the configuration file must not be listed as a
+ <tt>conffile</tt> and must not be part of the package
+ distribution. If the existence of a file is required for
+ the package to be sensibly configured it is the
+ responsibility of the package maintainer to provide
+ maintainer scripts which correctly create, update and
+ maintain the file and remove it on purge. (See <ref
+ id="maintainerscripts"> for more information.) These
+ scripts must be idempotent (i.e., must work correctly if
+ <prgn>dpkg</prgn> needs to re-run them due to errors
+ during installation or removal), must cope with all the
+ variety of ways <prgn>dpkg</prgn> can call maintainer
+ scripts, must not overwrite or otherwise mangle the user's
+ configuration without asking, must not ask unnecessary
+ questions (particularly during upgrades), and otherwise be
+ good citizens.
+ </p>
+
+ <p>
+ The scripts are not required to configure every possible
+ option for the package, but only those necessary to get
+ the package running on a given system. Ideally the
+ sysadmin should not have to do any configuration other
+ than that done (semi-)automatically by the
+ <prgn>postinst</prgn> script.
+ </p>
+
+ <p>
+ A common practice is to create a script called
+ <file><var>package</var>-configure</file> and have the
+ package's <prgn>postinst</prgn> call it if and only if the
+ configuration file does not already exist. In certain
+ cases it is useful for there to be an example or template
+ file which the maintainer scripts use. Such files should
+ be in <file>/usr/share/<var>package</var></file> or
+ <file>/usr/lib/<var>package</var></file> (depending on whether
+ they are architecture-independent or not). There should
+ be symbolic links to them from
+ <file>/usr/share/doc/<var>package</var>/examples</file> if
+ they are examples, and should be perfectly ordinary
+ <prgn>dpkg</prgn>-handled files (<em>not</em>
+ configuration files).
+ </p>
+
+ <p>
+ These two styles of configuration file handling must
+ not be mixed, for that way lies madness:
+ <prgn>dpkg</prgn> will ask about overwriting the file
+ every time the package is upgraded.
+ </p>
+ </sect1>
+
+ <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>
+ with each other. (This is an instance of the general rule
+ about not sharing files. Note that neither alternatives
+ nor diversions are likely to be appropriate in this case;
+ in particular, <prgn>dpkg</prgn> does not handle diverted
+ <tt>conffile</tt>s well.)
+ </p>
+
+ <p>
+ The maintainer scripts must not alter a <tt>conffile</tt>
+ of <em>any</em> package, including the one the scripts
+ belong to.
+ </p>
+
+ <p>
+ If two or more packages use the same configuration file
+ and it is reasonable for both to be installed at the same
+ time, one of these packages must be defined as
+ <em>owner</em> of the configuration file, i.e., it will be
+ the package which handles that file as a configuration
+ file. Other packages that use the configuration file must
+ depend on the owning package if they require the
+ configuration file to operate. If the other package will
+ use the configuration file if present, but is capable of
+ operating without it, no dependency need be declared.
+ </p>
+
+ <p>
+ If it is desirable for two or more related packages to
+ share a configuration file <em>and</em> for all of the
+ related packages to be able to modify that configuration
+ file, then the following should be done:
+ <enumlist compact="compact">
+ <item>
+ One of the related packages (the "owning" package)
+ will manage the configuration file with maintainer
+ scripts as described in the previous section.
+ </item>
+ <item>
+ The owning package should also provide a program
+ that the other packages may use to modify the
+ configuration file.
+ </item>
+ <item>
+ The related packages must use the provided program
+ to make any desired modifications to the
+ configuration file. They should either depend on
+ the core package to guarantee that the configuration
+ modifier program is available or accept gracefully
+ that they cannot modify the configuration file if it
+ is not. (This is in addition to the fact that the
+ configuration file may not even be present in the
+ latter scenario.)
+ </item>
+ </enumlist>
+ </p>
- <p>
- The unification of Debian documentation is being carried out
- via HTML.</p>
+ <p>
+ Sometimes it's appropriate to create a new package which
+ provides the basic infrastructure for the other packages
+ and which manages the shared configuration files. (The
+ <tt>sgml-base</tt> package is a good example.)
+ </p>
+ </sect1>
- <p>
- If your package comes with extensive documentation in a
- markup format that can be converted to various other formats
- you should if possible ship HTML versions in a binary
- package, in the directory
- <file>/usr/share/doc/<var>appropriate-package</var></file> or
- its subdirectories.<footnote>
- 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.
- </footnote>
- </p>
+ <sect1>
+ <heading>User configuration files ("dotfiles")</heading>
- <p>
- Other formats such as PostScript may be provided at the
- package maintainer's discretion.
- </p>
- </sect>
+ <p>
+ The files in <file>/etc/skel</file> will automatically be
+ copied into new user accounts by <prgn>adduser</prgn>.
+ No other program should reference the files in
+ <file>/etc/skel</file>.
+ </p>
- <sect id="copyrightfile">
- <heading>Copyright information</heading>
+ <p>
+ Therefore, if a program needs a dotfile to exist in
+ advance in <file>$HOME</file> to work sensibly, that dotfile
+ should be installed in <file>/etc/skel</file> and treated as a
+ configuration file.
+ </p>
- <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>. This
- file must neither be compressed nor be a symbolic link.
- </p>
+ <p>
+ However, programs that require dotfiles in order to
+ operate sensibly are a bad thing, unless they do create
+ the dotfiles themselves automatically.
+ </p>
- <p>
- In addition, the copyright file must say where the upstream
- sources (if any) were obtained. It should name the original
- authors of the package and the Debian maintainer(s) who were
- involved with its creation.</p>
+ Furthermore, programs should be configured by the Debian
+ default installation to behave as closely to the upstream
+ default behaviour as possible.
+ </p>
- <p>
- A copy of the file which will be installed in
- <file>/usr/share/doc/<var>package</var>/copyright</file> should
- be in <file>debian/copyright</file> in the source package.
- </p>
+ <p>
+ Therefore, if a program in a Debian package needs to be
+ configured in some way in order to operate sensibly, that
+ should be done using a site-wide configuration file placed
+ in <file>/etc</file>. Only if the program doesn't support a
+ site-wide default configuration and the package maintainer
+ doesn't have time to add it may a default per-user file be
+ placed in <file>/etc/skel</file>.
+ </p>
- <p>
- <file>/usr/share/doc/<var>package</var></file> may be a symbolic
- link to another directory in <file>/usr/share/doc</file> only if
- the two packages both come from the same source and the
- first package Depends on the second. These rules are
- important because copyrights must be extractable by
- mechanical means.
- </p>
+ <p>
+ <file>/etc/skel</file> should be as empty as we can make it.
+ This is particularly true because there is no easy (or
+ necessarily desirable) mechanism for ensuring that the
+ appropriate dotfiles are copied into the accounts of
+ existing users when a package is installed.
+ </p>
+ </sect1>
+ </sect>
+ <sect>
+ <heading>Log files</heading>
<p>
- Packages distributed under the UCB BSD license, the Artistic
- license, the GNU GPL, and the GNU LGPL should refer to the
- files <file>/usr/share/common-licenses/BSD</file>,
- <file>/usr/share/common-licenses/Artistic</file>,
- <file>/usr/share/common-licenses/GPL</file>, and
- <file>/usr/share/common-licenses/LGPL</file> respectively,
- rather than quoting them in the copyright file.
+ Log files should usually be named
+ <file>/var/log/<var>package</var>.log</file>. If you have many
+ log files, or need a separate directory for permission
+ reasons (<file>/var/log</file> is writable only by
+ <file>root</file>), you should usually create a directory named
+ <file>/var/log/<var>package</var></file> and place your log
+ files there.
</p>
<p>
- You should not use the copyright file as a general <file>README</file>
- file. If your package has such a file it should be
- installed in <file>/usr/share/doc/<var>package</var>/README</file> or
- <file>README.Debian</file> or some other appropriate place.</p>
- </sect>
-
- <sect>
- <heading>Examples</heading>
+ Log files must be rotated occasionally so that they don't
+ grow indefinitely; the best way to do this is to drop a log
+ rotation configuration file into the directory
+ <file>/etc/logrotate.d</file> and use the facilities provided by
+ logrotate.<footnote>
+ <p>
+ The traditional approach to log files has been to set up
+ <em>ad hoc</em> log rotation schemes using simple shell
+ scripts and cron. While this approach is highly
+ customizable, it requires quite a lot of sysadmin work.
+ Even though the original Debian system helped a little
+ by automatically installing a system which can be used
+ as a template, this was deemed not enough.
+ </p>
- <p>
- Any examples (configurations, source files, whatever),
- should be installed in a directory
- <file>/usr/share/doc/<var>package</var>/examples</file>. These
- files should not be referenced by any program: they're there
- for the benefit of the system administrator and users as
- documentation only. Architecture-specific example files
- should be installed in a directory
- <file>/usr/lib/<var>package</var>/examples</file> with symbolic
- links to them from
- <file>/usr/share/doc/<var>package</var>/examples</file>, or the
- latter directory itself may be a symbolic link to the
- former.
+ <p>
+ The use of <prgn>logrotate</prgn>, a program developed
+ by Red Hat, is better, as it centralizes log management.
+ It has both a configuration file
+ (<file>/etc/logrotate.conf</file>) and a directory where
+ packages can drop their individual log rotation
+ configurations (<file>/etc/logrotate.d</file>).
+ </p>
+ </footnote>
+ Here is a good example for a logrotate config
+ file (for more information see <manref name="logrotate"
+ section="8">):
+ <example compact="compact">
+/var/log/foo/*.log {
+rotate 12
+weekly
+compress
+postrotate
+/etc/init.d/foo force-reload
+endscript
+}
+ </example>
+ This rotates all files under <file>/var/log/foo</file>, saves 12
+ compressed generations, and forces the daemon to reload its
+ configuration information after the log rotation.
</p>
<p>
- 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>.
+ Log files should be removed when the package is
+ purged (but not when it is only removed). This should be
+ done by the <prgn>postrm</prgn> script when it is called
+ with the argument <tt>purge</tt> (see <ref
+ id="removedetails">).
</p>
</sect>
- <sect 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>
- 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.)
- </footnote>
- </p>
+ <sect>
+ <heading>Permissions and owners</heading>
<p>
- Packages that are not Debian-native must contain a
- compressed copy of the <file>debian/changelog</file> file from
- the Debian source tree in
- <file>/usr/share/doc/<var>package</var></file> with the name
- <file>changelog.Debian.gz</file>.
- </p>
-
- <p>
- If an upstream changelog is available, it should be accessible as
- <file>/usr/share/doc/<var>package</var>/changelog.gz</file> in
- plain text. If the upstream changelog is distributed in
- HTML, it should be made available in that form as
- <file>/usr/share/doc/<var>package</var>/changelog.html.gz</file>
- and a plain text <file>changelog.gz</file> should be generated
- from it using, for example, <tt>lynx -dump -nolist</tt>. If
- the upstream changelog files do not already conform to this
- naming convention, then this may be achieved either by
- renaming the files, or by adding a symbolic link, at the
- maintainer's discretion.<footnote>
- 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.
- </footnote>
+ The rules in this section are guidelines for general use.
+ If necessary you may deviate from the details below.
+ However, if you do so you must make sure that what is done
+ is secure and you should try to be as consistent as possible
+ with the rest of the system. You should probably also
+ discuss it on <prgn>debian-devel</prgn> first.
</p>
<p>
- All of these files should be installed compressed using
- <tt>gzip -9</tt>, as they will become large with time even
- if they start out small.
+ Files should be owned by <tt>root.root</tt>, and made
+ writable only by the owner and universally readable (and
+ executable, if appropriate), that is mode 644 or 755.
</p>
<p>
- If the package has only one changelog which is used both as
- the Debian changelog and the upstream one because there is
- no separate upstream maintainer then that changelog should
- usually be installed as
- <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>
-
- </sect>
- </chapt>
-
- <appendix id="pkg-scope">
- <heading>Introduction and scope of these appendices</heading>
+ Directories should be mode 755 or (for group-writability)
+ mode 2775. The ownership of the directory should be
+ consistent with its mode: if a directory is mode 2775, it
+ should be owned by the group that needs write access to
+ it.
+ </p>
- <p>
- These appendices are taken essentially verbatim from the
- now-deprecated Packaging Manual, version 3.2.1.0. They are
- the chapters which are likely to be of use to package
- maintainers and which have not already been included in the
- policy document itself. Most of these sections are very likely
- not relevant to policy; they should be treated as
- documentation for the packaging system. Please note that these
- appendices are included for convenience, and for historical
- reasons: they used to be part of policy package, and they have
- not yet been incorporated into dpkg documentation. However,
- they still have value, and hence they are presented here.
- </p>
- <p>
- They have not yet been checked to ensure that they are
- compatible with the contents of policy, and if there are any
- contradictions, the version in the main policy document takes
- precedence. The remaining chapters of the old Packaging
- Manual have also not been read in detail to ensure that there
- are not parts which have been left out. Both of these will be
- done in due course.
- </p>
+ <p>
+ Setuid and setgid executables should be mode 4755 or 2755
+ respectively, and owned by the appropriate user or group.
+ They should not be made unreadable (modes like 4711 or
+ 2711 or even 4111); doing so achieves no extra security,
+ because anyone can find the binary in the freely available
+ Debian package; it is merely inconvenient. For the same
+ reason you should not restrict read or execute permissions
+ on non-set-id executables.
+ </p>
- <p>
- <prgn>dpkg</prgn> is a suite of programs for creating binary
- package files and installing and removing them on Unix
- systems.<footnote>
- <prgn>dpkg</prgn> is targetted primarily at Debian
- GNU/Linux, but may work on or be ported to other
- systems.
- </footnote>
- </p>
+ Some setuid programs need to be restricted to particular
+ sets of users, using file permissions. In this case they
+ should be owned by the uid to which they are set-id, and by
+ the group which should be allowed to execute them. They
+ should have mode 4754; again there is no point in making
+ them unreadable to those users who must not be allowed to
+ execute them.
+ </p>
- <p>
- The binary packages are designed for the management of
- installed executable programs (usually compiled binaries) and
- their associated data, though source code examples and
- documentation are provided as part of some packages.</p>
+ <p>
+ It is possible to arrange that the system administrator can
+ reconfigure the package to correspond to their local
+ security policy by changing the permissions on a binary:
+ they can do this by using <prgn>dpkg-statoverride</prgn>, as
+ described below.<footnote>
+ Ordinary files installed by <prgn>dpkg</prgn> (as
+ opposed to <tt>conffile</tt>s and other similar objects)
+ normally have their permissions reset to the distributed
+ permissions when the package is reinstalled. However,
+ the use of <prgn>dpkg-statoverride</prgn> overrides this
+ default behaviour. If you use this method, you should
+ remember to describe <prgn>dpkg-statoverride</prgn> in
+ the package documentation; being a relatively new
+ addition to Debian, it is probably not yet well-known.
+ </footnote>
+ Another method you should consider is to create a group for
+ people allowed to use the program(s) and make any setuid
+ executables executable only by that group.
+ </p>
- <p>
- This manual describes the technical aspects of creating Debian
- binary packages (<file>.deb</file> files). It documents the
- behaviour of the package management programs
- <prgn>dpkg</prgn>, <prgn>dselect</prgn> et al. and the way
- they interact with packages.</p>
+ <p>
+ If you need to create a new user or group for your package
+ there are two possibilities. Firstly, you may need to
+ make some files in the binary package be owned by this
+ user or group, or you may need to compile the user or
+ group id (rather than just the name) into the binary
+ (though this latter should be avoided if possible, as in
+ this case you need a statically allocated id).</p>
- <p>
- It also documents the interaction between
- <prgn>dselect</prgn>'s core and the access method scripts it
- uses to actually install the selected packages, and describes
- how to create a new access method.</p>
+ <p>
+ If you need a statically allocated id, you must ask for a
+ user or group id from the <tt>base-passwd</tt> maintainer,
+ and must not release the package until you have been
+ allocated one. Once you have been allocated one you must
+ either make the package depend on a version of the
+ <tt>base-passwd</tt> package with the id present in
+ <file>/etc/passwd</file> or <file>/etc/group</file>, or arrange for
+ your package to create the user or group itself with the
+ correct id (using <tt>adduser</tt>) in its
+ <prgn>preinst</prgn> or <prgn>postinst</prgn>. (Doing it in
+ the <prgn>postinst</prgn> is to be preferred if it is
+ possible, otherwise a pre-dependency will be needed on the
+ <tt>adduser</tt> package.)
+ </p>
- <p>
- This manual does not go into detail about the options and
- usage of the package building and installation tools. It
- should therefore be read in conjuction with those programs'
- manpages.
- </p>
+ <p>
+ On the other hand, the program might be able to determine
+ the uid or gid from the user or group name at runtime, so
+ that a dynamically allocated id can be used. In this case
+ you should choose an appropriate user or group name,
+ discussing this on <prgn>debian-devel</prgn> and checking
+ with the <package/base-passwd/ maintainer that it is unique and that
+ they do not wish you to use a statically allocated id
+ instead. When this has been checked you must arrange for
+ your package to create the user or group if necessary using
+ <prgn>adduser</prgn> in the <prgn>preinst</prgn> or
+ <prgn>postinst</prgn> script (again, the latter is to be
+ preferred if it is possible).
+ </p>
- <p>
- The utility programs which are provided with <prgn>dpkg</prgn>
- for managing various system configuration and similar issues,
- such as <prgn>update-rc.d</prgn> and
- <prgn>install-info</prgn>, are not described in detail here -
- please see their manpages.
- </p>
+ Note that changing the numeric value of an id associated
+ with a name is very difficult, and involves searching the
+ file system for all appropriate files. You need to think
+ carefully whether a static or dynamic id is required, since
+ changing your mind later will cause problems.
+ </p>
- <p>
- It is assumed that the reader is reasonably familiar with the
- <prgn>dpkg</prgn> System Administrators' manual.
- Unfortunately this manual does not yet exist.
- </p>
+ <sect1><heading>The use of <prgn>dpkg-statoverride</prgn></heading>
+ <p>
+ This section is not intended as policy, but as a
+ description of the use of <prgn>dpkg-statoverride</prgn>.
+ </p>
- <p>
- The Debian version of the FSF's GNU hello program is provided
- as an example for people wishing to create Debian
- packages. The Debian <prgn>debmake</prgn> package is
- recommended as a very helpful tool in creating and maintaining
- Debian packages. However, while the tools and examples are
- helpful, they do not replace the need to read and follow the
- Policy and Programmer's Manual.</p>
- </appendix>
+ <prgn>dpkg-statoverride</prgn> is a replacement for the
+ deprecated <tt>suidmanager</tt> package. Packages which
+ previously used <tt>suidmanager</tt> should have a
+ <tt>Conflicts: suidmanager (<< 0.50)</tt> entry (or even
+ <tt>(<< 0.52)</tt>), and calls to <tt>suidregister</tt>
+ and <tt>suidunregister</tt> should now be simply removed
+ from the maintainer scripts.
+ </p>
- <appendix id="pkg-binarypkg"><heading>Binary packages (from old
- Packaging Manual)
- </heading>
+ <p>
+ If a system administrator wishes to have a file (or
+ directory or other such thing) installed with owner and
+ permissions different from those in the distributed Debian
+ package, he can use the <prgn>dpkg-statoverride</prgn>
+ program to instruct <prgn>dpkg</prgn> to use the different
+ settings every time the file is installed. Thus the
+ package maintainer should distribute the files with their
+ normal permissions, and leave it for the system
+ administrator to make any desired changes. For example, a
+ daemon which is normally required to be setuid root, but
+ in certain situations could be used without being setuid,
+ should be installed setuid in the <tt>.deb</tt>. Then the
+ local system administrator can change this if they wish.
+ If there are two standard ways of doing it, the package
+ maintainer can use <tt>debconf</tt> to find out the
+ preference, and call <prgn>dpkg-statoverride</prgn> in the
+ maintainer script if necessary to accommodate the system
+ administrator's choice.
+ </p>
- <p>
- The binary package has two main sections. The first part
- consists of various control information files and scripts used
- by <prgn>dpkg</prgn> when installing and removing. See <ref
- id="pkg-controlarea">.
- </p>
+ <p>
+ Given the above, <prgn>dpkg-statoverride</prgn> is
+ essentially a tool for system administrators and would not
+ normally be needed in the maintainer scripts. There is
+ one type of situation, though, where calls to
+ <prgn>dpkg-statoverride</prgn> would be needed in the
+ maintainer scripts, and that involves packages which use
+ dynamically allocated user or group ids. In such a
+ situation, something like the following idiom can be very
+ helpful in the package's <prgn>postinst</prgn>, where
+ <tt>sysuser</tt> is a dynamically allocated id:
+ <example>
+for i in /usr/bin/foo /usr/sbin/bar
+do
+ if ! dpkg-statoverride --list $i >/dev/null
+ then
+ dpkg-statoverride --update --add sysuser root 4755 $i
+ fi
+done
+ </example>
+ The corresponding <tt>dpkg-statoverride --remove</tt>
+ calls can then be made unconditionally when the package is
+ purged.
+ </p>
+ </sect1>
+ </sect>
+ </chapt>
- <p>
- The second part is an archive containing the files and
- directories to be installed.
- </p>
- <p>
- In the future binary packages may also contain other
- components, such as checksums and digital signatures. The
- format for the archive is described in full in the
- <file>deb(5)</file> manpage.
- </p>
+ <chapt id="customized-programs">
+ <heading>Customized programs</heading>
+ <sect id="arch-spec">
+ <heading>Architecture specification strings</heading>
- <sect id="pkg-bincreating"><heading>Creating package files -
- <prgn>dpkg-deb</prgn>
- </heading>
+ <p>
+ 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>
+ The following architectures and operating systems are
+ currently recognised by <prgn>dpkg-archictecture</prgn>.
+ The architecture, <tt><var>arch</var></tt>, is one of
+ the following: <tt>alpha</tt>, <tt>arm</tt>,
+ <tt>hppa</tt>, <tt>i386</tt>, <tt>ia64</tt>,
+ <tt>m68k</tt>, <tt>mips</tt>, <tt>mipsel</tt>,
+ <tt>powerpc</tt>, <tt>s390</tt>, <tt>sh</tt>,
+ <tt>sheb</tt>, <tt>sparc</tt> and <tt>sparc64</tt>. The
+ operating system, <tt><var>os</var></tt>, is one of:
+ <tt>linux</tt>, <tt>gnu</tt>, <tt>freebsd</tt> and
+ <tt>openbsd</tt>. Use of <tt>gnu</tt> in this string is
+ reserved for the GNU/Hurd operating system.
+ </footnote>.
+ </p>
<p>
- All manipulation of binary package files is done by
- <prgn>dpkg-deb</prgn>; it's the only program that has
- knowledge of the format. (<prgn>dpkg-deb</prgn> may be
- invoked by calling <prgn>dpkg</prgn>, as <prgn>dpkg</prgn>
- will spot that the options requested are appropriate to
- <prgn>dpkg-deb</prgn> and invoke that instead with the same
- arguments.)
+ Note that we don't want to use
+ <tt><var>arch</var>-debian-linux</tt> to apply to the rule
+ <tt><var>architecture</var>-<var>vendor</var>-<var>os</var></tt>
+ since this would make our programs incompatible with other
+ Linux distributions. We also don't use something like
+ <tt><var>arch</var>-unknown-linux</tt>, since the
+ <tt>unknown</tt> does not look very good.
</p>
+ </sect>
+
+ <sect>
+ <heading>Daemons</heading>
<p>
- In order to create a binary package you must make a
- directory tree which contains all the files and directories
- you want to have in the filesystem data part of the package.
- In Debian-format source packages this directory is usually
- <file>debian/tmp</file>, relative to the top of the package's
- source tree.
+ The configuration files <file>/etc/services</file>,
+ <file>/etc/protocols</file>, and <file>/etc/rpc</file> are managed
+ by the <prgn>netbase</prgn> package and must not be modified
+ by other packages.
</p>
<p>
- They should have the locations (relative to the root of the
- directory tree you're constructing) ownerships and
- permissions which you want them to have on the system when
- they are installed.
+ If a package requires a new entry in one of these files, the
+ maintainer should get in contact with the
+ <prgn>netbase</prgn> maintainer, who will add the entries
+ and release a new version of the <prgn>netbase</prgn>
+ package.
</p>
<p>
- With current versions of <prgn>dpkg</prgn> the uid/username
- and gid/groupname mappings for the users and groups being
- used should be the same on the system where the package is
- built and the one where it is installed.
+ The configuration file <file>/etc/inetd.conf</file> must not be
+ modified by the package's scripts except via the
+ <prgn>update-inetd</prgn> script or the
+ <file>DebianNet.pm</file> Perl module. See their documentation
+ for details on how to add entries.
</p>
<p>
- You need to add one special directory to the root of the
- miniature filesystem tree you're creating:
- <prgn>DEBIAN</prgn>. It should contain the control
- information files, notably the binary package control file
- (see <ref id="pkg-controlfile">).
+ If a package wants to install an example entry into
+ <file>/etc/inetd.conf</file>, the entry must be preceded with
+ exactly one hash character (<tt>#</tt>). Such lines are
+ treated as "commented out by user" by the
+ <prgn>update-inetd</prgn> script and are not changed or
+ activated during package updates.
</p>
+ </sect>
+
+ <sect>
+ <heading>Using pseudo-ttys and modifying wtmp, utmp and
+ lastlog</heading>
<p>
- The <prgn>DEBIAN</prgn> directory will not appear in the
- filesystem archive of the package, and so won't be installed
- by <prgn>dpkg</prgn> when the package is installed.
+ Some programs need to create pseudo-ttys. This should be done
+ using Unix98 ptys if the C library supports it. The resulting
+ program must not be installed setuid root, unless that
+ is required for other functionality.
</p>
<p>
- When you've prepared the package, you should invoke:
- <example>
- dpkg --build <var>directory</var>
- </example>
+ The files <file>/var/run/utmp</file>, <file>/var/log/wtmp</file> and
+ <file>/var/log/lastlog</file> must be installed writeable by
+ group <tt>utmp</tt>. Programs which need to modify those
+ files must be installed setgid <tt>utmp</tt>.
</p>
+ </sect>
+
+ <sect>
+ <heading>Editors and pagers</heading>
<p>
- This will build the package in
- <file><var>directory</var>.deb</file>. (<prgn>dpkg</prgn> knows
- that <tt>--build</tt> is a <prgn>dpkg-deb</prgn> option, so
- it invokes <prgn>dpkg-deb</prgn> with the same arguments to
- build the package.)
+ Some programs have the ability to launch an editor or pager
+ program to edit or display a text document. Since there are
+ lots of different editors and pagers available in the Debian
+ distribution, the system administrator and each user should
+ have the possibility to choose his/her preferred editor and
+ pager.
</p>
<p>
- See the manpage <manref name="dpkg-deb" section="8"> for details of how
- to examine the contents of this newly-created file. You may find the
- output of following commands enlightening:
- <example>
- dpkg-deb --info <var>filename</var>.deb
- dpkg-deb --contents <var>filename</var>.deb
- dpkg --contents <var>filename</var>.deb
- </example>
- To view the copyright file for a package you could use this command:
- <example>
- dpkg --fsys-tarfile <var>filename</var>.deb | tar xof usr/share/doc/<var>\*</var>copyright | less
- </example>
+ In addition, every program should choose a good default
+ editor/pager if none is selected by the user or system
+ administrator.
</p>
- </sect>
- <sect id="pkg-controlarea">
- <heading>
- Package control information files
- </heading>
+ <p>
+ Thus, every program that launches an editor or pager must
+ use the EDITOR or PAGER environment variable to determine
+ the editor or pager the user wishes to use. If these
+ variables are not set, the programs <file>/usr/bin/editor</file>
+ and <file>/usr/bin/pager</file> should be used, respectively.
+ </p>
<p>
- The control information portion of a binary package is a
- collection of files with names known to <prgn>dpkg</prgn>.
- It will treat the contents of these files specially - some
- of them contain information used by <prgn>dpkg</prgn> when
- installing or removing the package; others are scripts which
- the package maintainer wants <prgn>dpkg</prgn> to run.
+ These two files are managed through the <prgn>dpkg</prgn>
+ "alternatives" mechanism. Thus every package providing an
+ editor or pager must call the
+ <prgn>update-alternatives</prgn> script to register these
+ programs.
</p>
<p>
- It is possible to put other files in the package control
- area, but this is not generally a good idea (though they
- will largely be ignored).
+ If it is very hard to adapt a program to make use of the
+ EDITOR or PAGER variables, that program may be configured to
+ use <file>/usr/bin/sensible-editor</file> and
+ <file>/usr/bin/sensible-pager</file> as the editor or pager
+ program respectively. These are two scripts provided in the
+ Debian base system that check the EDITOR and PAGER variables
+ and launch the appropriate program, and fall back to
+ <file>/usr/bin/editor</file> and <file>/usr/bin/pager</file> if the
+ variable is not set.
</p>
<p>
- Here is a brief list of the control info files supported by
- <prgn>dpkg</prgn> and a summary of what they're used for.
+ A program may also use the VISUAL environment variable to
+ determine the user's choice of editor. If it exists, it
+ should take precedence over EDITOR. This is in fact what
+ <file>/usr/bin/sensible-editor</file> does.
</p>
<p>
- <taglist>
- <tag><tt>control</tt>
- <item>
+ 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>
+ The Debian base system already provides an editor and a
+ pager program.
+ </footnote>
+ </p>
+ </sect>
- <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>
+ <sect id="web-appl">
+ <heading>Web servers and applications</heading>
- <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>
+ <p>
+ This section describes the locations and URLs that should
+ be used by all web servers and web applications in the
+ Debian system.
+ </p>
- <tag><tt>postinst</tt>, <tt>preinst</tt>, <tt>postrm</tt>,
- <tt>prerm</tt>
- </tag>
+ <p>
+ <enumlist>
<item>
+ Cgi-bin executable files are installed in the
+ directory
+ <example compact="compact">
+/usr/lib/cgi-bin/<var>cgi-bin-name</var>
+ </example>
+ and should be referred to as
+ <example compact="compact">
+http://localhost/cgi-bin/<var>cgi-bin-name</var>
+ </example>
+ </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>
- 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.
- </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>
+ <item>
+ <p>Access to HTML documents</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.
+ HTML documents for a package are stored in
+ <file>/usr/share/doc/<var>package</var></file>
+ and can be referred to as
+ <example compact="compact">
+http://localhost/doc/<var>package</var>/<var>filename</var>
+ </example>
</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>
+ The web server should restrict access to the document
+ tree so that only clients on the same host can read
+ the documents. If the web server does not support such
+ access controls, then it should not provide access at
+ all, or ask about providing access during installation.
+ </p>
</item>
- <tag><tt>shlibs</tt>
- </tag>
<item>
+ <p>Web Document Root</p>
<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">.
+ Web Applications should try to avoid storing files in
+ the Web Document Root. Instead they should use the
+ /usr/share/doc/<var>package</var> directory for
+ documents and register the Web Application via the
+ menu package. If access to the web document root is
+ unavoidable then use
+ <example compact="compact">
+/var/www
+ </example>
+ as the Document Root. This might be just a symbolic
+ link to the location where the system administrator
+ has put the real document root.
</p>
</item>
- </taglist>
+
+ </enumlist>
</p>
+ </sect>
+
+ <sect id="mail-transport-agents">
+ <heading>Mail transport, delivery and user agents</heading>
- <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".
+ Debian packages which process electronic mail, whether mail
+ user agents (MUAs) or mail transport agents (MTAs), must
+ ensure that they are compatible with the configuration
+ decisions below. Failure to do this may result in lost
+ mail, broken <tt>From:</tt> lines, and other serious brain
+ damage!
</p>
<p>
- The 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.
+ The mail spool is <file>/var/mail</file> and the interface to
+ send a mail message is <file>/usr/sbin/sendmail</file> (as per
+ the FHS). On older systems, the mail spool may be
+ physically located in <file>/var/spool/mail</file>, but all
+ access to the mail spool should be via the
+ <file>/var/mail</file> symlink. The mail spool is part of the
+ base system and not part of the MTA package.
</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>
- This field should appear in all packages, though
- <prgn>dpkg</prgn> doesn't require it yet so that
- old packages can still be installed.
- </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>
+ All Debian MUAs, MTAs, MDAs and other mailbox accessing
+ programs (such as IMAP daemons) must lock the mailbox in an
+ NFS-safe way. This means that <tt>fcntl()</tt> locking must
+ be combined with dot locking. To avoid deadlocks, a program
+ should use <tt>fcntl()</tt> first and dot locking after
+ this, or alternatively implement the two locking methods in
+ a non blocking way<footnote>
+ 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.
+ </footnote>. Using the functions <tt>maillock</tt> and
+ <tt>mailunlock</tt> provided by the
+ <tt>liblockfile*</tt><footnote>
+ 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>
<p>
- A description of the syntax of control files and the purpose
- of these fields is available in <ref id="pkg-controlfields">.
+ Mailboxes are generally mode 660
+ <tt><var>user</var>.mail</tt> unless the system
+ administrator has chosen otherwise. A MUA may remove a
+ mailbox (unless it has nonstandard permissions) in which
+ case the MTA or another MUA must recreate it if needed.
+ Mailboxes must be writable by group mail.
</p>
- </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>
- 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>
- </appendix>
+ The mail spool is 2775 <tt>root.mail</tt>, and MUAs should
+ be setgid mail to do the locking mentioned above (and
+ must obviously avoid accessing other users' mailboxes
+ using this privilege).</p>
- <appendix id="pkg-sourcepkg">
- <heading>Source packages (from old Packaging Manual) </heading>
+ <p>
+ <file>/etc/aliases</file> is the source file for the system mail
+ aliases (e.g., postmaster, usenet, etc.), it is the one
+ which the sysadmin and <prgn>postinst</prgn> scripts may
+ edit. After <file>/etc/aliases</file> is edited the program or
+ human editing it must call <prgn>newaliases</prgn>. All MTA
+ packages must come with a <prgn>newaliases</prgn> program,
+ even if it does nothing, but older MTA packages did not do
+ this so programs should not fail if <prgn>newaliases</prgn>
+ cannot be found. Note that because of this, all MTA
+ packages must have <tt>Provides</tt>, <tt>Conflicts</tt> and
+ <tt>Replaces: mail-transport-agent</tt> control file
+ fields.
+ </p>
- <p>
- The 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>
+ The convention of writing <tt>forward to
+ <var>address</var></tt> in the mailbox itself is not
+ supported. Use a <tt>.forward</tt> file instead.</p>
- <sect id="pkg-sourcetools">
- <heading>Tools for processing source packages</heading>
+ <p>
+ The <prgn>rmail</prgn> program used by UUCP
+ for incoming mail should be <file>/usr/sbin/rmail</file>.
+ Likewise, <prgn>rsmtp</prgn>, for receiving
+ batch-SMTP-over-UUCP, should be <file>/usr/sbin/rsmtp</file> if it
+ is supported.</p>
<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.
+ If your package needs to know what hostname to use on (for
+ example) outgoing news and mail messages which are generated
+ locally, you should use the file <file>/etc/mailname</file>. It
+ will contain the portion after the username and <tt>@</tt>
+ (at) sign for email addresses of users on the machine
+ (followed by a newline).
</p>
<p>
- They are introduced and typical uses described here; see
- <manref name="dpkg-source" section="1"> for full
- documentation about their arguments and operation.
+ Such package should check for the existence of this file
+ when it is being configured. If it exists, it should be
+ used without comment, although an MTA's configuration script
+ may wish to prompt the user even if it finds that this file
+ exists. If the file does not exist, the package should
+ prompt the user for the value (preferably using
+ <prgn>debconf</prgn>) and store it in <file>/etc/mailname</file>
+ as well as using it in the package's configuration. The
+ prompt should make it clear that the name will not just be
+ used by that package. For example, in this situation the
+ <tt>inn</tt> package could say something like:
+ <example compact="compact">
+Please enter the "mail name" of your system. This is the
+hostname portion of the address to be shown on outgoing
+news and mail messages. The default is
+<var>syshostname</var>, your system's host name. Mail
+name ["<var>syshostname</var>"]:
+ </example>
+ where <var>syshostname</var> is the output of <tt>hostname
+ --fqdn</tt>.
</p>
+ </sect>
+
+ <sect>
+ <heading>News system configuration</heading>
<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.
+ All the configuration files related to the NNTP (news)
+ servers and clients should be located under
+ <file>/etc/news</file>.</p>
+
+ <p>
+ There are some configuration issues that apply to a number
+ of news clients and server packages on the machine. These
+ are:
+
+ <taglist>
+ <tag><file>/etc/news/organization</file></tag>
+ <item>
+ A string which should appear as the
+ organization header for all messages posted
+ by NNTP clients on the machine
+ </item>
+
+ <tag><file>/etc/news/server</file></tag>
+ <item>
+ Contains the FQDN of the upstream NNTP
+ server, or localhost if the local machine is
+ an NNTP server.
+ </item>
+ </taglist>
+
+ Other global files may be added as required for cross-package news
+ configuration.
</p>
+ </sect>
+
+
+ <sect>
+ <heading>Programs for the X Window System</heading>
+
+ <sect1>
+ <heading>Providing X support and package priorities</heading>
+
+ <p>
+ Programs that can be configured with support for the X
+ Window System must be configured to do so and must declare
+ any package dependencies necessary to satisfy their
+ runtime requirements when using the X Window System. If
+ such a package is of higher priority than the X packages
+ on which it depends, it is required that either the
+ X-specific components be split into a separate package, or
+ that an alternative version of the package, which includes
+ X support, be provided, or that the package's priority be
+ lowered.
+ </p>
+ </sect1>
+
+ <sect1>
+ <heading>Packages providing an X server</heading>
+
+ <p>
+ Packages that provide an X server that, directly or
+ indirectly, communicates with real input and display
+ hardware should declare in their control data that they
+ provide the virtual package <tt>xserver</tt>.<footnote>
+ This implements current practice, and provides an
+ actual policy for usage of the <tt>xserver</tt>
+ virtual package which appears in the virtual packages
+ list. In a nutshell, X servers that interface
+ directly with the display and input hardware or via
+ another subsystem (e.g., GGI) should provide
+ <tt>xserver</tt>. Things like <tt>Xvfb</tt>,
+ <tt>Xnest</tt>, and <tt>Xprt</tt> should not.
+ </footnote>
+ </p>
+ </sect1>
<sect1>
- <heading>
- <prgn>dpkg-source</prgn> - packs and unpacks Debian source
- packages
- </heading>
+ <heading>Packages providing a terminal emulator</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>.
+ Packages that provide a terminal emulator for the X Window
+ System which meet the criteria listed below should declare
+ in their control data that they provide the virtual
+ package <tt>x-terminal-emulator</tt>. They should also
+ register themselves as an alternative for
+ <file>/usr/bin/x-terminal-emulator</file>, with a priority of
+ 20.
</p>
<p>
- To unpack a package it is typically invoked with
- <example>
- dpkg-source -x <var>.../path/to/filename</var>.dsc
- </example>
- </p>
+ To be an <tt>x-terminal-emulator</tt>, a program must:
+ <list compact="compact">
+ <item>
+ Be able to emulate a DEC VT100 terminal, or a
+ compatible terminal.
+ </item>
- <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>
+ <item>
+ Support the command-line option <tt>-e
+ <var>command</var></tt>, which creates a new
+ terminal window<footnote>
+ "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).
+ </footnote>
+ 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>
- <p>
- To create a packed source archive it is typically invoked:
- <example>
- dpkg-source -b <var>package</var>-<var>version</var>
- </example>
+ <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>.
+ </item>
+ </list>
</p>
+ </sect1>
- <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>
+ <sect1>
+ <heading>Packages providing a window manager</heading>
<p>
- See also <ref id="pkg-sourcearchives">.</p>
- </sect1>
+ Packages that provide a window manager should declare in
+ their control data that they provide the virtual package
+ <tt>x-window-manager</tt>. They should also register
+ themselves as an alternative for
+ <file>/usr/bin/x-window-manager</file>, with a priority
+ calculated as follows:
+ <list compact="compact">
+ <item>
+ Start with a priority of 20.
+ </item>
+
+ <item>
+ If the window manager supports the Debian menu
+ system, add 20 points if this support is available
+ in the package's default configuration (i.e., no
+ configuration files belonging to the system or user
+ have to be edited to activate the feature); if
+ configuration files must be modified, add only 10
+ points.
+ </p>
+ </item>
+
+ <item>
+ 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 40 points.
+ </item>
+ <item>
+ If the window manager permits the X session to be
+ restarted using a <em>different</em> window manager
+ (without killing the X server) in its default
+ configuration, add 10 points; otherwise add none.
+ </item>
+ </list>
+ </p>
+ </sect1>
<sect1>
- <heading>
- <prgn>dpkg-buildpackage</prgn> - overall package-building
- control script
- </heading>
+ <heading>Packages providing fonts</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>
+ Packages that provide fonts for the X Window
+ System<footnote>
+ For the purposes of Debian Policy, a "font for the X
+ Window System" is one which is accessed via X protocol
+ requests. Fonts for the Linux console, for PostScript
+ renderers, or any other purpose, do not fit this
+ definition. Any tool which makes such fonts available
+ to the X Window System, however, must abide by this
+ font policy.
+ </footnote>
+ must do a number of things to ensure that they are both
+ available without modification of the X or font server
+ configuration, and that they do not corrupt files used by
+ other font packages to register information about
+ themselves.
+ <enumlist>
+ <item>
+ Fonts of any type supported by the X Window System
+ must be in a separate binary package from any
+ executables, libraries, or documentation (except
+ that specific to the fonts shipped, such as their
+ license information). If one or more of the fonts
+ so packaged are necessary for proper operation of
+ the package with which they are associated the font
+ package may be Recommended; if the fonts merely
+ provide an enhancement, a Suggests relationship may
+ be used. Packages must not Depend on font
+ packages.<footnote>
+ 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.
+ </footnote>
+ </item>
+
+ <item>
+ 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>
+ 100 dpi fonts must be placed in
+ <file>/usr/X11R6/lib/X11/fonts/100dpi/</file>.
+ </item>
+
+ <item>
+ 75 dpi fonts must be placed in
+ <file>/usr/X11R6/lib/X11/fonts/75dpi/</file>.
+ </item>
+
+ <item>
+ Character-cell fonts, cursor fonts, and other
+ low-resolution fonts must be placed in
+ <file>/usr/X11R6/lib/X11/fonts/misc/</file>.
+ </item>
+ </list>
+ </item>
+
+ <item>
+ Speedo fonts must be placed in
+ <file>/usr/X11R6/lib/X11/fonts/Speedo/</file>.
+ </item>
+
+ <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.
+ </item>
+
+ <item>
+ 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.)
+ </item>
+
+ <item>
+ 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.
+ </item>
+
+ <item>
+ Font packages should not contain both 75dpi and
+ 100dpi versions of a font. If both are available,
+ they should be provided in separate binary packages
+ with <tt>-75dpi</tt> or <tt>-100dpi</tt> appended to
+ the names of the packages containing the
+ corresponding fonts.
+ </item>
+
+ <item>
+ 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.
+ </item>
+
+ <item>
+ 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>
+ <file>fonts.dir</file> files must not be provided at all.
+ </item>
+
+ <item>
+ <file>fonts.alias</file> and <file>fonts.scale</file>
+ files, if needed, should be provided in the
+ directory
+ <file>/etc/X11/fonts/<var>fontdir</var>/<var>package</var>.<var>extension</var></file>,
+ where <var>fontdir</var> is the name of the
+ subdirectory of
+ <file>/usr/X11R6/lib/X11/fonts/</file> where the
+ package's corresponding fonts are stored
+ (e.g., <tt>75dpi</tt> or <tt>misc</tt>),
+ <var>package</var> is the name of the package
+ that provides these fonts, and
+ <var>extension</var> is either <tt>scale</tt>
+ or <tt>alias</tt>, whichever corresponds to
+ the file contents.
+ </item>
+ </list>
+ </item>
- <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>
+ Font packages must declare a dependency on
+ <tt>xutils (>> 4.0.3)</tt> in their control
+ data.
</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>
+ Font packages that provide one or more
+ <file>fonts.scale</file> files as described above must
+ invoke <prgn>update-fonts-scale</prgn> on each
+ directory into which they installed fonts
+ <em>before</em> invoking
+ <prgn>update-fonts-dir</prgn> on that directory.
+ This invocation must occur in both the
+ <prgn>postinst</prgn> (for all arguments) and
+ <prgn>postrm</prgn> (for all arguments except
+ <tt>upgrade</tt>) scripts.
</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>
+ Font packages that provide one or more
+ <file>fonts.alias</file> files as described above must
+ invoke <prgn>update-fonts-alias</prgn> on each
+ directory into which they installed fonts. This
+ invocation must occur in both the
+ <prgn>postinst</prgn> (for all arguments) and
+ <prgn>postrm</prgn> (for all arguments except
+ <tt>upgrade</tt>) scripts.
</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>
+ 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.
</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>
- This is so that the control file which is produced has
- the right permissions
- </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>
+ <item>
+ Font packages must not provide alias names for the
+ fonts they include which collide with alias names
+ already in use by fonts already packaged.
+ </item>
- <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.
+ <item>
+ Font packages must not provide fonts with the same
+ XLFD registry name as another font already packaged.
+ </item>
+ </enumlist>
</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>
+ <heading>Application defaults files</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>
+ Application defaults files must be installed in the
+ directory <file>/etc/X11/app-defaults/</file> (use of a
+ localized subdirectory of <file>/etc/X11/</file> as described
+ in the <em>X Toolkit Intrinsics - C Language
+ Interface</em> manual is also permitted). They must be
+ registered as <tt>conffile</tt>s or handled as
+ configuration files. Packages must not provide the
+ directory <file>/usr/X11R6/lib/X11/app-defaults/</file>.
</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.
+ Customization of programs' X resources may also be
+ supported with the provision of a file with the same name
+ as that of the package placed in the
+ <file>/etc/X11/Xresources/</file> directory, which must
+ registered as a <tt>conffile</tt> or handled as a
+ configuration file.<footnote>
+ 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.
+ </footnote>
+ <em>Important:</em> packages that install files into the
+ <file>/etc/X11/Xresources/</file> directory must conflict with
+ <tt>xbase (<< 3.3.2.3a-2)</tt>; if this is not done
+ it is possible for the installing package to destroy a
+ previously-existing <file>/etc/X11/Xresources</file> file
+ which had been customized by the system administrator.
</p>
</sect1>
-
<sect1>
- <heading>
- <prgn>dpkg-distaddfile</prgn> - adds a file to
- <file>debian/files</file>
- </heading>
+ <heading>Installation directory issues</heading>
<p>
- Some packages' uploads need to include files other than
- the source and binary package files.
+ Packages using the X Window System should not be
+ configured to install files under the <file>/usr/X11R6/</file>
+ directory unless they use <prgn>imake</prgn>. The
+ <file>/usr/X11R6/</file> directory hierarchy should be
+ regarded as deprecated for all packages except the X
+ Window System itself, and those which use the
+ <prgn>imake</prgn> program it provides, in which case the
+ packages may transition out of the <file>/usr/X11R6/</file>
+ directory at the maintainer's discretion.<footnote>
+ <prgn>Imake</prgn>-using programs are exempt because,
+ as long as they are written correctly, the pathnames
+ they use to locate resources and install themselves
+ are derived wholly from the X Window System
+ configuration. Thus, in the event that the X Window
+ System moves to <file>/usr/X11R7/</file>,
+ <file>/usr/X12/</file>, or just plain <file>/usr/</file>, all
+ that is required for these programs is a recompile
+ against the corresponding X Window System library
+ development packages.
+ </footnote>
</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.
+ 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
+ <file>/usr/X11R6/</file>, and this should be done whenever
+ possible. Configuration files for window managers and
+ display managers should be placed in a subdirectory of
+ <file>/etc/X11/</file> corresponding to the package name due
+ to these programs' tight integration with the mechanisms
+ of the X Window System. Application-level programs should
+ use the <file>/etc/</file> directory unless otherwise mandated
+ by policy.
</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>.
+ 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
+ <file>/usr/lib/</file> and <file>/usr/share/</file> can be used
+ 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.)
</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">.
+ 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
+ their <tt>X11R6</tt>-named counterparts
+ <file>/usr/X11R6/bin/</file>, <file>/usr/X11R6/include/X11/</file>
+ and <file>/usr/X11R6/lib/X11/</file>, if the resources being
+ referred to have not been moved to other FHS-compliant
+ locations.
</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>
+ <sect1>
+ <heading>The OSF/Motif and OpenMotif libraries</heading>
<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.
+ <em>Programs that require the non-DFSG-compliant OSF/Motif or
+ OpenMotif libraries</em><footnote>
+ OSF/Motif and OpenMotif are collectively referred to as
+ "Motif" in this policy document.
+ </footnote>
+ should be compiled against and tested with LessTif (a free
+ re-implementation of Motif) instead. If the maintainer
+ judges that the program or programs do not work
+ sufficiently well with LessTif to be distributed and
+ supported, but do so when compiled against Motif, then two
+ versions of the package should be created; one linked
+ statically against Motif and with <tt>-smotif</tt>
+ appended to the package name, and one linked dynamically
+ against Motif and with <tt>-dmotif</tt> appended to the
+ package name.
</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.
+ Both Motif-linked versions are dependent
+ upon non-DFSG-compliant software and thus cannot be
+ uploaded to the <em>main</em> distribution; if the
+ software is itself DFSG-compliant it may be uploaded to
+ the <em>contrib</em> distribution. While known existing
+ versions of Motif permit unlimited redistribution of
+ binaries linked against the library (whether statically or
+ dynamically), it is the package maintainer's
+ responsibility to determine whether this is permitted by
+ the license of the copy of Motif in his or her possession.
</p>
</sect1>
-
- <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>
+ <sect id="perl">
+ <heading>Perl programs and modules</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.
+ Perl programs and modules should follow the current Perl policy.
</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.
+ 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>
- <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>
+ <sect id="emacs">
+ <heading>Emacs lisp programs</heading>
- <p>
- The <tt>binary</tt> targets must be invoked as
- root.
- </p>
- </item>
+ <p>
+ Please refer to the "Debian Emacs Policy" for details of how to
+ package emacs lisp programs.
+ </p>
- <tag><tt>clean</tt></tag>
- <item>
+ <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>
- <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>
+ <sect>
+ <heading>Games</heading>
- <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 permissions on <file>/var/games</file> are mode 755, owner
+ <tt>root</tt> and group <tt>root</tt>.
+ </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>
+ <p>
+ Each game decides on its own security policy.</p>
- <tag><tt>get-orig-source</tt> (optional)</tag>
- <item>
+ <p>
+ Games which require protected, privileged access to
+ high-score files, savegames, etc., may be made
+ set-<em>group</em>-id (mode 2755) and owned by
+ <tt>root.games</tt>, and use files and directories with
+ appropriate permissions (770 <tt>root.games</tt>, for
+ example). They must not be made
+ set-<em>user</em>-id, as this causes security problems. (If
+ an attacker can subvert any set-user-id game they can
+ overwrite the executable of any other, causing other players
+ of these games to run a Trojan horse program. With a
+ set-group-id game the attacker only gets access to less
+ important game data, and if they can get at the other
+ players' accounts at all it will take considerably more
+ effort.)</p>
- <p>
- This target fetches the most recent version of the
- original source package from a canonical archive
- site (via FTP or WWW, for example), does any
- necessary rearrangement to turn it into the original
- source tarfile format described below, and leaves it
- in the current directory.
- </p>
+ <p>
+ Some packages, for example some fortune cookie programs, are
+ configured by the upstream authors to install with their
+ data files or other static information made unreadable so
+ that they can only be accessed through set-id programs
+ provided. You should not do this in a Debian package: anyone can
+ download the <file>.deb</file> file and read the data from it,
+ so there is no point making the files unreadable. Not
+ making the files unreadable also means that you don't have
+ to make so many programs set-id, which reduces the risk of a
+ security hole.</p>
- <p>
- This target may be invoked in any directory, and
- should take care to clean up any temporary files it
- may have left.
- </p>
+ <p>
+ As described in the FHS, binaries of games should be
+ installed in the directory <file>/usr/games</file>. This also
+ applies to games that use the X Window System. Manual pages
+ for games (X and non-X games) should be installed in
+ <file>/usr/share/man/man6</file>.</p>
+ </sect>
+ </chapt>
- <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>
+ <chapt id="docs">
+ <heading>Documentation</heading>
+ <sect>
+ <heading>Manual pages</heading>
- <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>
+ You should install manual pages in <prgn>nroff</prgn> source
+ form, in appropriate places under <file>/usr/share/man</file>.
+ You should only use sections 1 to 9 (see the FHS for more
+ details). You must not install a preformatted "cat page".
+ </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>
+ Each program, utility, and function should have an
+ associated manual page included in the same package. It is
+ suggested that all configuration files also have a manual
+ page included as well. Manual pages for protocols and other
+ auxiliary things are optional.
+ </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>
+ If no manual page is available, this is considered as a bug
+ and should be reported to the Debian Bug Tracking System (the
+ 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>
+ 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">,
+ <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>.
+ </footnote>
+ </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>
+ You may forward a complaint about a missing manpage to the
+ upstream authors, and mark the bug as forwarded in the
+ Debian bug tracking system. Even though the GNU Project do
+ not in general consider the lack of a manpage to be a bug,
+ we do; if they tell you that they don't consider it a bug
+ you should leave the bug in our bug tracking system open
+ anyway.
+ </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>
+ <p>
+ Manual pages should be installed compressed using <tt>gzip -9</tt>.
+ </p>
+ <p>
+ If one manpage needs to be accessible via several names it
+ is better to use a symbolic link than the <file>.so</file>
+ feature, but there is no need to fiddle with the relevant
+ parts of the upstream source to change from <file>.so</file> to
+ symlinks: don't do it unless it's easy. You should not
+ create hard links in the manual page directories, nor put
+ absolute filenames in <file>.so</file> directives. The filename
+ in a <file>.so</file> in a manpage should be relative to the
+ base of the manpage tree (usually
+ <file>/usr/share/man</file>). If you do not create any links
+ (whether symlinks, hard links, or <tt>.so</tt> directives)
+ in the filesystem to the alternate names of the manpage,
+ then you should not rely on <prgn>man</prgn> finding your
+ manpage under those names based solely on the information in
+ the manpage's header.<footnote>
+ 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.
+ </footnote>
+ </p>
+ </sect>
- <sect1><heading><file>debian/control</file>
- </heading>
+ <sect>
+ <heading>Info documents</heading>
- This file contains version-independent details about the
- source package and about the binary packages it creates.
- </p>
+ <p>
+ Info documents should be installed in <file>/usr/share/info</file>.
+ They should be compressed with <tt>gzip -9</tt>.
+ </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>
+ Your package should call <prgn>install-info</prgn> to update
+ the Info <file>dir</file> file in its <prgn>postinst</prgn>
+ script when called with a <tt>configure</tt> argument, for
+ example:
+ <example compact="compact">
+install-info --quiet --section Development Development \
+ /usr/share/info/foobar.info
+ </example></p>
- <p>
- The syntax and semantics of the fields are described below
- in <ref id="pkg-controlfields">.
- </p>
+ <p>
+ It is a good idea to specify a section for the location of
+ your program; this is done with the <tt>--section</tt>
+ switch. To determine which section to use, you should look
+ at <file>/usr/share/info/dir</file> on your system and choose the most
+ relevant (or create a new section if none of the current
+ sections are relevant). Note that the <tt>--section</tt>
+ flag takes two arguments; the first is a regular expression
+ to match (case-insensitively) against an existing section,
+ the second is used when creating a new one.</p>
- <p>
- 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>
+ You should remove the entries in the <prgn>prerm</prgn>
+ script when called with a <tt>remove</tt> argument:
+ <example compact="compact">
+install-info --quiet --remove /usr/share/info/foobar.info
+ </example></p>
- <p>
- 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>
+ If <prgn>install-info</prgn> cannot find a description entry
+ in the Info file you must supply one. See <manref
+ name="install-info" section="8"> for details.</p>
+ </sect>
- <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>
+ <sect>
+ <heading>Additional documentation</heading>
- <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>
+ Any additional documentation that comes with the package may
+ be installed at the discretion of the package maintainer.
+ Text documentation should be installed in the directory
+ <file>/usr/share/doc/<var>package</var></file>, where
+ <var>package</var> is the name of the package, and
+ compressed with <tt>gzip -9</tt> unless it is small.
+ </p>
- <p> <sect2><heading>User-defined fields
- </heading>
+ <p>
+ If a package comes with large amounts of documentation which
+ many users of the package will not require you should create
+ a separate binary package to contain it, so that it does not
+ take up disk space on the machines of users who do not need
+ or want it installed.</p>
- <p>
- 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>
+ It is often a good idea to put text information files
+ (<file>README</file>s, changelogs, and so forth) that come with
+ the source package in <file>/usr/share/doc/<var>package</var></file>
+ in the binary package. However, you don't need to install
+ the instructions for building and installing the package, of
+ course!</p>
- <p>
- If you wish to add additional unsupported fields to
- these output files you should use the mechanism
- described here.
- </p>
+ <p>
+ Packages must not require the existence of any files in
+ <file>/usr/share/doc/</file> in order to function
+ <footnote>
+ The system administrator should be able to
+ delete files in <file>/usr/share/doc/</file> without causing
+ any programs to break.
+ </footnote>.
+ Any files that are referenced by programs but are also
+ useful as standalone documentation should be installed under
+ <file>/usr/share/<var>package</var>/</file> with symbolic links from
+ <file>/usr/share/doc/<var>package</var></file>.
+ </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>
+ <file>/usr/share/doc/<var>package</var></file> may be a symbolic
+ link to another directory in <file>/usr/share/doc</file> only if
+ the two packages both come from the same source and the
+ first package Depends on the second.
+ </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>
+ <p>
+ Former Debian releases placed all additional documentation
+ in <file>/usr/doc/<var>package</var></file>. This has been
+ 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>
+ 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.
+ </footnote>
+ </p>
+ </sect>
- </sect1>
+ <sect>
+ <heading>Preferred documentation formats</heading>
- <sect1 id="pkg-dpkgchangelog"><heading><file>debian/changelog</file>
- </heading>
+ <p>
+ The unification of Debian documentation is being carried out
+ via HTML.</p>
- <p>
- This file records the changes to the Debian-specific parts of the
- package
- <footnote>
- 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.
- </footnote>.
- </p>
+ <p>
+ If your package comes with extensive documentation in a
+ markup format that can be converted to various other formats
+ you should if possible ship HTML versions in a binary
+ package, in the directory
+ <file>/usr/share/doc/<var>appropriate-package</var></file> or
+ its subdirectories.<footnote>
+ 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.
+ </footnote>
+ </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>
+ Other formats such as PostScript may be provided at the
+ package maintainer's discretion.
+ </p>
+ </sect>
- <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>
+ <sect id="copyrightfile">
+ <heading>Copyright information</heading>
- * <var>change details</var>
- <var>more change details</var>
- * <var>even more change details</var>
+ <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>. This
+ file must neither be compressed nor be a symbolic link.
+ </p>
- -- <var>maintainer name and email address</var> <var>date</var>
- </example>
- </p>
+ <p>
+ In addition, the copyright file must say where the upstream
+ sources (if any) were obtained. It should name the original
+ authors of the package and the Debian maintainer(s) who were
+ involved with its creation.</p>
- <p>
- <var>package</var> and <var>version</var> are the source
- package name and version number.
- </p>
+ <p>
+ A copy of the file which will be installed in
+ <file>/usr/share/doc/<var>package</var>/copyright</file> should
+ be in <file>debian/copyright</file> in the source package.
+ </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>
+ <file>/usr/share/doc/<var>package</var></file> may be a symbolic
+ link to another directory in <file>/usr/share/doc</file> only if
+ the two packages both come from the same source and the
+ first package Depends on the second. These rules are
+ important because copyrights must be extractable by
+ mechanical means.
+ </p>
- <p>
- <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>
+ Packages distributed under the UCB BSD license, the Artistic
+ license, the GNU GPL, and the GNU LGPL should refer to the
+ files <file>/usr/share/common-licenses/BSD</file>,
+ <file>/usr/share/common-licenses/Artistic</file>,
+ <file>/usr/share/common-licenses/GPL</file>, and
+ <file>/usr/share/common-licenses/LGPL</file> respectively,
+ rather than quoting them in the copyright file.
+ </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>
+ You should not use the copyright file as a general <file>README</file>
+ file. If your package has such a file it should be
+ installed in <file>/usr/share/doc/<var>package</var>/README</file> or
+ <file>README.Debian</file> or some other appropriate place.</p>
+ </sect>
- <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>
+ <sect>
+ <heading>Examples</heading>
- <p>
- 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 timezone specified
- numerically, with the timezone name or abbreviation
- optionally present as a comment.
- </p>
+ <p>
+ Any examples (configurations, source files, whatever),
+ should be installed in a directory
+ <file>/usr/share/doc/<var>package</var>/examples</file>. These
+ files should not be referenced by any program: they're there
+ for the benefit of the system administrator and users as
+ documentation only. Architecture-specific example files
+ should be installed in a directory
+ <file>/usr/lib/<var>package</var>/examples</file> with symbolic
+ links to them from
+ <file>/usr/share/doc/<var>package</var>/examples</file>, or the
+ latter directory itself may be a symbolic link to the
+ former.
+ </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>
+ 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>
- <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>
+ <sect id="changelogs">
+ <heading>Changelog files</heading>
- <sect2><heading>Defining alternative changelog formats
- </heading>
+ <p>
+ Packages that are not Debian-native must contain a
+ compressed copy of the <file>debian/changelog</file> file from
+ the Debian source tree in
+ <file>/usr/share/doc/<var>package</var></file> with the name
+ <file>changelog.Debian.gz</file>.
+ </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>
+ If an upstream changelog is available, it should be accessible as
+ <file>/usr/share/doc/<var>package</var>/changelog.gz</file> in
+ plain text. If the upstream changelog is distributed in
+ HTML, it should be made available in that form as
+ <file>/usr/share/doc/<var>package</var>/changelog.html.gz</file>
+ and a plain text <file>changelog.gz</file> should be generated
+ from it using, for example, <tt>lynx -dump -nolist</tt>. If
+ the upstream changelog files do not already conform to this
+ naming convention, then this may be achieved either by
+ renaming the files, or by adding a symbolic link, at the
+ maintainer's discretion.<footnote>
+ 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.
+ </footnote>
+ </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>
+ All of these files should be installed compressed using
+ <tt>gzip -9</tt>, as they will become large with time even
+ if they start out small.
+ </p>
- <p>
- If 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>
+ If the package has only one changelog which is used both as
+ the Debian changelog and the upstream one because there is
+ no separate upstream maintainer then that changelog should
+ usually be installed as
+ <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>
- <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>
+ </sect>
+ </chapt>
- <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>
+ <appendix id="pkg-scope">
+ <heading>Introduction and scope of these appendices</heading>
- <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>
+ These appendices are taken essentially verbatim from the
+ now-deprecated Packaging Manual, version 3.2.1.0. They are
+ the chapters which are likely to be of use to package
+ maintainers and which have not already been included in the
+ policy document itself. Most of these sections are very likely
+ not relevant to policy; they should be treated as
+ documentation for the packaging system. Please note that these
+ appendices are included for convenience, and for historical
+ reasons: they used to be part of policy package, and they have
+ not yet been incorporated into dpkg documentation. However,
+ they still have value, and hence they are presented here.
+ </p>
+
+ <p>
+ They have not yet been checked to ensure that they are
+ compatible with the contents of policy, and if there are any
+ contradictions, the version in the main policy document takes
+ precedence. The remaining chapters of the old Packaging
+ Manual have also not been read in detail to ensure that there
+ are not parts which have been left out. Both of these will be
+ done in due course.
+ </p>
- <p>
- For the format of the <tt>Changes</tt> field see <ref
- id="pkg-f-Changes">.
- </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>
- 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>
+ <prgn>dpkg</prgn> is a suite of programs for creating binary
+ package files and installing and removing them on Unix
+ systems.<footnote>
+ <prgn>dpkg</prgn> is targetted primarily at Debian
+ GNU/Linux, but may work on or be ported to other
+ systems.
+ </footnote>
+ </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>
+ The binary packages are designed for the management of
+ installed executable programs (usually compiled binaries) and
+ their associated data, though source code examples and
+ documentation are provided as part of some packages.</p>
- 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>
+ This manual describes the technical aspects of creating Debian
+ binary packages (<file>.deb</file> files). It documents the
+ behaviour of the package management programs
+ <prgn>dpkg</prgn>, <prgn>dselect</prgn> et al. and the way
+ they interact with packages.</p>
- <p>
- A changelog parser may not interact with the user at
- all.</p></sect2>
- </sect1>
+ <p>
+ It also documents the interaction between
+ <prgn>dselect</prgn>'s core and the access method scripts it
+ uses to actually install the selected packages, and describes
+ how to create a new access method.</p>
-<!-- FIXME: section pkg-srcsubstvars is the same as srcsubstvars -->
+ <p>
+ This manual does not go into detail about the options and
+ usage of the package building and installation tools. It
+ should therefore be read in conjuction with those programs'
+ manpages.
+ </p>
- <sect1 id="pkg-srcsubstvars"><heading><file>debian/substvars</file>
- and variable substitutions
- </heading>
+ <p>
+ The utility programs which are provided with <prgn>dpkg</prgn>
+ for managing various system configuration and similar issues,
+ such as <prgn>update-rc.d</prgn> and
+ <prgn>install-info</prgn>, are not described in detail here -
+ please see their manpages.
+ </p>
- <p>
- 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>
+ It is assumed that the reader is reasonably familiar with the
+ <prgn>dpkg</prgn> System Administrators' manual.
+ Unfortunately this manual does not yet exist.
+ </p>
- <p>
- 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>
+ The Debian version of the FSF's GNU hello program is provided
+ as an example for people wishing to create Debian
+ packages. The Debian <prgn>debmake</prgn> package is
+ recommended as a very helpful tool in creating and maintaining
+ Debian packages. However, while the tools and examples are
+ helpful, they do not replace the need to read and follow the
+ Policy and Programmer's Manual.</p>
+ </appendix>
- <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>
+ <appendix id="pkg-binarypkg">
+ <heading>Binary packages (from old Packaging Manual)</heading>
- <sect1><heading><file>debian/files</file>
- </heading>
+ <p>
+ The binary package has two main sections. The first part
+ consists of various control information files and scripts used
+ by <prgn>dpkg</prgn> when installing and removing. See <ref
+ id="pkg-controlarea">.
+ </p>
- <p>
- 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>
+ The second part is an archive containing the files and
+ directories to be installed.
+ </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>
- <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
- </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>
+ In the future binary packages may also contain other
+ components, such as checksums and digital signatures. The
+ format for the archive is described in full in the
+ <file>deb(5)</file> manpage.
+ </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>
+ <sect id="pkg-bincreating"><heading>Creating package files -
+ <prgn>dpkg-deb</prgn>
+ </heading>
- <sect1><heading><file>debian/tmp</file>
- </heading>
+ <p>
+ All manipulation of binary package files is done by
+ <prgn>dpkg-deb</prgn>; it's the only program that has
+ knowledge of the format. (<prgn>dpkg-deb</prgn> may be
+ invoked by calling <prgn>dpkg</prgn>, as <prgn>dpkg</prgn>
+ will spot that the options requested are appropriate to
+ <prgn>dpkg-deb</prgn> and invoke that instead with the same
+ arguments.)
+ </p>
- <p>
- 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>
+ In order to create a binary package you must make a
+ directory tree which contains all the files and directories
+ you want to have in the filesystem data part of the package.
+ In Debian-format source packages this directory is usually
+ <file>debian/tmp</file>, relative to the top of the package's
+ source tree.
+ </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>
+ They should have the locations (relative to the root of the
+ directory tree you're constructing) ownerships and
+ permissions which you want them to have on the system when
+ they are installed.
+ </p>
- <p>
- 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>
+ <p>
+ With current versions of <prgn>dpkg</prgn> the uid/username
+ and gid/groupname mappings for the users and groups being
+ used should be the same on the system where the package is
+ built and the one where it is installed.
+ </p>
+ <p>
+ You need to add one special directory to the root of the
+ miniature filesystem tree you're creating:
+ <prgn>DEBIAN</prgn>. It should contain the control
+ information files, notably the binary package control file
+ (see <ref id="pkg-controlfile">).
+ </p>
- <sect id="pkg-sourcearchives"><heading>Source packages as archives
- </heading>
+ <p>
+ The <prgn>DEBIAN</prgn> directory will not appear in the
+ filesystem archive of the package, and so won't be installed
+ by <prgn>dpkg</prgn> when the package is installed.
+ </p>
<p>
- 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.
+ When you've prepared the package, you should invoke:
+ <example>
+ dpkg --build <var>directory</var>
+ </example>
</p>
<p>
- <taglist>
- <tag>Debian source control file - <tt>.dsc</tt></tag>
- <item>
+ This will build the package in
+ <file><var>directory</var>.deb</file>. (<prgn>dpkg</prgn> knows
+ that <tt>--build</tt> is a <prgn>dpkg-deb</prgn> option, so
+ it invokes <prgn>dpkg-deb</prgn> with the same arguments to
+ build the package.)
+ </p>
- <p>
- 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>
+ See the manpage <manref name="dpkg-deb" section="8"> for details of how
+ to examine the contents of this newly-created file. You may find the
+ output of following commands enlightening:
+ <example>
+ dpkg-deb --info <var>filename</var>.deb
+ dpkg-deb --contents <var>filename</var>.deb
+ dpkg --contents <var>filename</var>.deb
+ </example>
+ To view the copyright file for a package you could use this command:
+ <example>
+ dpkg --fsys-tarfile <var>filename</var>.deb | tar xof usr/share/doc/<var>\*</var>copyright | less
+ </example>
+ </p>
+ </sect>
- <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>
+ <sect id="pkg-controlarea">
+ <heading>Package control information files</heading>
- <tag>
- Original source archive -
- <file>
- <var>package</var>_<var>upstream-version</var>.orig.tar.gz
- </file>
- </tag>
+ <p>
+ The control information portion of a binary package is a
+ collection of files with names known to <prgn>dpkg</prgn>.
+ It will treat the contents of these files specially - some
+ of them contain information used by <prgn>dpkg</prgn> when
+ installing or removing the package; others are scripts which
+ the package maintainer wants <prgn>dpkg</prgn> to run.
+ </p>
+
+ <p>
+ It is possible to put other files in the package control
+ area, but this is not generally a good idea (though they
+ will largely be ignored).
+ </p>
+
+ <p>
+ Here is a brief list of the control info files supported by
+ <prgn>dpkg</prgn> and a summary of what they're used for.
+ </p>
+ <p>
+ <taglist>
+ <tag><tt>control</tt>
<item>
+ <p>
+ This is the key description file used by
+ <prgn>dpkg</prgn>. It specifies the package's name
+ and version, gives its description for the user,
+ states its relationships with other packages, and so
+ forth. See <ref id="sourcecontrolfiles"> and
+ <ref id="binarycontrolfiles">.
+ </p>
<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>
+ 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>
+ 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>
+
+ <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 id="pkg-controlfile">
+ <heading>The main control information file: <tt>control</tt></heading>
<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>.
+ 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 listed in
+ <ref id="binarycontrolfiles">.
+ </p>
+
+ <p>
+ A description of the syntax of control files and the purpose
+ of the fields is available in <ref id="controlfields">.
</p>
</sect>
- <sect><heading>Unpacking a Debian source package without
- <prgn>dpkg-source</prgn>
- </heading>
+ <sect>
+ <heading>Time Stamps</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>
+ See <ref id="timestamps">.
+ </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>
+
+ <sect id="pkg-sourcetools">
+ <heading>Tools for processing source packages</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.
+ 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>Restrictions on objects in source packages
+ <sect1>
+ <heading>
+ <prgn>dpkg-source</prgn> - packs and unpacks Debian source
+ packages
</heading>
<p>
- 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>
+ 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>
- 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>
+ 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>
- <item><p>Creating directories, other than <file>debian</file>.</p>
+ <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>
- <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">
+ <tag><tt>-r<var>root-command</var></tt></tag>
<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>
+ 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>
- Changed text files which are missing the usual final
- newline (either in the original or the modified
- source tree).
+ Two types of binary-only build and upload - see
+ <manref name="dpkg-source" section="1">.
</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>
- 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.
+ </taglist>
</p>
</sect1>
- </sect>
- </appendix>
-
- <appendix id="pkg-controlfields"><heading>Control files and their
- fields (from old Packaging Manual)
- </heading>
-
- <p>
- Many of the tools in the <prgn>dpkg</prgn> suite manipulate
- data in a common format, known as control files. Binary and
- source packages have control data as do the <file>.changes</file>
- files which control the installation of uploaded files, and
- <prgn>dpkg</prgn>'s internal databases are in a similar
- format.
- </p>
-
- <sect><heading>Syntax of control files
- </heading>
-
- <p>
- A file consists of one or more paragraphs of fields. The
- paragraphs are separated by blank lines. Some control files
- only allow one paragraph; others allow several, in which
- case each paragraph often refers to a different package.
- </p>
-
- <p>
- Each paragraph is a series of fields and values; each field
- consists of a name, followed by a colon and the value. It
- ends at the end of the line. Horizontal whitespace (spaces
- and tabs) may occur before or after the value and is ignored
- there; it is conventional to put a single space after the
- colon.
- </p>
-
- <p>
- Some fields' values may span several lines; in this case
- each continuation line <em>must</em> start with a space or
- tab. Any trailing spaces or tabs at the end of individual
- lines of a field value are ignored.
- </p>
- <p>
- Except where otherwise stated only a single line of data is
- allowed and whitespace is not significant in a field body.
- Whitespace may never appear inside names (of packages,
- architectures, files or anything else), version numbers or
- in between the characters of multi-character version
- relationships.
- </p>
-
- <p>
- Field names are not case-sensitive, but it is usual to
- capitalise the field names using mixed case as shown below.
- </p>
-
- <p>
- Blank lines, or lines consisting only of spaces and tabs,
- are not allowed within field values or between fields - that
- would mean a new paragraph.
- </p>
-
- <p>
- It is important to note that there are several fields which
- are optional as far as <prgn>dpkg</prgn> and the related
- tools are concerned, but which must appear in every Debian
- package, or whose omission may cause problems.
- </p>
- </sect>
+ <sect1>
+ <heading>
+ <prgn>dpkg-gencontrol</prgn> - generates binary package
+ control files
+ </heading>
- <sect><heading>List of fields
- </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>
- <sect1 id="pkg-f-Package"><heading><tt>Package</tt>
- </heading>
+ <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>
+ This is so that the control file which is produced has
+ the right permissions
+ </footnote>.
+ </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>
- 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.
- </footnote>
+ <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>
- 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>
- This is a bug.
- </footnote>; use lowercase package names unless
- the package you're building (or referring to, in other
- fields) is already using uppercase.
+ 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>
- </sect1>
- <sect1 id="pkg-f-Version"><heading><tt>Version</tt>
- </heading>
+ <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>
- This lists the source or binary package's version number -
- see <ref id="versions">.
+ 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-Architecture"><heading><tt>Architecture</tt>
+ <sect1>
+ <heading>
+ <prgn>dpkg-shlibdeps</prgn> - calculates shared library
+ dependencies
</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>
+ just before <prgn>dpkg-gencontrol</prgn> (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.
+ 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>
- The special value <tt>all</tt> indicates that the package
- is architecture-independent.
+ 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>
- 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.
+ <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>
- 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 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>
- See <ref id="pkg-debianrules"> for information how to get the
- architecture for the build process.
+ 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 id="pkg-f-Maintainer"><heading><tt>Maintainer</tt>
+
+ <sect1>
+ <heading>
+ <prgn>dpkg-distaddfile</prgn> - adds a file to
+ <file>debian/files</file>
</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).
+ Some packages' uploads need to include files other than
+ the source and binary package files.
</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).
+ <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>
- 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.
+ 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>
- 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>
+ The <var>section</var> and <var>priority</var> are passed
+ unchanged into the resulting <file>.changes</file> file.
+ </p>
</sect1>
- <sect1 id="pkg-f-Source"><heading><tt>Source</tt>
- </heading>
- <p>
- This field identifies the source package name.
- </p>
+ <sect1><heading><prgn>dpkg-genchanges</prgn> - generates a <file>.changes</file> upload
+ control 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.
+ 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 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>
- It is usual 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.
+ 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>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>
+
+ <sect1><heading><prgn>dpkg-parsechangelog</prgn> - produces parsed representation of
+ a changelog
</heading>
<p>
- These fields describe the package's relationships with
- other packages. Their syntax and semantics are described
- in <ref id="relationships">.</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-f-Description"><heading><tt>Description</tt>
- </heading>
+ <sect1 id="pkg-dpkgarch"><heading><prgn>dpkg-architecture</prgn> -
+ information about the build and host system
+ </heading>
- <p>
- In a binary package <tt>Packages</tt> file or main source
- control file this field contains a description of the
- binary package, in a special format. See <ref
- id="descriptions"> for details.
- </p>
+ <p>
+ 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>
- 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>
- </sect1>
+ <sect id="pkg-sourcetree">
+ <heading>The Debianised source tree</heading>
- <sect1 id="pkg-f-Essential"><heading><tt>Essential</tt>
- </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>
- 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.
- </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>
- 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>
+ See <ref id="debianrules">.
+ </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-dpkgchangelog">
+ <heading><file>debian/changelog</file></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.
+ See <ref id="dpkgchangelog">.
</p>
- <p>
- The section and priority are represented, though not as
- separate fields, in the information for each file in the
- <qref id="pkg-f-Files"><tt>-File</tt></qref>field of a
- <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>
+ <sect2><heading>Defining alternative changelog formats
+ </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.
- </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>
- These fields can appear in binary package control files,
- in which case they provide a default value in case the
- <file>Packages</file> files are missing the information.
- <prgn>dpkg</prgn> and <prgn>dselect</prgn> will only use
- the 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>
+ 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>
- <sect1 id="pkg-f-Binary"><heading><tt>Binary</tt>
- </heading>
+ <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>
- This field is a list of binary packages.
- </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>
- 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>
+ 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>
- When it appears in a <file>.changes</file> file it lists the
- names of the binary packages actually being uploaded.
- </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>
- 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>
+ <p>
+ For the format of the <tt>Changes</tt> field see
+ <ref id="f-Changes">.
+ </p>
- <sect1 id="pkg-f-Installed-Size"><heading><tt>Installed-Size</tt>
- </heading>
+ <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>
- 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>
+ 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>
- The disk space is represented in kilobytes as a simple
- decimal number.</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>
- 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>
+ </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 Debian Policy
- and associated texts) with which the package complies. This
- is updated manually when editing the source package to
- conform to newer standards; it can sometimes be used to
- tell when a package needs attention.
+ 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>
projects / debian / debian-policy.git / commitdiff