<tt>/usr/share/common-licenses/GPL</tt> in the Debian GNU/Linux
distribution or on the World Wide Web at
<url id="http://www.gnu.org/copyleft/gpl.html"
- name="The GNU General Public Licence">. You can also obtain it by writing to the
- Free Software Foundation, Inc., 59 Temple Place - Suite 330,
- Boston, MA 02111-1307, USA.
+ name="The GNU General Public Licence">. You can also
+ obtain it by writing to the Free Software Foundation, Inc.,
+ 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
</p>
</copyright>
</titlepag>
<p>
Informally, the criteria used for inclusion is that the
material meet one of the following requirements:
- <taglist>
+ <taglist compact="compact">
<tag>Standard interfaces</tag>
<item>
<p>
interfaces not changing, and the package
management software authors need to ensure
compatibility with these interface
- definitions. (Control file and and changelog file
+ definitions. (Control file and changelog file
formats are examples.)
</p>
</item>
<em>may</em>, and the adjectives <em>required</em>,
<em>recommended</em> and <em>optional</em>, are used to
distinguish the significance of the various guidelines in
- this policy document. Packages that do not conform the the
+ this policy document. Packages that do not conform to the
guidelines denoted by <em>must</em> (or <em>required</em>)
will generally not be considered acceptable for the Debian
distribution. Non-conformance with guidelines denoted by
</p>
</sect>
</chapt>
- <chapt>
+
+ <chapt id="archive">
<heading>The Debian Archive</heading>
<p>
The Debian GNU/Linux system is maintained and distributed as a
<p>
Every package must be accompanied by a verbatim copy of
its copyright and distribution license in the file
- <tt>/usr/share/doc/<em><package-name></em>/copyright</tt>
+ <tt>/usr/share/doc/<em><package></em>/copyright</tt>
(see <ref id="copyrightfile"> for further details).
</p>
<p>
<item>
<p>
These packages provide a reasonably small but not too
- limited character-mode system. This is what will
- install by default if the user doesn't select anything
+ limited character-mode system. This is what will be
+ installed by default if the user doesn't select anything
else. It doesn't include many large applications, but
it does include Emacs (this is more of a piece of
infrastructure than an application) and a reasonable
archive.</p>
<p>
- Package names must consist of lower case letters (a-z),
- digits (0-9), plus (+) and minus (-) signs, and periods
- (.). They must be at least two characters long and must
- contain at least one letter.
+ Package names must consist of lower case letters
+ (<tt>a-z</tt>), digits (<tt>0-9</tt>), plus (<tt>+</tt>)
+ and minus (<tt>-</tt>) signs, and periods (<tt>.</tt>).
+ They must be at least two characters long and must contain
+ at least one letter.
</p>
<p>
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
+ 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>
+ either (that is what the copyright file is for).
+ </p>
</sect1>
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
+ 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
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
+ 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>
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
+ <prgn>update-alternatives</prgn>; this is an exception to
the usual rule that versioned conflicts should be
avoided).
</p>
<footnote>
<p>
2.5% of Debian packages [see <url
- id="http://kitenet.net/programs/debconf/stats/">]
- currently use <package>debconf</package> to prompt
- the user at install time, and this number is growing
- daily. The benefits of using debconf are briefly
- explained at <url
- id="http://kitenet.net/doc/debconf-doc/introduction.html">;
- they include preconfiguration, (mostly)
- noninteractive installation, elimination of
- redundant prompting, consistency of user interface,
- etc.
+ id="http://kitenet.net/programs/debconf/stats/"
+ name="Debconf stats">] currently use
+ <package>debconf</package> to prompt the user at
+ install time, and this number is growing daily. The
+ benefits of using debconf are briefly explained at
+ <url
+ id="http://kitenet.net/doc/debconf-doc/introduction.html"
+ name="Debconf introduction">; they include
+ preconfiguration, (mostly) noninteractive
+ installation, elimination of redundant prompting,
+ consistency of user interface, etc.
</p>
<p>
With this increasing number of packages using
</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 <tt>/etc</tt> so that the user can
- modify them, and how this has been done should be
- documented.</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 <tt>/etc</tt> 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
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>
- <sect1>
+ <sect1 id="standardsversion">
<heading>Standards conformance</heading>
- <sect id="standardsversion">
<p>
In the source package's <tt>Standards-Version</tt> control
</p>
<p>
- The version number has four components--major and minor
+ 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
package).
<footnote>
<p>Rationale:
- <list>
+ <list compact="compact">
<item>
<p>This allows maintaining the list separately
from the policy documents (the list does not
format.
</p>
- <sect><heading>Syntax of control files</heading>
+ <sect id="controlsyntax"><heading>Syntax of control files</heading>
<p>
A control file consists of one or more paragraphs of fields.
tabs) may occur immediately before or after the value and is
ignored there; it is conventional to put a single space
after the colon. For example, a field might be:
- <example>
- Package: libc6
+ <example compact="compact">
+Package: libc6
</example>
the field name is <tt>Package</tt> and the field value
<tt>libc6</tt>.
archive maintainers.
<footnote>
Current distribution names are:
- <taglist>
+ <taglist compact="compact">
<tag><em>stable</em></tag>
<item>
<p>
<tag><em>frozen</em></tag>
<item>
<p>
- From time to time, the <em>frozen</em>
+ 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
</sect>
</chapt>
- <chapt id="versions"><heading>Version numbering </heading>
+ <chapt id="versions"><heading>Version numbering</heading>
<p>
- Every package has a version number, in its <tt>Version</tt>
- control file field.
+ Every package has a version number recorded in its
+ <tt>Version</tt> control file field.
</p>
<p>
<p>
The version number format is:
- &lsqb<var>epoch</var><tt>:</tt>]<var>upstream-version</var>[<tt>-</tt><var>debian-revision</var>]
+ &lsqb<var>epoch</var><tt>:</tt>]<var>upstream_version</var>[<tt>-</tt><var>debian_revision</var>]
</p>
<p>
<p>
This is a single (generally small) unsigned integer. It
may be omitted, in which case zero is assumed. If it is
- omitted then the <var>upstream-version</var> may not
+ omitted then the <var>upstream_version</var> may not
contain any colons.
</p>
</item>
- <tag><var>upstream-version</var></tag>
+ <tag><var>upstream_version</var></tag>
<item>
<p>
- This is the main part of the version. It is usually the
- version number of the original (`upstream') package from
- which the <tt>.deb</tt> file has been made, if this is
- applicable. Usually this will be in the same format as
- that specified by the upstream author(s); however, it
- may need to be reformatted to fit into the package
- management system's format and comparison scheme.
+ This is the main part of the version number. It is
+ usually the version number of the original (`upstream')
+ package from which the <tt>.deb</tt> file has been made,
+ if this is applicable. Usually this will be in the same
+ format as that specified by the upstream author(s);
+ however, it may need to be reformatted to fit into the
+ package management system's format and comparison
+ scheme.
</p>
<p>
The comparison behavior of the package management system
- with respect to the <var>upstream-version</var> is
- described below. The <var>upstream-version</var>
+ with respect to the <var>upstream_version</var> is
+ described below. The <var>upstream_version</var>
portion of the version number is mandatory.
</p>
<p>
- The <var>upstream-version</var> may contain only
- alphanumerics and the characters <tt>.</tt> <tt>+</tt>
- <tt>-</tt> <tt>:</tt> (full stop, plus, hyphen, colon)
- and should start with a digit. If there is no
- <var>debian-revision</var> then hyphens are not allowed;
+ The <var>upstream_version</var> may contain only
+ alphanumerics
+ <footnote>
+ <p>Alphanumerics are <tt>A-Za-z0-9</tt> only.</p>
+ </footnote>
+ and the characters <tt>.</tt> <tt>+</tt> <tt>-</tt>
+ <tt>:</tt> (full stop, plus, hyphen, colon) and should
+ start with a digit. If there is no
+ <var>debian_revision</var> then hyphens are not allowed;
if there is no <var>epoch</var> then colons are not
allowed.</p>
</item>
- <tag><var>debian-revision</var></tag>
+ <tag><var>debian_revision</var></tag>
<item>
<p>
- This part of the version represents the version of the
- modifications that were made to the package to make it a
- Debian binary package. It is in the same format as the
- <var>upstream-version</var> and is compared in the same
- way.
+ This part of the version number specifies the version of
+ the Debian package based on the upstream version. It
+ may contain only alphanumerics and the characters
+ <tt>+</tt> and <tt>.</tt> (plus and full stop) and is
+ compared in the same way as the
+ <var>upstream_version</var> is.
</p>
<p>
It is optional; if it isn't present then the
- <var>upstream-version</var> may not contain a hyphen.
+ <var>upstream_version</var> may not contain a hyphen.
This format represents the case where a piece of
software was written specifically to be turned into a
- Debian binary package, and so there is only one
- `debianization' of it and therefore no revision
- indication is required.
+ Debian package, and so there is only one `debianization'
+ of it and therefore no revision indication is required.
</p>
<p>
It is conventional to restart the
- <var>debian-revision</var> at <tt>1</tt> each time the
- <var>upstream-version</var> is increased.
- </p>
-
- <p>
- The package management system will break the
- <var>upstream-version</var> and
- <var>debian-revision</var> apart at the last hyphen in
- the string. The absence of a <var>debian-revision</var>
- compares earlier than the presence of one (but note that
- the <var>debian-revision</var> is the least significant
- part of the version number).
+ <var>debian_revision</var> at <tt>1</tt> each time the
+ <var>upstream_version</var> is increased.
</p>
<p>
- The <var>debian-revision</var> may contain only
- alphanumerics and the characters <tt>+</tt> and
- <tt>.</tt> (plus and full stop).
+ The package management system will break the version
+ number apart at the last hyphen in the string (if there
+ is one) to determine the <var>upstream_version</var> and
+ <var>debian_revision</var>. The absence of a
+ <var>debian_revision</var> compares earlier than the
+ presence of one (but note that the
+ <var>debian_revision</var> is the least significant part
+ of the version number).
</p>
</item>
</taglist>
- The <var>upstream-version</var> and <var>debian-revision</var>
+ </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>
<p>
- These two steps are repeated (chopping initial non-digit
- strings and initial digit strings off from the start) until a
+ These two steps (comparing and removing initial non-digit
+ strings and initial digit strings) are repeated until a
difference is found or both strings are exhausted.
</p>
<p>
Note that the purpose of epochs is to allow us to leave behind
mistakes in version numbering, and to cope with situations
- where the version numbering changes. It is <em>not</em> there
- to cope with version numbers containing strings of letters
- which the package management system cannot interpret (such as
- <tt>ALPHA</tt> or <tt>pre-</tt>), or with silly orderings (the
- author of this manual has heard of a package whose versions
- went <tt>1.1</tt>, <tt>1.2</tt>, <tt>1.3</tt>, <tt>1</tt>,
- <tt>2.1</tt>, <tt>2.2</tt>, <tt>2</tt> and so forth).
+ where the version numbering scheme changes. It is
+ <em>not</em> intended to cope with version numbers containing
+ strings of letters which the package management system cannot
+ interpret (such as <tt>ALPHA</tt> or <tt>pre-</tt>), or with
+ silly orderings (the author of this manual has heard of a
+ package whose versions went <tt>1.1</tt>, <tt>1.2</tt>,
+ <tt>1.3</tt>, <tt>1</tt>, <tt>2.1</tt>, <tt>2.2</tt>,
+ <tt>2</tt> and so forth).
</p>
<p>
too.</p>
<p>
- Note, that other version formats based on dates which are
+ Note that other version formats based on dates which are
parsed correctly by the package management system should
<em>not</em> be changed.</p>
<sect id="timestamps"><heading>Time Stamps</heading>
<p>
- Maintainers are encouraged to preserve the modification
- times of the upstream source files in a package, as far as
- is reasonably possible. Even though this is optional, this
- is still a good idea.
+ Maintainers should preserve the modification times of the
+ upstream source files in a package, as far as is reasonably
+ possible.
<footnote>
<p>
The rationale is that there is some information conveyed
</sect>
<sect id="debianrules"><heading><tt>debian/rules</tt> - the
- main building script </heading>
+ main building script</heading>
<p>
This file must be an executable makefile, and contains the
package-specific recipes for compiling the package and
- building binary package(s) out of the source.
+ building binary package(s) from the source.
</p>
<p>
Since an interactive <tt>debian/rules</tt> script makes it
impossible to auto-compile that package and also makes it
hard for other people to reproduce the same binary
- package, all <strong>required targets</strong> MUST be
+ package, all <em>required targets</em> MUST be
non-interactive. At a minimum, required targets are the
ones called by <prgn>dpkg-buildpackage</prgn>, namely,
<em>clean</em>, <em>binary</em>, <em>binary-arch</em>,
</p>
<p>
- The targets which must be present are:
+ The required and optional targets are as follows:
<taglist>
<tag><tt>build</tt></tag>
<item>
<p>
- This should perform all non-interactive
- configuration and compilation of the package. If a
- package has an interactive pre-build configuration
- routine, the Debianised source package should be
- built after this has taken place, so that it can be
- built without rerunning the configuration.
+ This should perform all non-interactive configuration
+ and compilation of the package. If a package has an
+ interactive pre-build configuration routine, the
+ Debianized source package must either be built after
+ this has taken place (so that the binary package can
+ be built without rerunning the configuration) or the
+ configuration routine modified to become
+ non-interactive. (The latter is preferable if there
+ are architecture-specific features detected by the
+ configuration routine.)
</p>
<p>
</p>
<p>
- The <prgn>build</prgn> target may need to run
- <prgn>clean</prgn> first - see below.
+ The <prgn>build</prgn> target may need to run the
+ <prgn>clean</prgn> target first - see below.
</p>
<p>
- When a package has a configuration routine that
- takes a long time, or when the makefiles are poorly
- designed, or when <prgn>build</prgn> needs to run
- <prgn>clean</prgn> first, it is a good idea to
+ When a package has a configuration and build routine
+ which takes a long time, or when the makefiles are
+ poorly designed, or when <prgn>build</prgn> needs to
+
run <prgn>clean</prgn> first, it is a good idea to
<tt>touch build</tt> when the build process is
complete. This will ensure that if <tt>debian/rules
- build</tt> is run again it will not rebuild the
- whole program.
+ build</tt> is run again it will not rebuild the whole
+ program.
+ <footnote>
+ <p>
+ Another common way to do this is for <prgn>build</prgn>
+ to depend on <prgn>build-stamp</prgn> and to do
+ nothing else, and for the <prgn>build-stamp</prgn>
+ target to do the building and to <tt>touch
+ build-stamp</tt> on completion. This is
+ especially useful if the build routine creates a
+ file or directory called <tt>build</tt>; in such a
+ case, <prgn>build</prgn> will need to be listed as
+ a phony target (i.e., as a dependency of the
+ <tt>.PHONY</tt> target). See the documentation of
+ <prgn>make</prgn> for more information on phony
+ targets.
+ </p>
+ </footnote>
</p>
</item>
<item>
<p>
The <prgn>binary</prgn> target must be all that is
- necessary for the user to build the binary
- package. All these targets are required to be
- non-interactive. It is split into two parts:
- <prgn>binary-arch</prgn> builds the packages' output
- files which are specific to a particular
+ necessary for the user to build the binary package(s)
+ produced from this source package. All of these
+ targets are required to be non-interactive. It is
+ split into two parts: <prgn>binary-arch</prgn> builds
+ the binary packages which are specific to a particular
architecture, and <prgn>binary-indep</prgn> builds
those which are not.
</p>
</p>
<p>
- Both <prgn>binary-*</prgn> targets should depend on
+ Each <prgn>binary-*</prgn> target should depend on
the <prgn>build</prgn> target, above, so that the
package is built if it has not been already. It
should then create the relevant binary package(s),
</p>
<p>
- If one of the <prgn>binary-*</prgn> targets has
- nothing to do (this will be always be the case if
- the source generates only a single binary package,
- whether architecture-dependent or not) it
- <em>must</em> still exist, and must always
- succeed.
+ Both the <prgn>binary-arch</prgn> and
+ <prgn>binary-indep</prgn> targets <em>must</em> exist.
+ If one of them has nothing to do (which will always be
+ the case if the source generates only a single binary
+ package, whether architecture-dependent or not), it
+ must still exist and must always succeed.
</p>
<p>
The <prgn>binary</prgn> targets must be invoked as
root.
+ <footnote>
+ <p>
+ The <prgn>fakeroot</prgn> package often allows one
+ to build a package correctly even without being
+ root.
+ </p>
+ </footnote>
</p>
</item>
<item>
<p>
- This must undo any effects that the
- <prgn>build</prgn> and <prgn>binary</prgn> targets
- may have had, except that it should leave alone any
- output files created in the parent directory by a
- run of <prgn>binary</prgn>. This target must be
- non-interactive.
+ This must undo any effects that the <prgn>build</prgn>
+ and <prgn>binary</prgn> targets may have had, except
+ that it should leave alone any output files created in
+ the parent directory by a run of a <prgn>binary</prgn>
+ target. This target must be non-interactive.
</p>
<p>
- If a <prgn>build</prgn> file is touched at the end
- of the <prgn>build</prgn> target, as suggested
- above, it should be removed as the first thing that
- <prgn>clean</prgn> does, so that running
+ If a <prgn>build</prgn> file is touched at the end of
+ the <prgn>build</prgn> target, as suggested above, it
+ should be removed as the first action that
+ <prgn>clean</prgn> performs, so that running
<prgn>build</prgn> again after an interrupted
<prgn>clean</prgn> doesn't think that everything is
already done.
<p>
The <prgn>build</prgn>, <prgn>binary</prgn> and
- <prgn>clean</prgn> targets must be invoked with a current
- directory of the package's top-level directory.
+ <prgn>clean</prgn> targets must be invoked with the current
+ directory being the package's top-level directory.
</p>
</p>
<p>
- The architecture we build on and build for is determined by
- make variables via dpkg-architecture. You can get the Debian
- architecture and the GNU style architecture specification
- string for the build machine as well as the host
- machine. Here is a list of supported make variables:
+ The architectures we build on and build for are determined
+ by <prgn>make</prgn> variables using the utility
+ <prgn>dpkg-architecture</prgn>. You can determine the
+ Debian architecture and the GNU style architecture
+ specification string for the build machine (the machine type
+ we are building on) as well as for the host machine (the
+ machine type we are building for). Here is a list of
+ supported <prgn>make</prgn> variables:
<list compact="compact">
<item>
<p><tt>DEB_*_ARCH</tt> (the Debian architecture)</p>
specification string)</p>
</item>
<item>
- <p><tt>DEB_*_GNU_CPU</tt> (the CPU part of DEB_*_GNU_TYPE)</p>
+ <p><tt>DEB_*_GNU_CPU</tt> (the CPU part of
+ <tt>DEB_*_GNU_TYPE</tt>)</p>
</item>
<item>
<p><tt>DEB_*_GNU_SYSTEM</tt> (the System part of
- DEB_*_GNU_TYPE)</p>
+ <tt>DEB_*_GNU_TYPE</tt>)</p>
</list>
- </p>
-
- <p>
where <tt>*</tt> is either <tt>BUILD</tt> for specification of
- the build machine or <tt>HOST</tt> for specification of the machine
- we build for.
+ the build machine or <tt>HOST</tt> for specification of the
+ host machine.
</p>
<p>
Backward compatibility can be provided in the rules file
by setting the needed variables to suitable default
- values, please refer to the documentation of
- dpkg-architecture for details.
+ values; please refer to the documentation of
+ <prgn>dpkg-architecture</prgn> for details.
</p>
<p>
Though there is nothing stopping an author who is also
the Debian maintainer from using it for all their
changes, it will have to be renamed if the Debian and
- upstream maintainers become different
- people.
+ upstream maintainers become different people. In such a
+ case, however, it might be better to maintain the
+ package as a non-native package.
</p>
</footnote>.
</p>
<p>
That format is a series of entries like this:
- <example>
- <var>package</var> (<var>version</var>) <var>distribution(s)</var>; urgency=<var>urgency</var>
+ <example compact="compact">
+<var>package</var> (<var>version</var>) <var>distribution(s)</var>; urgency=<var>urgency</var>
- * <var>change details</var>
- <var>more change details</var>
- * <var>even more change details</var>
+ * <var>change details</var>
+ <var>more change details</var>
+ * <var>even more change details</var>
- -- <var>maintainer name and email address</var> <var>date</var>
+ -- <var>maintainer name</var> <<var>email address</var>> <var>date</var>
</example>
</p>
<prgn>dpkg</prgn> changelog format (though there is
currently only one useful <var>keyword</var>,
<tt>urgency</tt>).
+ <footnote>
+ <p>
+ Usual urgency values are <tt>low</tt>, <tt>medium</tt>,
+ <tt>high</tt> and <tt>critical</tt>. They have an
+ effect on how quickly a package will be considered for
+ inclusion into the <tt>testing</tt> distribution, and
+ give an indication of the importance of any fixes
+ included in this upload.
+ </p>
+ </footnote>
</p>
<p>
</p>
<p>
- The maintainer name and email address need <em>not</em>
- necessarily be those of the usual package maintainer.
- They should be the details of the person doing
- <em>this</em> version. The information here will be
- copied to the <tt>.changes</tt> file, and then later used
- to send an acknowledgement when the upload has been
- installed.
+ If this upload resolves bugs recorded in the Bug Tracking
+ System (BTS), they may be automatically closed on the
+ inclusion of this package into the Debian archive by
+ including the string: <tt>closes: Bug#<var>nnnnn</var></tt>
+ in the change details.
+ <footnote>
+ <p>
+ To be precise, the string should match the following
+ Perl regular expression:
+ <example>
+/closes:\s*(?:bug)?\#?\s?\d+(?:,\s*(?:bug)?\#?\s?\d+)*/i
+ </example>
+ Then all of the bug numbers listed will be closed by the
+ archive maintenance script (<prgn>katie</prgn>), or in
+ the case of an NMU, marked as fixed.
+ </p>
+ </footnote>
+ </p>
+
+ <p>
+ The maintainer name and email address used in the changelog
+ should be the details of the person uploading <em>this</em>
+ version. They are <em>not</em> necessarily those of the
+ usual package maintainer. The information here will be
+ copied to the <tt>Changed-By</tt> field in the
+ <tt>.changes</tt> file, and then later used to send an
+ acknowledgement when the upload has been installed.
</p>
<p>
</p>
</footnote>; it should include the time zone specified
numerically, with the time zone name or abbreviation
- optionally present as a comment.
+ optionally present as a comment in parentheses.
</p>
<p>
<p>
When <prgn>dpkg-gencontrol</prgn>,
<prgn>dpkg-genchanges</prgn> and <prgn>dpkg-source</prgn>
- generate control files they do variable substitutions on
- their output just before writing it. Variable
+ generate control files they perform variable substitutions
+ on their output just before writing it. Variable
substitutions have the form
<tt>${<var>variable-name</var>}</tt>. The optional file
- <tt>debian/substvars</tt> contains variable substitutions
- to be used; variables can also be set directly from
+ <tt>debian/substvars</tt> contains variable substitutions to
+ be used; variables can also be set directly from
<tt>debian/rules</tt> using the <tt>-V</tt> option to the
- source packaging commands, and certain predefined
- variables are available.
+ source packaging commands, and certain predefined variables
+ are also available.
</p>
<p>
- The is usually generated and modified dynamically by
- <tt>debian/rules</tt> targets; in this case it must be
- removed by the <prgn>clean</prgn> target.
+ The <tt>debian/substvars</tt> file is usually generated and
+ modified dynamically by <tt>debian/rules</tt> targets; in
+ this case it must be removed by the <prgn>clean</prgn>
+ target.
</p>
<p>
</p>
<p>
- <prgn>dpkg-gencontrol</prgn> adds an entry to this file
- for the <tt>.deb</tt> file that will be created by
- <prgn>dpkg-deb</prgn> from the control file that it
- generates, so for most packages all that needs to be done
- with this file is to delete it in <prgn>clean</prgn>.
+ When <prgn>dpkg-gencontrol</prgn> is run for a binary
+ package, it adds an entry to <tt>debian/files</tt> for the
+ <tt>.deb</tt> file that will be created when <tt>dpkg-deb
+ --build</tt> is run for that binary package. So for most
+ packages all that needs to be done with this file is to
+ delete it in the <prgn>clean</prgn> target.
</p>
<p>
packages, but only when extracting
them.
</p>
- </footnote>
- <footnote>
<p>
Hard links may be permitted at some point in the
future, but would require a fair amount of
</p>
<p>
- These scripts should be the files <tt>preinst</tt>,
- <tt>postinst</tt>, <tt>prerm</tt> and <tt>postrm</tt> in the
+ 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
+ files; if they are scripts (which is recommended), they must
start with the usual <tt>#!</tt> convention. They should be
readable and executable by anyone, and not world-writable.
</p>
well.
</p>
- <p>
- It is necessary for the error recovery procedures that the
- scripts be idempotent: i.e., invoking the same script several
- times in the same situation should do no harm. If the first
- call failed, or aborted half way through for some reason,
- the second call should merely do the things that were left
- undone the first time, if any, and exit with a success
- status.
- </p>
-
<p>
When a package is upgraded a combination of the scripts from
- the old and new packages is called in amongst the other
- steps of the upgrade procedure. If your scripts are going
- to be at all complicated you need to be aware of this, and
- may need to check the arguments to your scripts.
+ the old and new packages is called during the upgrade
+ procedure. If your scripts are going to be at all
+ complicated you need to be aware of this, and may need to
+ check the arguments to your scripts.
</p>
<p>
<prgn>postrm</prgn> afterwards.
</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>,
+ <p>
+ Programs called from maintainer scripts should not normally
+ have a path prepended to them. Before installation is
+ started, the package management system checks to see if the
+ programs <prgn>ldconfig</prgn>,
<prgn>start-stop-daemon</prgn>, <prgn>install-info</prgn>,
and <prgn>update-rc.d</prgn> can be found via the
<tt>PATH</tt> environment variable. Those programs, and any
- other program that one would expect to on the <tt>PATH</tt>,
- should thus be invoked without an absolute
+ other program that one would expect to be on the
+ <tt>PATH</tt>, should thus be invoked without an absolute
pathname. Maintainer scripts should also not reset the
- <tt>PATH</tt>, though they might choose to modify it by pre-
- or appending package-specific directories. These
+ <tt>PATH</tt>, though they might choose to modify it by
+ prepending or appending package-specific directories. These
considerations really apply to all shell scripts.</p>
</sect>
+
<sect>
<heading>Maintainer scripts Idempotency</heading>
<p>
- It is very important to make maintainer scripts
- idempotent.
- <footnote>
+ It is necessary for the error recovery procedures that the
+ scripts be idempotent. This means that if it is run
+ successfully, and then it is called again, it doesn't bomb
+ out or cause any harm, but just ensures that everything is
+ the way it ought to be. If the first call failed, or
+ aborted half way through for some reason, the second call
+ should merely do the things that were left undone the first
+ time, if any, and exit with a success status if everything
+ is OK.
+ <footnote>
<p>
- That means that if it runs successfully or fails
- and then you call it again it doesn't bomb out,
- but just ensures that everything is the way it
- ought to be.
+ This is so that if an error occurs, the user interrupts
+ <prgn>dpkg</prgn> or some other unforeseen circumstance
+ happens you don't leave the user with a badly-broken
+ package when <prgn>dpkg</prgn> attempts to repeat the
+ action.
</p>
- </footnote> This is so that if an error occurs, the
- user interrupts <prgn>dpkg</prgn> or some other
- unforeseen circumstance happens you don't leave the
- user with a badly-broken package.
+ </footnote>
</p>
</sect>
+
<sect>
<heading>Controlling terminal for maintainer scripts</heading>
</item>
<item>
<p><var>old-postinst</var> <tt>abort-upgrade</tt>
- <var>new version</var></p>
+ <var>new-version</var></p>
</item>
<item>
<p><var>conflictor's-postinst</var> <tt>abort-remove</tt>
The procedure on installation/upgrade/overwrite/disappear
(i.e., when running <tt>dpkg --unpack</tt>, or the unpack
stage of <tt>dpkg --install</tt>) is as follows. In each
- case if an error occurs the actions are, in general, run
- backwards - this means that the maintainer scripts are run
- with different arguments in reverse order. These are the
- `error unwind' calls listed below.
+ case, if a major error occurs (unless listed below) the
+ actions are, in general, run backwards - this means that the
+ maintainer scripts are run with different arguments in
+ reverse order. These are the `error unwind' calls listed
+ below.
<enumlist>
<item>
<item>
<p>If a version of the package is already
installed, call
- <example>
- <var>old-prerm</var> upgrade <var>new-version</var>
+ <example compact="compact">
+<var>old-prerm</var> upgrade <var>new-version</var>
</example></p>
</item>
<item>
<p>
If the script runs but exits with a non-zero
exit status, <prgn>dpkg</prgn> will attempt:
- <example>
- <var>new-prerm</var> failed-upgrade <var>old-version</var>
+ <example compact="compact">
+<var>new-prerm</var> failed-upgrade <var>old-version</var>
</example>
Error unwind, for both the above cases:
- <example>
- <var>old-postinst</var> abort-upgrade <var>new-version</var>
+ <example compact="compact">
+<var>old-postinst</var> abort-upgrade <var>new-version</var>
</example>
</p>
</item>
If any packages depended on that conflicting
package and <tt>--auto-deconfigure</tt> is
specified, call, for each such package:
- <example>
- <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 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>
- <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 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
</item>
<item>
<p>To prepare for removal of the conflicting package, call:
- <example>
- <var>conflictor's-prerm</var> remove in-favour <var>package</var> <var>new-version</var>
+ <example compact="compact">
+<var>conflictor's-prerm</var> remove \
+ in-favour <var>package</var> <var>new-version</var>
</example>
Error unwind:
- <example>
- <var>conflictor's-postinst</var> abort-remove \
- in-favour <var>package</var> <var>new-version</var>
+ <example compact="compact">
+<var>conflictor's-postinst</var> abort-remove \
+ in-favour <var>package</var> <var>new-version</var>
</example>
</p>
</item>
<enumlist>
<item>
<p>If the package is being upgraded, call:
- <example>
- <var>new-preinst</var> upgrade <var>old-version</var>
+ <example compact="compact">
+<var>new-preinst</var> upgrade <var>old-version</var>
</example></p>
</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>
- <var>new-preinst</var> install <var>old-version</var>
+ <example compact="compact">
+<var>new-preinst</var> install <var>old-version</var>
</example></p>
<item>
<p>Otherwise (i.e., the package was completely purged):
- <example>
- <var>new-preinst</var> install
+ <example compact="compact">
+<var>new-preinst</var> install
</example>
- Error unwind versions, respectively:
- <example>
- <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
+ 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>
</p>
</item>
The new package's files are unpacked, overwriting any
that may be on the system already, for example any
from the old version of the same package or from
- another package (backups of the old files are left
- around, and if anything goes wrong the package
+ another package. Backups of the old files are kept
+ temporarily, and if anything goes wrong the package
management system will attempt to put them back as
- part of the error unwind).
+ part of the error unwind.
</p>
<p>
It is an error for a package to contains files which
are on the system in another package, unless
<tt>Replaces</tt> is used (see <ref id="replaces">).
- Currently the <tt>--force-overwrite</tt> flag is
+ <!--
+ The following paragraph is not currently the case:
+ Currently the <tt>- - force-overwrite</tt> flag is
enabled, downgrading it to a warning, but this may not
always be the case.
+ -->
</p>
<p>
<p>
Packages which overwrite each other's files produce
- behavior which though deterministic is hard for the
+ behavior which, though deterministic, is hard for the
system administrator to understand. It can easily
lead to `missing' programs if, for example, a package
is installed which overwrites a file from another
</p>
<p>
- A directory will never be replaced by a symbolic links
+ A directory will never be replaced by a symbolic link
to a directory or vice versa; instead, the existing
state (symlink or not) will be left alone and
<prgn>dpkg</prgn> will follow the symlink if there is
<p><enumlist>
<item>
<p>If the package is being upgraded, call
- <example>
- <var>old-postrm</var> upgrade <var>new-version</var>
+ <example compact="compact">
+<var>old-postrm</var> upgrade <var>new-version</var>
</example></p>
</item>
<item>
<p>If this fails, <prgn>dpkg</prgn> will attempt:
- <example>
- <var>new-postrm</var> failed-upgrade <var>old-version</var>
+ <example compact="compact">
+<var>new-postrm</var> failed-upgrade <var>old-version</var>
</example>
Error unwind, for both cases:
- <example>
- <var>old-preinst</var> abort-upgrade <var>new-version</var>
+ <example compact="compact">
+<var>old-preinst</var> abort-upgrade <var>new-version</var>
</example>
</p>
</item>
<p>Any packages all of whose files have been overwritten during the
installation, and which aren't required for
dependencies, are considered to have been removed.
- For each such package,
+ For each such package
<enumlist>
<item>
<p><prgn>dpkg</prgn> calls:
- <example>
- <var>disappearer's-postrm</var> disappear \
- <var>overwriter</var> <var>overwriter-version</var>
+ <example compact="compact">
+<var>disappearer's-postrm</var> disappear \
+ <var>overwriter</var> <var>overwriter-version</var>
</example>
</p>
</item>
<item>
<p>
The new package's status is now sane, and recorded as
- `unpacked'. Here is another point of no return - if
- the conflicting package's removal fails we do not
- unwind the rest of the installation; the conflicting
- package is left in a half-removed limbo.
+ `unpacked'.
+ </p>
+
+ <p>
+ Here is another point of no return - if the
+ conflicting package's removal fails we do not unwind
+ the rest of the installation; the conflicting package
+ is left in a half-removed limbo.
</p>
</item>
+
<item>
<p>
If there was a conflicting package we go and do the
<p>
When we configure a package (this happens with <tt>dpkg
--install</tt>, or with <tt>--configure</tt>), we first
- update the conffiles and then call:
- <example>
- <var>postinst</var> configure <var>most-recently-configured-version</var>
+ update any <tt>conffile</tt>s and then call:
+ <example compact="compact">
+<var>postinst</var> configure <var>most-recently-configured-version</var>
</example>
</p>
<enumlist>
<item>
<p>
- <example>
- <var>prerm</var> remove
+ <example compact="compact">
+<var>prerm</var> remove
</example>
</p>
</item>
<item>
<p>
- The package's files are removed (except conffiles).
+ The package's files are removed (except <tt>conffile</tt>s).
</p>
</item>
<item>
- <p><example>
- <var>postrm</var> remove
- </example></p>
+ <p>
+ <example compact="compact">
+<var>postrm</var> remove
+ </example>
+ </p>
</item>
<item>
- <p>All the maintainer scripts except the postrm are removed.
+ <p>
+ All the maintainer scripts except the <prgn>postrm</prgn>
+ are removed.
</p>
<p>
If we aren't purging the package we stop here. Note
- that packages which have no postrm and no conffiles
- are automatically purged when removed, as there is no
- difference except for the <prgn>dpkg</prgn>
- status.</p>
+ that packages which have no <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>
<p>
<tt>.dpkg-{old,new,tmp}</tt>, etc.) are removed.</p>
</item>
<item>
- <p><example>
- <var>postrm</var> purge
- </example></p>
+ <p>
+ <example compact="compact">
+<var>postrm</var> purge
+ </example>
+ </p>
</item>
<item>
<p>The package's file list is removed.</p>
</item>
</enumlist>
No attempt is made to unwind after errors during
- removal.</p>
+ removal.
+ </p>
</sect>
</chapt>
<chapt id="relationships"><heading>Declaring relationships between
- packages </heading>
+ packages</heading>
<p>
Packages can declare in their control file that they have
</p>
<p>
- This is done using the <tt>Depends</tt>, <tt>Recommends</tt>,
- <tt>Suggests</tt>, <tt>Enhances</tt>, <tt>Conflicts</tt>,
- <tt>Provides</tt> and <tt>Replaces</tt> control file fields.
+ This is done using the <tt>Depends</tt>, <tt>Pre-Depends</tt>,
+ <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
+ <tt>Conflicts</tt>, <tt>Provides</tt> and <tt>Replaces</tt>
+ control file fields.
</p>
<p>
<p>
This is done using the <tt>Build-Depends</tt>,
- <tt>Build-Depends-Indep</tt>, <tt>Build-Conflicts</tt>, and
+ <tt>Build-Depends-Indep</tt>, <tt>Build-Conflicts</tt> and
<tt>Build-Conflicts-Indep</tt> control file fields.
</p>
control file fields of the package, which declare
dependencies on other packages, the package names listed may
also include lists of alternative package names, separated
- by vertical bar symbols <tt>|</tt> (pipe symbols). In such
- a case, the presence of any one of the alternative packages
- is installed, that part of the dependency is considered to
- be satisfied.
+ by vertical bar (pipe) symbols <tt>|</tt>. In such a case,
+ if any one of the alternative packages is installed, that
+ part of the dependency is considered to be satisfied.
</p>
<p>
- All the fields except <tt>Provides</tt> may restrict their
- applicability to particular versions of each named package.
- This is done in parentheses after each individual package
- name; the parentheses should contain a relation from the
- list below followed by a version number, in the format
+ All of the fields except for <tt>Provides</tt> may restrict
+ their applicability to particular versions of each named
+ package. This is done in parentheses after each individual
+ package name; the parentheses should contain a relation from
+ the list below followed by a version number, in the format
described in <ref id="versions">.
</p>
The relations allowed are <tt><<</tt>, <tt><=</tt>,
<tt>=</tt>, <tt>>=</tt> and <tt>>></tt> for
strictly earlier, earlier or equal, exactly equal, later or
- equal and strictly later, respectively. The forms
- <tt><</tt> and <tt>></tt> were used to mean
+ equal and strictly later, respectively. The deprecated
+ forms <tt><</tt> and <tt>></tt> were used to mean
earlier/later or equal, rather than strictly earlier/later,
so they should not appear in new packages (though
<prgn>dpkg</prgn> still supports them).
<p>
Whitespace may appear at any point in the version
- specification, and must appear where it's necessary to
+ specification subject to the rules in <ref
+ id="controlsyntax">, and must appear where it's necessary to
disambiguate; it is not otherwise significant. For
consistency and in case of future changes to
<prgn>dpkg</prgn> it is recommended that a single space be
used after a version relationship and before a version
- number; it is usual also to put a single space after each
- comma, on either side of each vertical bar, and before each
- open parenthesis.
+ number; it is also conventional to put a single space after
+ each comma, on either side of each vertical bar, and before
+ each open parenthesis.
</p>
<p>
- For example:
- <example>
- Package: metamail
- Version: 2.7-3
- Depends: libc5 (>= 5.2.18-4), mime-support, csh | tcsh
+ 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>
(<tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
<tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>)
may be restricted to a certain set of architectures. This
- is done in brackets after each individual package name and
+ is indicated in brackets after each individual package name and
the optional version specification. The brackets enclose a
list of Debian architecture names separated by whitespace.
Exclamation marks may be prepended to each of the names.
<p>
For example:
- <example>
- Source: glibc
- Build-Depends-Indep: texinfo
- Build-Depends: kernel-headers-2.2.10 [!hurd-i386],
- hurd-dev [hurd-i386], gnumach-dev [hurd-i386]
+ <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>
</sect>
</p>
<p>
- All but <tt>Pre-Depends</tt> and <tt>Conflicts</tt>
- (discussed below) take effect <em>only</em> when a package
- is to be configured. They do not prevent a package being on
- the system in an unconfigured state while its dependencies
- are unsatisfied, and it is possible to replace a package
- whose dependencies are satisfied and which is properly
- installed with a different version whose dependencies are
- not and cannot be satisfied; when this is done the depending
- package will be left unconfigured (since attempts to
- configure it will give errors) and will not function
- properly.
+ A <tt>Depends</tt> field takes effect <em>only</em> when a
+ package is to be configured. It does not prevent a package
+ being on the system in an unconfigured state while its
+ dependencies are unsatisfied, and it is possible to replace
+ a package whose dependencies are satisfied and which is
+ properly installed with a different version whose
+ dependencies are not and cannot be satisfied; when this is
+ done the depending package will be left unconfigured (since
+ attempts to configure it will give errors) and will not
+ function properly. If it is necessary, a
+ <tt>Pre-Depends</tt> field can be used, which has a partial
+ effect even when a package is being unpacked, as explained
+ in detail below. (The other three dependency fields,
+ <tt>Recommends</tt>, <tt>Suggests</tt> and
+ <tt>Enhances</tt>, are only used by the various front-ends
+ to <prgn>dpkg</prgn> such as <prgn>dselect</prgn>.)
</p>
<p>
</p>
<p>
- Thus <tt>Depends</tt> allows package maintainers to impose
- an order in which packages should be configured.
+ The <tt>Depends</tt> field thus allows package maintainers
+ to impose an order in which packages should be configured.
+ </p>
+
+ <p>
+ The meaning of the five dependency fields is as follows:
<taglist>
<tag><tt>Depends</tt></tag>
<item>
- <p>This declares an absolute dependency.
+ <p>
+ This declares an absolute dependency. A package will
+ not be configured unless all of the packages listed in
+ its <tt>Depends</tt> field have been correctly
+ configured.
</p>
<p>
The <tt>Depends</tt> field should be used if the
depended-on package is required for the depending
package to provide a significant amount of
- functionality.</p>
+ functionality.
+ </p>
+ <p>
+ The <tt>Depends</tt> field should also be used if the
+ <prgn>postinst</prgn>, <prgn>prerm</prgn> or
+ <prgn>postrm</prgn> scripts require the package to be
+ present in order to run. Note, however, that the
+ <prgn>postrm</prgn> cannot rely on any non-essential
+ packages to be present during the <tt>purge</tt>
+ phase.
</item>
<tag><tt>Recommends</tt></tag>
also forces <prgn>dpkg</prgn> to complete installation
of the packages named before even starting the
installation of the package which declares the
- Pre-dependency.
+ pre-dependency, as follows:
</p>
<p>
- <tt>Pre-Depends</tt> should be used sparingly,
- preferably only by packages whose premature upgrade or
- installation would hamper the ability of the system to
- continue with any upgrade that might be in progress.
+ When a package declaring a pre-dependency is about to
+ be <em>unpacked</em> the pre-dependency can be
+ satisfied if the depended-on package is either fully
+ configured, <em>or even if</em> the depended-on
+ package(s) are only unpacked or half-configured,
+ provided that they have been configured correctly at
+ some point in the past (and not removed or partially
+ removed since). In this case, both the
+ previously-configured and currently unpacked or
+ half-configured versions must satisfy any version
+ clause in the <tt>Pre-Depends</tt> field.
</p>
<p>
- When the package declaring it is being configured, a
- <tt>Pre-Dependency</tt> will be considered satisfied
- only if the depending package has been correctly
- configured, just as if an ordinary <tt>Depends</tt>
- had been used.
+ When the package declaring a pre-dependency is about
+ to be <em>configured</em>, the pre-dependency will be
+ treated as a normal <tt>Depends</tt>, that is, it will
+ be considered satisfied only if the depended-on
+ package has been correctly configured.
</p>
<p>
- However, when a package declaring a Pre-dependency is
- being unpacked the predependency can be satisfied even
- if the depended-on package(s) are only unpacked or
- half-configured, provided that they have been
- configured correctly at some point in the past (and
- not removed or partially removed since). In this case
- both the previously-configured and currently unpacked
- or half-configured versions must satisfy any version
- clause in the <tt>Pre-Depends</tt> field.
+ <tt>Pre-Depends</tt> should be used sparingly,
+ preferably only by packages whose premature upgrade or
+ installation would hamper the ability of the system to
+ continue with any upgrade that might be in progress.
</p>
+
+ <p>
+ <tt>Pre-Depends</tt> are also required if the
+ <prgn>preinst</prgn> script depends on the named
+ package. It is best to avoid this situation if
+ possible.
</item>
</taglist>
</p>
</p>
- <sect id="conflicts"><heading>Alternative binary packages -
- <tt>Conflicts</tt> and <tt>Replaces</tt>
- </heading>
+ <sect id="conflicts"><heading>Conflicting binary packages -
+ <tt>Conflicts</tt></heading>
<p>
When one binary package declares a conflict with another
- <prgn>dpkg</prgn> will refuse to allow them to be installed
- on the system at the same time.
+ using a <tt>Conflicts</tt> field, <prgn>dpkg</prgn> will
+ refuse to allow them to be installed on the system at the
+ same time.
</p>
<p>
If one package is to be installed, the other must be removed
first - if the package being installed is marked as
- replacing (<ref id="replaces">) the one on the system, or
- the one on the system is marked as deselected, or both
+ replacing (see <ref id="replaces">) the one on the system,
+ or the one on the system is marked as deselected, or both
packages are marked <tt>Essential</tt>, then
<prgn>dpkg</prgn> will automatically remove the package
which is causing the conflict, otherwise it will halt the
- installation of the new package with an error. This
- mechanism specifically doesn't work when the installed
- package is <tt>Essential</tt>, but the new package is not.
+ installation of the new package with an error. This
+ mechanism is specifically designed to produce an error when
+ the installed package is <tt>Essential</tt>, but the new
+ package is not.
</p>
-
<p>
A package will not cause a conflict merely because its
configuration files are still installed; it must be at least
prevent their installation, and allows a package to conflict
with others providing a replacement for it. You use this
feature when you want the package in question to be the only
- package providing something.
+ package providing some feature.
</p>
<p>
<p>
As well as the names of actual (`concrete') packages, the
package relationship fields <tt>Depends</tt>,
+ <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
+ <tt>Pre-Depends</tt>, <tt>Conflicts</tt>,
<tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
- <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Conflicts</tt>,
- <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt> may
- mention virtual packages.
+ <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>
+ may mention `virtual packages'.
</p>
<p>
- A virtual package is one which appears in the
+ A <em>virtual package</em> is one which appears in the
<tt>Provides</tt> control file field of another package.
The effect is as if the package(s) which provide a
particular virtual package name had been listed by name
caused) by either the real package or any of the virtual
packages which provide it. This is so that, for example,
supposing we have
- <example>
- Package: vm
- Depends: emacs
+ <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 someone else releases an xemacs package they can say
- <example>
- Package: xemacs
- Provides: emacs
- </example> and all will work in the interim (until a purely
- virtual package name is decided on and the <tt>emacs</tt>
- and <tt>vm</tt> packages are changed to use it).
+ and the <tt>bar-plus</tt> package will now also satisfy the
+ dependency for the <tt>foo</tt> package.
</p>
<p>
</p>
<p>
- If you want to specify which of a set of real packages should be the
- default to satisfy a particular dependency on a virtual package, you
- should list the real package as an alternative before the virtual.
+ If you want to specify which of a set of real packages
+ should be the default to satisfy a particular dependency on
+ a virtual package, you should list the real package as an
+ alternative before the virtual one.
</p>
</sect>
- <sect id="replaces"><heading><tt>Replaces</tt> - overwriting
- files and replacing packages
- </heading>
-
- <p>
- The <tt>Replaces</tt> control file field has two purposes,
- which come into play in different situations.
- </p>
+ <sect id="replaces"><heading>Overwriting files and replacing
+ packages - <tt>Replaces</tt></heading>
<p>
- Virtual packages (<ref id="virtual">) are not considered
- when looking at a <tt>Replaces</tt> field - the packages
- declared as being replaced must be mentioned by their real
- names.
+ The <tt>Replaces</tt> control file field has two distinct
+ purposes, which come into play in different situations.
</p>
- <sect1><heading>Overwriting files in other packages
- </heading>
+ <sect1><heading>Overwriting files in other packages</heading>
<p>
Firstly, as mentioned before, it is usually an error for a
package to contain files which are on the system in
- another package, though currently the
- <tt>--force-overwrite</tt> flag is enabled by default,
- downgrading the error to a warning,
+ another package.
</p>
<p>
- If the overwriting package declares that it replaces the
- one containing the file being overwritten then
- <prgn>dpkg</prgn> will proceed, and replace the file from
- the old package with that from the new. The file will no
- longer be listed as `owned' by the old package.
+ However, if the overwriting package declares that it
+ <tt>Replaces</tt> the one containing the file being
+ overwritten, then <prgn>dpkg</prgn> will replace the file
+ from the old package with that from the new. The file
+ will no longer be listed as `owned' by the old package.
</p>
<p>
If a package is completely replaced in this way, so that
<prgn>dpkg</prgn> does not know of any files it still
- contains, it is considered to have disappeared. It will
+ contains, it is considered to have `disappeared'. It will
be marked as not wanted on the system (selected for
- removal) and not installed. Any conffiles details noted
- in the package will be ignored, as they will have been
- taken over by the replacing package(s). The package's
- <prgn>postrm</prgn> script will be run to allow the
- package to do any final cleanup required. See <ref
- id="mscriptsinstact">.
+ removal) and not installed. Any <tt>conffile</tt>s
+ details noted for the package will be ignored, as they
+ will have been taken over by the overwriting package. The
+ package's <prgn>postrm</prgn> script will be run with a
+ special argument to allow the package to do any final
+ cleanup required. See <ref id="mscriptsinstact">.
+ </p>
+
+ <p>
+ If an installed package, <tt>foo</tt> say, declares that
+ it replaces another, <tt>bar</tt>, and an attempt is made
+ to install <tt>bar</tt>, <prgn>dpkg</prgn> will discard
+ files in the <tt>bar</tt> package which would overwrite
+ those already present in <tt>foo</tt>. This is so that
+ you can install an older version of a package without
+ problems.
</p>
<p>
- In the future <prgn>dpkg</prgn> will discard files which
- would overwrite those from an already installed package
- which declares that it replaces the package being
- installed. This is so that you can install an older
- version of a package without problems.
+ For this usage of <tt>Replaces</tt>, virtual packages (see
+ <ref id="virtual">) are not considered when looking at a
+ <tt>Replaces</tt> field - the packages declared as being
+ replaced must be mentioned by their real names.
</p>
<p>
- This usage of <tt>Replaces</tt> only takes effect when
- both packages are at least partially on the system at
- once, so that it can only happen if they do not conflict
- or if the conflict has been overridden.</p>
+ Furthermore, this usage of <tt>Replaces</tt> only takes
+ effect when both packages are at least partially on the
+ system at once, so that it can only happen if they do not
+ conflict or if the conflict has been overridden.
+ </p>
+
</sect1>
<sect1><heading>Replacing whole packages, forcing their
- removal
- </heading>
+ removal</heading>
<p>
Secondly, <tt>Replaces</tt> allows the packaging system to
resolve which package should be removed when there is a
conflict - see <ref id="conflicts">. This usage only
takes effect when the two packages <em>do</em> conflict,
- so that the two effects do not interfere with each other.
+ so that the two usages of this field do not interfere with
+ each other.
</p>
+
+ <p>
+ In this situation, the package declared as being replaced
+ can be a virtual package, so for example, all mail
+ transport agents (MTAs) would have the following fields in
+ their control files:
+ <example 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>
<p>
A source package may declare a dependency or a conflict on a
- binary package. This is done with the control file fields
- <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
- <tt>Build-Conflicts</tt>, and
- <tt>Build-Conflicts-Indep</tt>. Their semantics are that
- the dependencies and conflicts they define must be satisfied
- (as defined earlier for binary packages), when one of the
- targets in <tt>debian/rules</tt> that the particular field
- applies to is invoked.
+ binary package, indicating which packages are required to be
+ present on the system in order to build the binary packages
+ from the source package. This is done with the control file
+ fields <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
+ <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>.
+ The dependencies and conflicts they define must be satisfied
+ (as defined earlier for binary packages) in order to invoke
+ the targets in <tt>debian/rules</tt>, as follows:
<taglist>
<tag><tt>Build-Depends</tt>, <tt>Build-Conflicts</tt></tag>
<item>
<p>
The <tt>Build-Depends</tt> and
- <tt>Build-Conflicts</tt> fields apply to the targets
+ <tt>Build-Conflicts</tt> fields must be satisfied when
+ any of the following targets is invoked:
<tt>build</tt>, <tt>binary</tt>, <tt>binary-arch</tt>
and <tt>binary-indep</tt>.
</p>
<item>
<p>
The <tt>Build-Depends-Indep</tt> and
- <tt>Build-Conflicts-Indep</tt> fields apply to the
- targets <tt>binary</tt> and <tt>binary-indep</tt>.
+ <tt>Build-Conflicts-Indep</tt> fields must be
+ satisfied when any of the following targets is
+ invoked: <tt>binary</tt> and <tt>binary-indep</tt>.
</p>
</item>
</taglist>
</heading>
<p>
- <prgn>dpkg</prgn> can do a certain amount of automatic
- handling of package configuration files.
- </p>
-
- <p>
- Whether this mechanism is appropriate depends on a number of
- factors, but basically there are two approaches to any
- particular configuration file.
- </p>
-
- <p>
- The easy method is to ship a best-effort configuration in the
- package, and use <prgn>dpkg</prgn>'s conffile mechanism to
- handle updates. If the user is unlikely to want to edit the
- file, but you need them to be able to without losing their
- changes, and a new package with a changed version of the file
- is only released infrequently, this is a good approach.
+ This chapter has been superseded by <ref id="config files">.
</p>
- <p>
- The hard method is to build the configuration file from
- scratch in the <prgn>postinst</prgn> script, and to take the
- responsibility for fixing any mistakes made in earlier
- versions of the package automatically. This will be
- appropriate if the file is likely to need to be different on
- each system.
- </p>
-
- <chapt id="sharedlibs"><heading>Shared libraries
- </heading>
+ <chapt id="sharedlibs"><heading>Shared libraries</heading>
<p>
Packages containing shared libraries must be constructed with
a little care to make sure that the shared library is always
available. This is especially important for packages whose
- shared libraries are vitally important, such as the libc.
+ shared libraries are vitally important, such as the C library
+ (currently <tt>libc6</tt>).
</p>
<p>
- Firstly, your package should install the shared libraries
- under their normal names. For example, the
- <prgn>libgdbm1</prgn> package should install
- <tt>libgdbm.so.1.7.3</tt> as
+ Firstly, the package should install the shared libraries under
+ their normal names. For example, the <tt>libgdbmg1</tt>
+ package should install <tt>libgdbm.so.1.7.3</tt> as
<tt>/usr/lib/libgdbm.so.1.7.3</tt>. The files should not be
- renamed or re-linked by any prerm or postrm scripts;
- <prgn>dpkg</prgn> will take care of renaming things safely
- without affecting running programs, and attempts to interfere
- with this are likely to lead to problems.
+ renamed or re-linked by any <prgn>prerm</prgn> or
+ <prgn>postrm</prgn> scripts; <prgn>dpkg</prgn> will take care
+ of renaming things safely without affecting running programs,
+ and attempts to interfere with this are likely to lead to
+ problems.
</p>
<p>
- Secondly, your package should include the symlink that
+ Secondly, the package should include the symbolic link that
<prgn>ldconfig</prgn> would create for the shared libraries.
- For example, the <prgn>libgdbm1</prgn> package should include
- a symlink from <tt>/usr/lib/libgdbm.so.1</tt> to
- <tt>libgdbm.so.1.7.3</tt>. This is needed so that
- <prgn>ld.so</prgn> can find the library in between the time
- <prgn>dpkg</prgn> installs it and <prgn>ldconfig</prgn> is run
- in the <prgn>postinst</prgn> script. Furthermore, older
- versions of the package management system required the library
- must be placed before the symlink pointing to it in the
- <tt>.deb</tt> file. This is so that by the time
- <prgn>dpkg</prgn> comes to install the symlink (overwriting
- the previous symlink pointing at an older version of the
- library) the new shared library is already in place.
- Unfortunately, this was not not always possible, since it
- highly depends on the behavior of the file system. Some
- file systems (such as reiserfs) will reorder the files so it
- doesn't matter in what order you create them. Starting with
- release <tt>1.7.0</tt> <prgn>dpkg</prgn> will reorder the
- files itself when building a package.
+ For example, the <prgn>libgdbmg1</prgn> package should include
+ a symbolic link from <tt>/usr/lib/libgdbm.so.1</tt> to
+ <tt>libgdbm.so.1.7.3</tt>. This is needed so that the dynamic
+ linker (for example <prgn>ld.so</prgn> or
+ <prgn>ld-linux.so.*</prgn>) can find the library between the
+ time that <prgn>dpkg</prgn> installs it and the time that
+ <prgn>ldconfig</prgn> is run in the <prgn>postinst</prgn>
+ script.
+ <footnote>
+ <p>
+ The package management system requires the library to be
+ placed before the symbolic link pointing to it in the
+ <tt>.deb</tt> file. This is so that when
+ <prgn>dpkg</prgn> comes to install the symlink
+ (overwriting the previous symlink pointing at an older
+ version of the library), the new shared library is already
+ in place. In the past, this was achieved by creating the
+ library in the temporary packaging directory before
+ creating the symlink. Unfortunately, this was not always
+ effective, since the building of the tar file in the
+ <tt>.deb</tt> depended on the behavior of the underlying
+ file system. Some file systems (such as reiserfs) reorder
+ the files so that the order of creation is forgotten.
+ Starting with release <tt>1.7.0</tt>, <prgn>dpkg</prgn>
+ will reorder the files itself as necessary when building a
+ package. Thus it is no longer important to concern
+ oneself with the order of file creation.
+ </p>
+ </footnote>
+ </p>
+
+ <p>
+ Thirdly, the associated development package should contain a
+ symlink for the shared library without a version number. For
+ example, the <tt>libgdbmg1-dev</tt> package should include a
+ symlink from <tt>/usr/lib/libgdbm.so</tt> to
+ <tt>libgdbm.so.1.7.3</tt>. This symlink is needed by the
+ linker (<prgn>ld</prgn>) when compiling packages, as it will
+ only look for <tt>libgdbm.so</tt> when compiling dynamically.
</p>
<p>
- Thirdly, the development package should contain a symlink for
- the shared library without a version number. For example, the
- <tt>libgdbm1-dev</tt> package should include a symlink from
- <tt>/usr/lib/libgdm.so</tt> to <tt>libgdm.so.1.7.3</tt>. This
- symlink is needed by <prgn>ld</prgn> when compiling packages
- as it will only look for <tt>libgdm.so</tt> and
- <tt>libgdm.a</tt> when compiling dynamically or statically,
- respectively.
+ Any package installing shared libraries in one of the default
+ library directories of the dynamic linker (which are currently
+ <tt>/usr/lib</tt> and <tt>/lib</tt>) or a directory that is
+ listed in <tt>/etc/ld.so.conf</tt>
+ <footnote>
+ <p>
+ These are currently
+ <list compact="compact">
+ <item><p>/usr/X11R6/lib/Xaw3d</p></item>
+ <item><p>/usr/local/lib</p></item>
+ <item><p>/usr/lib/libc5-compat</p></item>
+ <item><p>/lib/libc5-compat</p></item>
+ <item><p>/usr/X11R6/lib</p></item>
+ </list>
+ </p>
+ </footnote>
+ must call <prgn>ldconfig</prgn> in its <prgn>postinst</prgn>
+ script if and only if the first argument is <tt>configure</tt>
+ and should call it in the <prgn>postrm</prgn> script if the
+ first argument is <tt>remove</tt>.
</p>
<p>
- Any package installing shared libraries in a directory that's listed
- in <tt>/etc/ld.so.conf</tt> or in one of the default library
- directories of <prgn>ld.so</prgn> (currently, these are <tt>/usr/lib</tt>
- and <tt>/lib</tt>) must call <prgn>ldconfig</prgn> in its <prgn>postinst</prgn>
- script if and only if the first argument is `configure'. However, it
- is important not to call <prgn>ldconfig</prgn> in the postrm or preinst
- scripts in the case where the package is being upgraded (see <ref
- id="unpackphase">), as <prgn>ldconfig</prgn> will see the temporary names
- that <prgn>dpkg</prgn> uses for the files while it is
+ However, <prgn>postrm</prgn> and <prgn>preinst</prgn> scripts
+ <em>must not</em> call <prgn>ldconfig</prgn> in the case where
+ the package is being upgraded (see <ref id="unpackphase"> for
+ details), as <prgn>ldconfig</prgn> will see the temporary
+ names that <prgn>dpkg</prgn> uses for the files while it is
installing them and will make the shared library links point
to them, just before <prgn>dpkg</prgn> continues the
- installation and removes the links!
+ installation and renames the temporary files!
</p>
- <sect id="shlibs"><heading>The <tt>shlibs</tt> File Format
+ <sect>
+ <heading>Handling shared library dependencies - 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 <tt>shlibs</tt> files.
+ </p>
+
+ <p>
+ Thus, when a package is built which contains any shared
+ libraries, it must provide a <tt>shlibs</tt> 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> 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 needs to 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>
+ </sect>
+
+ <sect><heading>The <tt>shlibs</tt> files present on the system
</heading>
<p>
- This file is for use by <prgn>dpkg-shlibdeps</prgn> and is
- required when your package provides shared libraries.
+ 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>
+ <item>
+ <p><tt>debian/shlibs.local</tt></p>
+ <p>
+ This lists overrides for this package. Its use is
+ described below (see <ref id="shlibslocal">).
+ </p>
+ </item>
+
+ <item>
+ <p><tt>/etc/dpkg/shlibs.override</tt></p>
+ <p>
+ This lists global overrides. This list is normally
+ empty. It is maintained by the local system
+ administrator.
+ </p>
+ </item>
+
+ <item>
+ <p><tt>DEBIAN/shlibs</tt> files in the `build directory'</p>
+ <p>
+ When packages are being built, any
+ <tt>debian/shlibs</tt> files are copied into the
+ control file area of the temporary build directory and
+ given the name <tt>shlibs</tt>. These files give
+ details of any shared libraries included in the
+ package.
+ <footnote>
+ <p>
+ An example may help here. Let us say that the
+ source package <tt>foo</tt> generates two binary
+ packages, <tt>libfoo2</tt> and
+ <tt>foo-runtime</tt>. When building the binary
+ packages, the two packages are created in the
+ directories <tt>debian/libfoo2</tt> and
+ <tt>debian/foo-runtime</tt> respectively.
+ (<tt>debian/tmp</tt> 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
+ <tt>debian/libfoo2/DEBIAN/shlibs</tt>, eventually
+ to become
+ <tt>/var/lib/dpkg/info/libfoo2.shlibs</tt>. Then
+ when <prgn>dpkg-shlibdeps</prgn> is run on the
+ executable
+ <tt>debian/foo-runtime/usr/bin/foo-prog</tt>, it
+ will examine the
+ <tt>debian/libfoo2/DEBIAN/shlibs</tt> 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.
+ </p>
+ </footnote>
+ </p>
+ </item>
+
+ <item>
+ <p><tt>/var/lib/dpkg/info/*.shlibs</tt></p>
+ <p>
+ These are the <tt>shlibs</tt> files corresponding to
+ all of the packages installed on the system, and are
+ maintained by the relevant package maintainers.
+ </p>
+ </item>
+
+ <item>
+ <p><tt>/etc/dpkg/shlibs.default</tt></p>
+ <p>
+ This file lists any shared libraries whose packages
+ have failed to provide correct <tt>shlibs</tt> files.
+ It was used when the <tt>shlibs</tt> setup was first
+ introduced, but it is now normally empty. It is
+ maintained by the <tt>dpkg</tt> maintainer.
+ </p>
+ </item>
+ </list>
+ </p>
+ </sect>
+
+ <sect>
+ <heading>How to use <prgn>dpkg-shlibdeps</prgn> and the
+ <tt>shlibs</tt> files</heading>
+
+ <p>
+ Put a call to <prgn>dpkg-shlibdeps</prgn> into your
+ <tt>debian/rules</tt> 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>
+ <p>
+ If you are using <tt>debhelper</tt>, the
+ <prgn>dh_shlibdeps</prgn> program will do this work for
+ you. It will also correctly handle multi-binary
+ packages.
+ </p>
+ </footnote>
+ </p>
+
+ <p>
+ This command puts the dependency information into the
+ <tt>debian/substvars</tt> 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
+ <tt>debian/shlibs.local</tt> file, as explained below (see
+ <ref id="shlibslocal">).
</p>
<p>
- Each line is of the form:
- <example>
- <var>library-name</var> <var>version-or-soname</var> <var>dependencies ...</var>
+ 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 <tt>substvars</tt> file.
+ For more details on this and other options, see <manref
+ name="dpkg-shlibdeps" section="1">.
+ </p>
+ </sect>
+
+ <sect id="shlibs"><heading>The <tt>shlibs</tt> File Format
+ </heading>
+
+ <p>
+ Each <tt>shlibs</tt> file has the same format. Lines
+ beginning with <tt>#</tt> are considered to be commments 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>
+ 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 <tt>/usr/lib/libz.so.1.1.3</tt>.
+ </p>
+
<p>
<var>library-name</var> is the name of the shared library,
- for example <tt>libc5</tt>.
+ in this case <tt>libz</tt>. (This must match the name part
+ of the soname, see below.)
</p>
<p>
- <var>version-or-soname</var> is the soname of the library -
- i.e., the thing that must exactly match for the library to be
- recognized by <prgn>ld.so</prgn>. Usually this is the major
- version number of the library.
+ <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>
+ <p>
+ This can be determined using the command
+ <example compact="compact">
+objdump -p /usr/lib/libz.so.1.1.3 | grep SONAME
+ </example>
+ </p>
+ </footnote>
+ The version part is the part which comes after
+ <tt>.so.</tt>, so in our case, it is <tt>1</tt>.
</p>
<p>
<var>dependencies</var> has the same syntax as a dependency
field in a binary package control file. It should give
- details of which package(s) are required to satisfy a binary
+ 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">.
+ package. See <ref id="depsyntax"> for details.
+ </p>
+
+ <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>
+ </sect>
+
+ <sect>
+ <heading>Providing a <tt>shlibs</tt> file</heading>
<p>
- For example, if the package <tt>foo</tt> contains
- <tt>libfoo.so.1.2.3</tt>, where the soname of the library is
- <tt>libfoo.so.1</tt>, and the first version of the package
- which contained a minor number of at least <tt>2.3</tt> was
- <var>1.2.3-1</var>, then the package's <var>shlibs</var>
- could say:
- <example>
- libfoo 1 foo (>= 1.2.3-1)
+ If your package provides a shared library, you should create
+ a <tt>shlibs</tt> file following the format described above.
+ It is usual to call this file <tt>debian/shlibs</tt> (but if
+ you have multiple binary packages, you might want to call it
+ <tt>debian/shlibs.<var>package</var></tt> instead). Then
+ let <tt>debian/rules</tt> 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
+ <tt>shlibs</tt> file in the control area directly from
+ <tt>debian/rules</tt> without using a <tt>debian/shlibs</tt>
+ file at all,
+ <footnote>
+ <p>
+ This is what <prgn>dh_makeshlibs</prgn> in the
+ <tt>debhelper</tt> suite does.
+ </p>
+ </footnote>
+ since the <tt>debian/shlibs</tt> file itself is ignored by
+ <prgn>dpkg-shlibdeps</prgn>.
</p>
<p>
- The version-specific dependency is to avoid warnings from
- <prgn>ld.so</prgn> about using older shared libraries with
- newer binaries.</p>
+ As <prgn>dpkg-shlibdeps</prgn> reads the
+ <tt>DEBIAN/shlibs</tt> files in all of the binary packages
+ being built from this source package, all of the
+ <tt>DEBIAN/shlibs</tt> files should be installed before
+ <prgn>dpkg-shlibdeps</prgn> is called on any of the binary
+ packages.
+ </p>
</sect>
- <sect><heading>Further Technical information on
- <tt>shlibs</tt></heading>
+ <sect id="shlibslocal">
+ <heading>Writing the <tt>debian/shlibs.local</tt> file</heading>
- <sect1><heading><em>What</em> are the <tt>shlibs</tt> files?
- </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 <tt>shlibs</tt> 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 <tt>*.shlibs</tt> file handling
+ <tt>libbar.so.1</tt> in <tt>/var/lib/dpkg/info/</tt>. 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
+ <tt>debian/shlibs.local</tt> to locally fix the problem.
+ Including the following line into your
+ <tt>debian/shlibs.local</tt> 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 <tt>shlibs</tt> file, you should remove this line
+ from your <tt>debian/shlibs.local</tt> 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>
+ </sect>
+ </chapt>
+
+ <chapt id="opersys"><heading>The Operating System</heading>
+
+ <sect>
+ <heading>Filesystem hierarchy</heading>
+
+
+ <sect1>
+ <heading>Filesystem Structure</heading>
<p>
- The <tt>debian/shlibs</tt> file provides a way of checking
- for shared library dependencies on packaged binaries.
- They are intended to be used by package maintainers to
- make their lives easier.
+ The location of all installed files and directories must
+ comply with the Filesystem Hierarchy Standard (FHS),
+ version 2.1. This 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 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 Daniel Quinlan, the FHS coordinator, at
+ <email>quinlan@pathname.com</email>.
</p>
+ </sect1>
+
+ <sect1>
+ <heading>Site-specific programs</heading>
<p>
- Other <tt>shlibs</tt> files that exist on a Debian system are
- <list>
- <item> <p><tt>/etc/dpkg/shlibs.default</tt></p></item>
- <item> <p><tt>/etc/dpkg/shlibs.override</tt></p></item>
- <item> <p><tt>/var/lib/dpkg/info/*.shlibs</tt></p></item>
- <item> <p><tt>debian/shlibs.local</tt></p></item>
- </list>
- These files are used by <prgn>dpkg-shlibdeps</prgn> when
- creating a binary package.</p>
- </sect1>
-
- <sect1><heading><em>How</em> does <prgn>dpkg-shlibdeps</prgn>
- work?
- </heading>
- <p>
- <prgn>dpkg-shlibdeps</prgn>
- determines the shared libraries directly
- <footnote>
- <p>
- It used to do this by calling <prgn>ldd</prgn>, but it
- now calls <prgn>objdump</prgn> to do this. This
- requires a couple of changes in the way that packages
- are built.
- </p>
- <p>
- A binary <tt>foo</tt> directly uses a library
- <tt>libbar</tt> if it is linked with that
- library. Other libraries that are needed by
- <tt>libbar</tt> are linked indirectly to <tt>foo</tt>,
- and the dynamic linker will load them automatically
- when it loads <tt>libbar</tt>. Running<prgn>ldd</prgn>
- lists all of the libraries used, both directly and
- indirectly; but <prgn>objdump</prgn> only lists the
- directly linked libraries. A package only needs to
- depend on the libraries it is directly linked to,
- since the dependencies for those libraries should
- automatically pull in the other libraries.
- </p>
- <p>
- This change does mean a change in the way packages are
- build though: currently <prgn>dpkg-shlibdeps</prgn> is
- only run on binaries. But since we will now rely on the
- libraries depending on the libraries they themselves
- need, the packages containing those libraries will
- need to run <prgn>dpkg-shlibdeps</prgn> on the
- libraries.
- </p>
- <p>
- A good example where this would help us is the current
- mess with multiple version of the <tt>mesa</tt>
- library. With the <prgn>ldd</prgn>-based system, every
- package that uses <tt>mesa</tt> needs to add a
- dependency on <tt>svgalib|svgalib-dummy</tt> in order
- to handle the glide <tt>mesa</tt> variant. With an
- <prgn>objdump</prgn>-based system this isn't necessary
- anymore and would have saved everyone a lot of work.
- </p>
- <p>
- Another example: we could update <tt>libimlib</tt>
- with a new version that supports a new graphics format
- called dgf. If we use 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 wouldn't
- need to be updated.
- </p>
- </footnote>
- used by the compiled binaries and libraries passed through
- on its command line.
- </p>
-
- <p>
- For each shared library linked to,
- <prgn>dpkg-shlibdeps</prgn> needs to know
- <list compact="compact">
- <item><p>the package containing the library, and</p></item>
- <item><p>the library version number,</p></item>
- </list>
- and it scans the following files in this order:
- <enumlist compact="compact">
- <item><p><tt>debian/shlibs.local</tt></p></item>
- <item><p><tt>/etc/dpkg/shlibs.override</tt></p></item>
- <item><p><tt>/var/lib/dpkg/info/*.shlibs</tt></p></item>
- <item><p><tt>/etc/dpkg/shlibs.default</tt></p></item>
- </enumlist>
- </p>
- </sect1>
-
- <sect1><heading><em>Who</em> maintains the various
- <tt>shlibs</tt> files?
- </heading>
-
- <p>
- <list compact="compact">
- <item>
- <p><tt>/etc/dpkg/shlibs.default</tt> - the maintainer
- of dpkg</p>
- </item>
- <item>
- <p>
- <tt>/var/lib/dpkg/info/<var>package</var>.shlibs</tt>
- - the maintainer of each package</p>
- </item>
- <item>
- <p>
- <tt>/etc/dpkg/shlibs.override</tt> - the local
- system administrator</p>
- </item>
- <item>
- <p><tt>debian/shlibs.local</tt> - the maintainer of
- the package
- </p>
- </item>
- </list>
- The <tt>shlibs.default</tt> file is managed by
- <prgn>dpkg</prgn>. The entries in <tt>shlibs.default</tt>
- that are provided by <prgn>dpkg</prgn> are just there to
- fix things until the shared library packages all have
- <tt>shlibs</tt> files.
- </p>
- </sect1>
-
- <sect1><heading><em>How</em> to use <prgn>dpkg-shlibdeps</prgn> and
- the <tt>shlibs</tt> files
- </heading>
-
- <sect2><heading>If your package doesn't provide a shared
- library
- </heading>
-
- <p>
- Put a call to <prgn>dpkg-shlibdeps</prgn> into your
- <tt>debian/rules</tt> file. If your package contains
- only binaries (e.g. no scripts) use:
- <example>
- dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/*
- </example>
- If <prgn>dpkg-shlibdeps</prgn> doesn't complain, you're
- done. If it does complain you might need to create your
- own <tt>debian/shlibs.local</tt> file.</p>
- </sect2>
-
- <sect2><heading>If your package provides a shared library
- </heading>
-
- <p>
- Create a <tt>debian/shlibs</tt> file and let
- <tt>debian/rules</tt> install it in the control area:
- <example>
- install -m644 debian/shlibs debian/tmp/DEBIAN
- </example>
- If your package contains additional binaries see above.
- </p>
- </sect2>
- </sect1>
-
- <sect1><heading><em>How</em> to write
- <tt>debian/shlibs.local</tt>
- </heading>
-
- <p>
- This file is intended only as a <em>temporary</em> fix if
- your binaries depend on a library which doesn't provide
- its own <tt>/var/lib/dpkg/info/*.shlibs</tt> file yet.
- </p>
-
- <p>
- Let's assume you are packaging a binary <tt>foo</tt>. Your
- output in building the package might look like this.
- <example>
- $ ldd foo
- libbar.so.1 => /usr/X11R6/lib/libbar.so.1.0 (0x4001e000)
- libX11.so.6 => /usr/X11R6/lib/libX11.so.6 (0x4002c000)
- libc.so.6 => /lib/libc.so.6 (0x40114000)
- /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
- </example>
- And when you ran <prgn>dpkg-shlibdeps</prgn>
- <example>
- $ dpkg-shlibdeps -O foo
- dpkg-shlibdeps: warning: unable to find dependency information for shared library libbar
- (soname 1, path /usr/X11R6/lib/libbar.so.1.0, dependency field Depends)
- shlibs:Depends=libc6 (>= 2.2.1), xlibs (>= 4.0.1-11)
- </example>
- The <prgn>foo</prgn> binary depends on the
- <prgn>libbar</prgn> shared library, but no package seems
- to provide a <tt>*.shlibs</tt> file in
- <tt>/var/lib/dpkg/info/</tt>. Let's determine the package
- responsible:
- </p>
-
- <p>
- <example>
- $ dpkg -S /usr/X11R6/lib/libbar.so.1.0
- bar1: /usr/X11R6/lib/libbar.so.1.0
- $ dpkg -s bar1 | grep Version
- Version: 1.0-1
- </example>
- This tells us that the <prgn>bar1</prgn> package, version
- 1.0-1 is the one we are using. Now we can create our own
- <tt>debian/shlibs.local</tt> to temporarily fix the above
- problem. Include the following line into your
- <tt>debian/shlibs.local</tt> file.
- <example>
- libbar 1 bar1 (>= 1.0-1)
- </example>
- Now your package build should work. As soon as the
- maintainer of <prgn>libbar1</prgn> provides a
- <tt>shlibs</tt> file, you can remove your
- <tt>debian/shlibs.local</tt> file.
- </p>
- </sect1>
- </sect>
- </chapt>
-
- <chapt><heading>The Operating System</heading>
-
-
- <sect>
- <heading>File system hierarchy</heading>
-
-
- <sect1>
- <heading>Linux File system Structure</heading>
-
- <p>
- The location of all installed files and directories must
- comply with the Linux File system Hierarchy Standard
- (FHS). The latest version of this document can be found
- alongside this manual or on
- <url id="http://www.pathname.com/fhs/">.
- Specific questions about following the standard may be
- asked on <prgn>debian-devel</prgn>, or referred to Daniel
- Quinlan, the FHS coordinator, at
- <email>quinlan@pathname.com</email>.</p></sect1>
-
-
- <sect1>
- <heading>Site-specific programs</heading>
-
- <p>
- As mandated by the FHS, packages must not place any
- files in <tt>/usr/local</tt>, 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>
+ As mandated by the FHS, packages must not place any
+ files in <tt>/usr/local</tt>, 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
<tt>/usr/local</tt> so that the system administrator knows
- where to place site-specific files. These directories
+ where to place site-specific files. These directories
should be removed on package removal if they are
- empty.</p>
+ empty.
+ </p>
<p>
Note, that this applies only to directories <em>below</em>
- <tt>/usr/local</tt>, not <em>in</em>
- <tt>/usr/local</tt>. Packages must not create sub-directories
- in the directory <tt>/usr/local</tt> 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>
+ <tt>/usr/local</tt>, not <em>in</em> <tt>/usr/local</tt>.
+ Packages must not create sub-directories in the directory
+ <tt>/usr/local</tt> 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 <tt>/usr/local</tt> can be mounted read-only from a
remote server, these directories must be created and
- removed by the <tt>postinst</tt> and <tt>prerm</tt>
- maintainer scripts. These scripts must not fail if either
- of these operations fail. (In the future, it will be
- possible to tell <prgn>dpkg</prgn> not to unpack files
- matching certain patterns, so that the directories can be
- included in the <tt>.deb</tt> packages and system
- administrators who do not wish these directories in
- /usr/local do not need to have them.)</p>
-
- <p>
- For example, the <prgn>emacs</prgn> package will contain
- <example>
- mkdir -p /usr/local/lib/emacs/site-lisp || true
+ removed by the <prgn>postinst</prgn> and <prgn>prerm</prgn>
+ maintainer scripts and not be included in the
+ <tt>.deb</tt> archive. These scripts must not fail if
+ either of these operations fail.
+ <footnote>
+ <p>
+ In the future, it may be possible to tell
+ <prgn>dpkg</prgn> not to unpack files matching certain
+ patterns, so that the directories can be included in
+ the <tt>.deb</tt> packages and system administrators
+ who do not wish these directories in
+ <tt>/usr/local</tt> do not need to have them.)
+ </p>
+ </footnote>
+ </p>
+
+ <p>
+ For example, the <tt>emacsen-common</tt> package could
+ contain something like
+ <example compact="compact">
+mkdir -p /usr/local/share/emacs/site-lisp || true
</example>
- in the <tt>postinst</tt> script, and
- <example>
- rmdir /usr/local/lib/emacs/site-lisp || true
- rmdir /usr/local/lib/emacs || true
+ 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 <tt>prerm</tt> script.</p>
+ in the <prgn>prerm</prgn> script. (Note that this form is
+ used to ensure that if the script is interrupted, the
+ directory <tt>/usr/local/share/emacs</tt> will still be
+ removed.)
+ </p>
<p>
If you do create a directory in <tt>/usr/local</tt> for
local additions to a package, you should ensure that
settings in <tt>/usr/local</tt> take precedence over the
- equivalents in <tt>/usr</tt>.</p>
+ equivalents in <tt>/usr</tt>.
+ </p>
<p>
- However, because '/usr/local' 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 '/usr/local' for normal operation.</p>
+ However, because <tt>/usr/local</tt> 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 <tt>/usr/local</tt> for normal operation.
+ </p>
<p>
The <tt>/usr/local</tt> 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>
+ owned by <tt>root.staff</tt>.
+ </p>
+ </sect1>
+
+ <sect1>
+ <heading>The system-wide mail directory</heading>
+ <p>
+ The system-wide mail directory is <tt>/var/mail</tt>. This
+ directory is part of the base system and should not owned
+ by any particular mail agents. The use of the old
+ location <tt>/var/spool/mail</tt> is deprecated, even
+ though the spool may still be physically located there.
+ To maintain partial upgrade compatibility for systems
+ which have <tt>/var/spool/mail</tt> as their physical mail
+ spool, packages using <tt>/var/mail</tt> must depend on
+ either <package>libc6</package> (>= 2.1.3-13), or on
+ <package>base-files</package> (>= 2.2.0), or on later
+ versions of either one of these packages.
+ </p>
</sect1>
</sect>
<sect>
<heading>Users and groups</heading>
- <p>
- 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
- <tt>/etc/passwd</tt>, <tt>/etc/shadow</tt>,
- <tt>/etc/group</tt> or <tt>/etc/gshadow</tt>.</p>
+ <sect1>
+ <heading>Introduction</heading>
+ <p>
+ The Debian system can be configured to use either plain or
+ shadow passwords.
+ </p>
- <p>
- The UID and GID ranges are 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 <tt>passwd</tt> and <tt>group</tt> files of all
- Debian systems, new ids in this range being added
- automatically as the <tt>base-passwd</tt> package is
- updated.</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>
- 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>
+ <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>
- <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 <tt>adduser.conf</tt>.</p></item>
+ <p>
+ Packages other than <tt>base-passwd</tt> must not modify
+ <tt>/etc/passwd</tt>, <tt>/etc/shadow</tt>,
+ <tt>/etc/group</tt> or <tt>/etc/gshadow</tt>.
+ </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 <tt>passwd</tt> and <tt>group</tt> files of all
+ Debian systems, new ids in this range being added
+ automatically as the <tt>base-passwd</tt> package is
+ updated.
+ </p>
- <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
- <tt>adduser.conf</tt> may be used to modify this
- behavior.</p>
- </item>
+ <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>30000-59999:</tag>
- <item>
- <p>Reserved.</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
+ <tt>adduser.conf</tt>.
+ </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
+ <tt>adduser.conf</tt> may be used to modify this
+ behavior.
+ </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>
+ <tag>30000-59999:</tag>
+ <item>
+ <p>Reserved.</p>
+ </item>
- <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
- <tt>/etc/passwd</tt> or <tt>/etc/group</tt> (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>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
+ <tt>/etc/passwd</tt> or <tt>/etc/group</tt> (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>65534:</tag>
- <item>
- <p>User `<tt>nobody</tt>.' The corresponding gid refers
- to the group `<tt>nogroup</tt>.'</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>. NOT TO BE USED,
- because it is the error return sentinel value.</p>
- </item>
- </taglist>
- </p>
+ <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</heading>
+ <sect id="sysvinit">
+ <heading>System run levels and <tt>init.d</tt> scripts</heading>
<sect1 id="/etc/init.d">
<heading>Introduction</heading>
<p>
The <tt>/etc/init.d</tt> directory contains the scripts
- executed by <prgn>init</prgn> at boot time and when init
- state (or `runlevel') is changed (see <manref name="init"
- section="8">).</p>
+ 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
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 `update-rc.d'
- 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>
+ 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 <tt>/etc/rc<var>n</var>.d</tt> directories. When
- changing runlevels, <prgn>init</prgn> looks in the
- directory <tt>/etc/rc<var>n</var>.d</tt> for the scripts
- it should execute, where <var>n</var> is the runlevel that
- is being changed to, or `S' for the boot-up scripts.</p>
+ These scripts are referenced by symbolic links in the
+ <tt>/etc/rc<var>n</var>.d</tt> directories. When changing
+ runlevels, <prgn>init</prgn> looks in the directory
+ <tt>/etc/rc<var>n</var>.d</tt> 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
<tt>K<var>mm</var><var>script</var></tt> 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 <tt>/etc/init.d</tt>.</p>
+ name of the actual script in <tt>/etc/init.d</tt>).
+ </p>
<p>
When <prgn>init</prgn> changes runlevel first the targets
- of the links whose names starting with a <tt>K</tt> are
+ 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 <tt>K</tt>
- links are responsible for killing services and the
- <tt>S</tt> link for starting services upon entering the
- runlevel.</p>
+ with the single argument <tt>start</tt>. (The links are
+ those in the <tt>/etc/rc<var>n</var>.d</tt> 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 <tt>/etc/rc3.d</tt>, and then
- all of the <tt>S</tt> prefixed scripts. 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 decide which
- order to start and stop things in--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>
- /etc/rc2.d/S17bind
- /etc/rc2.d/S70inn
+ 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>
should behave as if the configuration has been reloaded
successfully.</p>
+ <p>
+ The <tt>/etc/init.d</tt> scripts should be treated as
+ configuration files, either by marking them as
+ <tt>conffile</tt>s or 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>
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>
+ 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, the init
- script itself is usually a configuration file (see
- <ref id="init.d notes">), and will remain on the system if
- the package is removed but not purged. Therefore, you
+ configuration files be removed. In particular, as the
+ <tt>/etc/init.d/<var>package</var></tt> 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>
- test -f <var>program-executed-later-in-script</var> || exit 0
- </example></p>
+ <example compact="compact">
+test -f <var>program-executed-later-in-script</var> || exit 0
+ </example>
+ </p>
<p>
- Often there are some values in the `<tt>init.d</tt>'
- scripts that a system administrator will frequently want
- to change. While the scripts are frequently conffiles,
- modifying them requires that the administrator merge in
- their changes each time the package is upgraded and the
- conffile 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 `<tt>/etc/default</tt>', which
- typically will have the same base name as the
- `<tt>init.d</tt>' script. This extra file can be sourced
- by the script when the script runs. It must contain only
- variable settings and comments.
+ Often there are some variables in the <tt>init.d</tt>
+ scripts whose values control the bahaviour of the scripts,
+ and which a system administrator is likely to want to
+ change. As the scripts themselves are frequently
+ <tt>conffiles</tt>, modifying them requires that the
+ administrator merge in their changes each time the package
+ is upgraded and the <tt>conffile changes</tt>. 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
+ <tt>/etc/default</tt>, which typically will have the same
+ base name as the <tt>init.d</tt> 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 should not be a
+ <tt>conffile</tt>, but a configuration file maintained by
+ the package maintainer scripts. See <ref id="config
+ files"> for more details.
</p>
<p>
To ensure that vital configurable values are always
- available, the `<tt>init.d</tt>' script should set default
- values for each of the shell variables it uses before
- sourcing the <tt>/etc/default/</tt> file. Also, since the
- `<tt>/etc/default/</tt>' file is often a conffile, the
- `<tt>init.d</tt>' script must behave sensibly without
- failing if it is deleted.
+ available, the <tt>init.d</tt> script should set default
+ values for each of the shell variables it uses, either
+ before sourcing the <tt>/etc/default/</tt> file or
+ afterwards using something like the <tt>:
+ ${VAR:=default}</tt> syntax. Also, the <tt>init.d</tt>
+ script must behave sensibly and not fail if the
+ <tt>/etc/default</tt> file is deleted.
</p>
-
</sect1>
<sect1>
<heading>Managing the links</heading>
<p>
- The program <prgn>update-rc.d</prgn> is provided to make
- it easier for package maintainers to arrange for the
- proper creation and removal of
- <tt>/etc/rc<var>n</var>.d</tt> symbolic links, or their
- functional equivalent if another method is being used.
- This may be used by maintainers in their packages'
- <tt>postinst</tt> and <tt>postrm</tt> scripts.</p>
+ The program <prgn>update-rc.d</prgn> is provided for
+ package maintainers to arrange for the proper creation and
+ removal of <tt>/etc/rc<var>n</var>.d</tt> 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>
- You must use this script to make changes to
- <tt>/etc/rc<var>n</var>.d</tt> and <em>never</em> either
- include any <tt>/etc/rc<var>n</var>.d</tt> symbolic links
- in the actual archive or manually create or remove the
- symbolic links in maintainer scripts. (The latter will
- fail if an alternative method of maintaining runlevel
- information is being used.)</p>
+ You must not include any <tt>/etc/rc<var>n</var>.d</tt>
+ 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 <tt>/etc/rc<var>n</var>.d</tt> directories themselves
+ in the archive either. (Only the <tt>sysvinit</tt>
+ package may do so.)
+ </p>
<p>
By default <prgn>update-rc.d</prgn> will start services in
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 either running <prgn>update-rc.d</prgn>, by
- simply adding, moving, or removing the symbolic links in
- <tt>/etc/rc<var>n</var>.d</tt> if symbolic links are being
- used, or by modifying <tt>/etc/runlevel.conf</tt> if the
- <tt>file-rc</tt> method is being used.</p>
+ runlevels by simply adding, moving, or removing the
+ symbolic links in <tt>/etc/rc<var>n</var>.d</tt> if
+ symbolic links are being used, or by modifying
+ <tt>/etc/runlevel.conf</tt> if the <tt>file-rc</tt> method
+ is being used.
+ </p>
<p>
To get the default behavior for your package, put in your
- <tt>postinst</tt> script
- <example>
- update-rc.d <var>package</var> defaults >/dev/null
+ <prgn>postinst</prgn> script
+ <example compact="compact">
+update-rc.d <var>package</var> defaults >/dev/null
</example>
- and in your <tt>postrm</tt>
- <example>
- if [ purge = "$1" ]; then
- update-rc.d <var>package</var> remove >/dev/null
- fi
+ and in your <prgn>postrm</prgn>
+ <example compact="compact">
+if [ "$1" = purge ]; then
+ update-rc.d <var>package</var> remove >/dev/null
+fi
</example></p>
<p>
This will use a default sequence number of 20. If it does
- not matter when or in which order the 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>
+ not matter when or in which order the <tt>init.d</tt>
+ 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>
For more information about using <tt>update-rc.d</tt>,
please consult its manpage <manref name="update-rc.d"
- section="8">.</p></sect1>
+ section="8">.
+ </p>
+ </sect1>
<sect1>
described in <ref id="/etc/init.d">. Packages must not
place files in <tt>/etc/rc.boot</tt>.</p>
- <sect1 id="init.d notes">
- <heading>Notes</heading>
-
- <p>
- <em>Do not</em> include the
- <tt>/etc/rc<var>n</var>.d/*</tt> symbolic links in the
- <tt>.deb</tt> file system archive! <em>This will cause
- problems!</em> You must create them with
- <prgn>update-rc.d</prgn>, as above.</p>
-
- <p>
- <em>Do not</em> include the
- <tt>/etc/rc<var>n</var>.d/*</tt> symbolic links in
- <prgn>dpkg</prgn>'s conffiles list! <em>This will cause
- problems!</em> You should, however, treat the
- <tt>/etc/init.d</tt> scripts as configuration files,
- either by marking them as conffiles or 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>Example</heading>
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 user can say
+ 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.
+ startup; this value is read from
+ <tt>/etc/default/bind</tt> (see below).
</p>
<p>
- <example>
- #!/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 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>
- Complementing the above init script is a file
- '<tt>/etc/default/bind</tt>', which contains configurable
- parameters used by the script.
- </p>
- <p>
- <example>
- # Specified parameters to pass to named. See named(8).
- # You may uncomment the following line, and edit to taste.
- #PARAMS="-u nobody"
+ Complementing the above init script is a configuration
+ file <tt>/etc/default/bind</tt>, 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>
- Another example on which to base your <tt>/etc/init.d</tt>
- scripts is in <tt>/etc/init.d/skeleton</tt>.</p>
+ Another example on which you can base your
+ <tt>/etc/init.d</tt> scripts is found in
+ <tt>/etc/init.d/skeleton</tt>.
+ </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 <tt>postinst</tt>:
- <example>
- update-rc.d bind defaults >/dev/null
+ its <prgn>postinst</prgn>:
+ <example compact="compact">
+update-rc.d bind defaults >/dev/null
</example>
- And in its <tt>postrm</tt>, to remove the links when the
+ And in its <prgn>postrm</prgn>, to remove the links when the
package is purged:
- <example>
- if [ purge = "$1" ]; then
- update-rc.d bind remove >/dev/null
- fi
- </example></p>
- </sect1></sect>
-
- <sect>
- <heading>Cron jobs</heading>
-
- <p>
- Packages must not modify the configuration file
- <tt>/etc/crontab</tt>, and they must not modify the files in
- <tt>/var/spool/cron/crontabs</tt>.</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 of the following directories:
- <example>
- /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
- <tt>/etc/crontab</tt>.</p>
-
- <p>
- All files installed in any of these directories must be
- scripts (shell scripts, Perl scripts, etc.) so that they can
- easily be modified by the local system administrator. In
- addition, they should be treated as configuration files.</p>
-
- <p>
- If a certain job has to be executed more frequently than
- daily, the package should install a file
- <tt>/etc/cron.d/<var>package-name</var></tt>. This file uses
- the same syntax as <tt>/etc/crontab</tt> and is processed by
- <prgn>cron</prgn> automatically. The file must also be
- treated as a configuration file. (Note, that entries in the
- <tt>/etc/cron.d</tt> 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>
+ <example compact="compact">
+if [ "$1" = purge ]; then
+ update-rc.d bind remove >/dev/null
+fi
+ </example>
+ </p>
+ </sect1>
</sect>
<sect>
- <heading>Console messages</heading>
+ <heading>Console messages from <tt>init.d</tt> scripts</heading>
<p>
- This section describes different formats for messages
+ This section describes the formats to be used for messages
written to standard output by the <tt>/etc/init.d</tt>
- scripts. The intent is to improve the consistency of
- Debian's startup and shutdown look and feel.</p>
-
- <p>
- Please look very careful at the details. We want to get the
- messages to look exactly the same way concerning spaces,
- punctuation, and case of letters.</p>
+ 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>
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 isn't covered in the sections
- below.</p>
+ 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>
<list>
<item>
<p>
- Every message should cover one line, start with a
- capital letter and end with a period `.'.</p></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>).
+ </p>
+ </item>
<item>
<p>
If you want to express that the computer is working on
- something (performing a specific task, not starting or
- stopping a program), we use an ``ellipsis'', namely
- three dots `...'. Note that we don't insert spaces in
- front of or behind the dots. If the task has been
- completed we write `done.' and a line feed.</p></item>
-
+ something (that is, performing a specific task, not
+ starting or stopping a program), we use an "ellipsis"
+ (three dots: <tt>...</tt>). Note that we don't insert
+ spaces before or after the dots. If the task has been
+ completed we write <tt>done.</tt> and a line feed.
+ </p>
+ </item>
<item>
<p>
Design your messages as if the computer is telling you
- what he is doing (let him be polite :-) but don't
- mention ``him'' directly. For example, if you think
- of saying
- <example>
- I'm starting network daemons: nfsd mountd.
+ 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>
- Starting network daemons: nfsd mountd.
- </example></p></item>
- </list></p>
+ <example compact="compact">
+Starting network daemons: nfsd mountd.
+ </example>
+ </p>
+ </item>
+ </list>
+ </p>
<p>
- The following formats should be used</p>
+ There are standard message formats for the following
+ situations. They should be used by the <tt>init.d</tt>
+ scripts.
+ </p>
<p>
<list>
<item>
- <p>when daemons get started.</p>
+ <p>When daemons are started</p>
<p>
- Use this format if your script starts one or more
- daemons. The output should look like this (a single
- line, no leading spaces):
- <example>
- Starting <description>: <daemon-1> <daemon-2> <...> <daemon-n>.
+ 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 <description> should describe the subsystem
- the daemon or set of daemons are part of, while
- <daemon-1> up to <daemon-n> denote each
- daemon's name (typically the file name of the
- program).</p>
+ 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>
- For example, the output of /etc/init.d/lpd would look like:
- <example>
- Starting printer spooler: lpd.
- </example></p>
+ For example, the output of <tt>/etc/init.d/lpd</tt>
+ would look like:
+ <example compact="compact">
+Starting printer spooler: lpd.
+ </example>
+ </p>
<p>
This can be achieved by saying
- <example>
- echo -n "Starting printer spooler: lpd"
- start-stop-daemon --start --quiet lpd
- echo "."
+ <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>
- 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 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
+ 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>
-
+ looks good.
+ </p>
+ </item>
<item>
- <p>when something needs to be configured.</p>
+ <p>When a system parameter is being set</p>
<p>
- If you have to set up different parameters of the
- system upon boot up, you should use this format:
- <example>
- Setting <parameter> to `<value>'.
- </example></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 the following echo statement to get the quotes right:
- <example>
- echo "Setting DNS domainname to \`"value"'."
- </example></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>
- Note that the left quotation mark (`) is different
- from the right (').</p></item>
+ Note that the left quotation mark (<tt>`</tt>) is
+ different from the right one (<tt>'</tt>).
+ </p>
+ </item>
<item>
- <p>when a daemon is stopped.</p>
+ <p>When a daemon is stopped or restarted</p>
<p>
- When you stop a daemon you should issue a message
- similar to the startup message, except that `Starting'
- is replaced with `Stopping'.</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>
- So stopping the printer daemon will like like this:
- <example>
- Stopping printer spooler: lpd.
- </example></p></item>
+ For example, stopping the printer daemon will like
+ like this:
+ <example compact="compact">
+Stopping printer spooler: lpd.
+ </example>
+ </p>
+ </item>
<item>
- <p>when something is executed.</p>
+ <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
- via `netdate' or killing all processes when the system
- comes down. Your message should like this:
- <example>
- Doing something very useful...done.
+ 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 `done.' right after the job has been completed,
- so that the user gets informed why he has to wait. You can get this
+ 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>
- echo -n "Doing something very useful..."
- do_something
- echo "done."
+ <example compact="compact">
+echo -n "Doing something very useful..."
+do_something
+echo "done."
</example>
- in your script.</p></item>
+ in your script.
+ </p>
+ </item>
<item>
- <p>when the configuration is reloaded.</p>
+ <p>When the configuration is reloaded</p>
<p>
When a daemon is forced to reload its configuration
files you should use the following format:
- <example>
- Reloading <daemon's-name> configuration...done.
- </example></p></item>
+ <example compact="compact">
+Reloading <var>description</var> configuration...done.
+ </example>
+ where <var>description</var> is the same as in the
+ daemon starting message.
+ </p>
+ </item>
+ </list>
+ </p>
+ </sect>
- <item>
- <p>when none of the above rules apply.</p>
+ <sect>
+ <heading>Cron jobs</heading>
- <p>
- If you have to print a message that doesn't fit into
- the styles described above, you can use something
- appropriate, but please have a look at the overall
- rules listed above.</p></item>
- </list></p></sect>
+ <p>
+ Packages must not modify the configuration file
+ <tt>/etc/crontab</tt>, and they must not modify the files in
+ <tt>/var/spool/cron/crontabs</tt>.</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
+ <tt>/etc/crontab</tt>.</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.
+ </p>
+
+ <p>
+ If a certain job has to be executed more frequently than
+ daily, the package should install a file
+ <tt>/etc/cron.d/<var>package</var></tt>. This file uses the
+ same syntax as <tt>/etc/crontab</tt> and is processed by
+ <prgn>cron</prgn> automatically. The file must also be
+ treated as a configuration file. (Note that entries in the
+ <tt>/etc/cron.d</tt> 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>
<heading>Menus</heading>
<p>
- Menu entries should follow the current menu policy as
- defined in the file <ftpsite>ftp.debian.org</ftpsite> in
- <ftppath>/debian/doc/package-developer/menu-policy.txt.gz</ftppath>
- or your local mirror. In addition, it is included in the
- <tt>debian-policy</tt> package.
+ Menu entries should follow the current menu policy found in
+ the <tt>menu-policy</tt> files in the <tt>debian-policy</tt>
+ package. It may also be found on the Debian FTP site
+ <ftpsite>ftp.debian.org</ftpsite> as the file
+ <ftppath>/debian/doc/package-developer/menu-policy.txt.gz</ftppath>,
+ or in the equivalent location on your local mirror.
</p>
<p>
- The Debian <tt>menu</tt> packages provides a unique
+ 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 as
- <prgn>pdmenu</prgn>).</p>
+ managers or text-based menu programs such as
+ <prgn>pdmenu</prgn>).
+ </p>
<p>
All packages that provide applications that need not be
managers, as well in shells like <tt>pdmenu</tt>.</p>
<p>
- Please refer to the <em>Debian Menu System</em> document
- that comes with the <tt>menu</tt> package for information
- about how to register your applications and web
- documents.</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.
+ </p>
</sect>
-
<sect>
<heading>Multimedia handlers</heading>
<p>
Packages which provide the ability to view/show/play,
compose, edit or print MIME types should register themselves
- as such following the current MIME support policy as defined
- in the file found on <ftpsite>ftp.debian.org</ftpsite> in
- <ftppath>/debian/doc/package-developer/mime-policy.txt.gz</ftppath>
- or your local mirror. In addition, it is included in the
- <tt>debian-policy</tt> package.
+ as such following the current MIME support policy found in
+ the <tt>mime-policy</tt> files in the <tt>debian-policy</tt>
+ package. It may also be found on the Debian FTP site
+ <ftpsite>ftp.debian.org</ftpsite> as the file
+ <ftppath>/debian/doc/package-developer/mime-policy.txt.gz</ftppath>,
+ or in the equivalent location on your local mirror.
</p>
<p>
- MIME (Multipurpose Internet Mail Extensions, RFC 1521) 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).
+ 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>
<heading>Keyboard configuration</heading>
<p>
- To achieve a consistent keyboard configuration (i.e., all
- applications interpret a keyboard event the same way) all
+ 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>
+ comply with the following guidelines.
+ </p>
<p>
- Here is a list that contains certain keys and their interpretation:
+ The following keys must have the specified interpretations:
<taglist>
<tag><tt><--</tt></tag>
<item><p>emacs: the help prefix</p></item>
</taglist>
- The interpretation of any keyboard events should be independent
- of the terminal that's used, be it a virtual console, an X
- terminal emulator, an rlogin/telnet session, etc.</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>
The following list explains how the different programs
- should be set up to achieve this:</p>
+ should be set up to achieve this:
+ </p>
<p>
- <list compact="compact">
- <item><p>`<tt><--</tt>' generates KB_Backspace in
- X.</p></item>
+ <list>
+ <item><p><tt><--</tt> generates <tt>KB_Backspace</tt>
+ in X.</p></item>
- <item><p>`<tt>Delete</tt>' generates KB_Delete in X.</p></item>
+ <item><p><tt>Delete</tt> generates <tt>KB_Delete</tt> in
+ X.</p></item>
<item>
<p>
- X translations are set up to make KB_Backspace
- generate ASCII DEL, and to make KB_Delete generate
- <tt>ESC [ 3 ~</tt> (this is the vt220 escape code for
- the `delete character' key). This must be done by
- loading the resources using xrdb on all local X
- displays, not using the application defaults, so that
- the translation resources used correspond to the
- xmodmap settings.</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.</p></item>
<item>
<p>
The Linux console is configured to make
- `<tt><--</tt>' generate DEL, and `Delete' generate
- <tt>ESC [ 3 ~</tt> (this is the case at the
- moment).</p></item>
+ <tt><--</tt> generate DEL, and <tt>Delete</tt>
+ generate <tt>ESC [ 3 ~</tt>.</p></item>
- <item><p>
- X applications are configured so that Backspace
- deletes left, and Delete deletes right. Motif
+ <item>
+ <p>
+ X applications are configured so that <tt><</tt>
+ deletes left, and <tt>Delete</tt> deletes right. Motif
applications already work like this.</p></item>
- <item><p>stty erase <tt>^?</tt> .</p></item>
+ <item><p>Terminals should have <tt>stty erase ^?</tt> .</p></item>
- <item><p>
- The `xterm' terminfo entry should have <tt>ESC [ 3
- ~</tt> for kdch1, just like TERM=linux and
- TERM=vt220.</p></item>
+ <item>
+ <p>
+ The <tt>xterm</tt> terminfo entry should have <tt>ESC
+ [ 3 ~</tt> for <tt>kdch1</tt>, just as for
+ <tt>TERM=linux</tt> and <tt>TERM=vt220</tt>.</p></item>
- <item><p>
- Emacs is programmed to map KB_Backspace or the `stty
- erase' character to delete-backward-char, and
- KB_Delete or kdch1 to delete-forward-char, and
- <tt>^H</tt> to help as always.</p></item>
+ <item>
+ <p>
+ Emacs is programmed to map <tt>KB_Backspace</tt> or
+ the <tt>stty erase</tt> character to
+ <tt>delete-backward-char</tt>, and <tt>KB_Delete</tt>
+ or <tt>kdch1</tt> to <tt>delete-forward-char</tt>, and
+ <tt>^H</tt> to <tt>help</tt> as always.</p></item>
- <item><p>
- Other applications use the `stty erase' character and
- kdch1 for the two delete keys, with ASCII DEL being
- `delete previous character' and kdch1 being `delete
- character under cursor'.</p></item>
- </list></p>
+ <item>
+ <p>
+ Other applications use the <tt>stty erase</tt>
+ character and <tt>kdch1</tt> for the two delete keys,
+ with ASCII DEL being `delete previous character' and
+ <tt>kdch1</tt> being `delete character under
+ cursor'.</p></item>
+
+ </list>
+ </p>
<p>
- This will solve the problem except for:</p>
+ This will solve the problem except for the following
+ cases:
+ </p>
<p>
- <list compact="compact">
- <item><p>
+ <list>
+ <item>
+ <p>
Some terminals have a <tt><--</tt> key that cannot
be made to produce anything except <tt>^H</tt>. On
these terminals Emacs help will be unavailable on
- <tt>^H</tt> (assuming that the `stty erase' character
- takes precedence in Emacs, and has been set
- correctly). M-x help or F1 (if available) can be used
- instead.</p></item>
-
- <item><p>
- Some operating systems use <tt>^H</tt> for stty erase.
- However, modern telnet versions and all rlogin
- versions propagate stty settings, and almost all UNIX
- versions honour stty erase. Where the stty settings
- are not propagated correctly things can be made to
- work by using stty manually.</p></item>
-
- <item><p>
+ <tt>^H</tt> (assuming that the <tt>stty erase</tt>
+ character takes precedence in Emacs, and has been set
+ correctly). <tt>M-x help</tt> or <tt>F1</tt> (if
+ available) can be used instead.</p></item>
+
+ <item>
+ <p>
+ Some operating systems use <tt>^H</tt> for <tt>stty
+ erase</tt>. However, modern telnet versions and all
+ rlogin versions propagate <tt>stty</tt> settings, and
+ almost all UNIX versions honour <tt>stty erase</tt>.
+ Where the <tt>stty</tt> settings are not propagated
+ correctly, things can be made to work by using
+ <tt>stty</tt> manually.</p></item>
+
+ <item>
+ <p>
Some systems (including previous Debian versions) use
- xmodmap to arrange for both <tt><--</tt> and Delete
- to generate KB_Delete. We can change the behavior
- of their X clients via the same X resources that we
- use to do it for our own, or have our clients be
- configured via their resources when things are the
- other way around. On displays configured like this
- Delete will not work, but <tt><--</tt>
+ <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.</p></item>
- <item><p>
- Some operating systems have different kdch1 settings
- in their terminfo for xterm and others. On these
- systems the Delete key will not work correctly when
- you log in from a system conforming to our policy, but
+ <item>
+ <p>
+ Some operating systems have different <tt>kdch1</tt>
+ settings in their <tt>terminfo</tt> database for
+ <tt>xterm</tt> and others. On these systems the
+ <tt>Delete</tt> key will not work correctly when you
+ log in from a system conforming to our policy, but
<tt><--</tt> will.</p></item>
</list>
</p>
</sect>
-
<sect>
<heading>Environment variables</heading>
<p>
A program must not depend on environment variables to get
- reasonable defaults. (That's because these environment
+ reasonable defaults. (That's because these environment
variables would have to be set in a system-wide
- configuration file like /etc/profile, which is not supported
- by all shells.)</p>
+ configuration file like <tt>/etc/profile</tt>, which is not
+ supported by all shells.)</p>
<p>
If a program usually depends on environment variables for its
<p>
Here is an example of a wrapper script for this purpose:
- <example>
- #!/bin/sh
- BAR=${BAR:-/var/lib/fubar}
- export BAR
- exec /usr/lib/foo/foo "$@"
- </example></p>
+ <example compact="compact">
+#!/bin/sh
+BAR=${BAR:-/var/lib/fubar}
+export BAR
+exec /usr/lib/foo/foo "$@"
+ </example>
+ </p>
<p>
Furthermore, as <tt>/etc/profile</tt> is a configuration
file.</p>
</sect>
</chapt>
- <chapt>
+
+ <chapt id="files">
<heading>Files</heading>
<p>
Generally the following compilation parameters should be used:
- <example>
- CC = gcc
- CFLAGS = -O2 -Wall # sane warning options vary between programs
- LDFLAGS = # none
- install -s # (or use strip on the files in debian/tmp)
+ <example compact="compact">
+CC = gcc
+CFLAGS = -O2 -Wall # sane warning options vary between programs
+LDFLAGS = # none
+install -s # (or use strip on the files in debian/tmp)
</example></p>
<p>
compiling that package.
</p>
<p>Now this has several added benefits:
- <list>
+ <list compact="compact">
<item>
<p>
It is actually easier to build debugging bins and
</footnote>
- <example>
- CFLAGS = -O2 -Wall
- 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
-
- ifneq (,$(findstring debug,$(DEB_BUILD_OPTIONS)))
- CFLAGS += -g
- endif
- ifeq (,$(findstring nostrip,$(DEB_BUILD_OPTIONS)))
- INSTALL_PROGRAM += -s
- endif
+ <example compact="compact">
+CFLAGS = -O2 -Wall
+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
+
+ifneq (,$(findstring debug,$(DEB_BUILD_OPTIONS)))
+CFLAGS += -g
+endif
+ifeq (,$(findstring nostrip,$(DEB_BUILD_OPTIONS)))
+INSTALL_PROGRAM += -s
+endif
</example>
Please note that the above example is merely informative,
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
+ options are best: they are often inappropriate for our
environment.</p></sect>
<p>
Note that all installed shared libraries should be
stripped with
- <example>
- strip --strip-unneeded <your-lib>
+ <example compact="compact">
+strip --strip-unneeded <your-lib>
</example>
- (The option `--strip-unneeded' makes <tt>strip</tt> 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.</p>
+ (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.</p>
<p>
Note that under some circumstances it may be useful to
libraries you need to create two packages:
<tt><var>libraryname</var><var>soname</var></tt>
(<var>soname</var> is the shared object name of the shared
- library--it's the thing that has to match exactly between
+ library: 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; usually the
<var>soname</var> is the major number of the library) and
without getting filename clashes. Instead, either create
a third package for the runtime binaries (this package
might typically be named
- <tt><var>libraryname</var>-runtime</tt>--note the absence
+ <tt><var>libraryname</var>-runtime</tt>; note the absence
of the <var>soname</var> in the package name) or if the
development package is small include them in there.</p>
<p>
You should follow the directions in the <em>Debian Packaging
- Manual</em> for putting the shared library in its package,
- and you must include a <tt>shlibs</tt> control area
- file with details of the dependencies for packages which
- use the library.</p>
+ Manual</em> (or other documentation of the Debian
+ packaging tools) for putting the shared library in its
+ package, and you must include a <tt>shlibs</tt> control area
+ file with details of the dependencies for packages which use
+ the library.</p>
<p>
Shared libraries should not be installed
<p>
For example, in your <prgn>Makefile</prgn> or
<tt>debian/rules</tt>, do things like:
- <example>
- 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 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
</example></p>
<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 <tt>postinst</tt> script,
+ <prgn>MAKEDEV</prgn> in the <prgn>postinst</prgn> script,
after asking the user for permission to do so.</p>
<p>
Packages must not remove any device files in the
- <tt>postrm</tt> or any other script. This is left to the
+ <prgn>postrm</prgn> or any other script. This is left to the
system administrator.</p>
<p>
<p>
Configuration file handling must conform to the following
behavior:
- <list>
+ <list compact="compact">
<item>
<p>local changes must be preserved during a package
upgrade</p>
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 <tt>postinst</tt> script.</p>
+ (semi-)automatically by the <prgn>postinst</prgn> script.</p>
<p>
A common practice is to create a script called
<tt><var>package</var>-configure</tt> and have the
- package's <tt>postinst</tt> call it if and only if the
+ 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
logrotate. Here is a good example for a logrotate config
file (for more information see <manref name="logrotate"
section="8">):
- <example>
- /var/log/foo/* {
- rotate 12
- weekly
- compress
- postrotate
- /etc/init.d/foo force-reload
- endscript
- }
+ <example compact="compact">
+/var/log/foo/* {
+rotate 12
+weekly
+compress
+postrotate
+/etc/init.d/foo force-reload
+endscript
+}
</example>
Which rotates all files under `/var/log/foo', saves 12
compressed generations, and sends a HUP signal at the end of
<p>
Log files should be removed when the package is
purged (but not when it is only removed), by checking the
- argument to the <tt>postrm</tt> script (see the <em>Debian
+ argument to the <prgn>postrm</prgn> script (see the <em>Debian
Packaging Manual</em> for details).</p>
</sect>
<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
+ consistent with its mode: if a directory is mode 2775, it
should be owned by the group that needs write access to
it.</p>
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
+ Debian package, it is merely inconvenient. For the same
reason you should not restrict read or execute permissions
on non-set-id executables.</p>
</sect>
</chapt>
- <chapt>
+ <chapt id="customized-programs">
<heading>Customized programs</heading>
<sect id="arch-spec">
<p>
If a program needs to specify an <em>architecture specification
string</em> in some place, the following format should be used:
- <example>
- <arch>-<os>
+ <example compact="compact">
+<arch>-<os>
</example>
where `<arch>' is one of the following: i386, alpha, arm, m68k,
powerpc, sparc and `<os>' is one of: linux, gnu. Use
<item>
<p>Cgi-bin executable files are installed in the
directory
- <example>
- /usr/lib/cgi-bin/<cgi-bin-name>
+ <example compact="compact">
+/usr/lib/cgi-bin/<cgi-bin-name>
</example>
and should be referred to as
- <example>
- http://localhost/cgi-bin/<cgi-bin-name>
- </example></p></item>
-
+ <example compact="compact">
+http://localhost/cgi-bin/<cgi-bin-name>
+ </example>
+ </p>
+ </item>
<item><p>Access to html documents</p>
<tt>/usr/doc/<var>package</var></tt><footnote> for
backward compatibility, see <ref id="usrdoc"></footnote>
and can be referred to as
- <example>
- http://localhost/doc/<package>/<filename>
- </example></p></item>
-
+ <example compact="compact">
+http://localhost/doc/<package>/<filename>
+ </example>
+ </p>
+ </item>
<item><p>Web Document Root</p>
/usr/share/doc/<package> directory for documents and
register the Web Application via the menu package. If
access to the web-root is unavoidable then use
- <example>
- /var/www
+ <example compact="compact">
+/var/www
</example>
as the Document Root. This might be just a
symbolic link to the location where the sysadmin has
</enumlist></p></sect>
- <sect>
+ <sect id="mail-transport-agents">
<heading>Mail transport, delivery and user agents</heading>
<p>
serious brain damage!</p>
<p>
- The mail spool is <tt>/var/spool/mail</tt> and the interface
+ The mail spool is <tt>/var/mail</tt> and the interface
to send a mail message is <tt>/usr/sbin/sendmail</tt> (as
- per the FHS). The mail spool is part of the base system
- and not part of the MTA package.</p>
+ per the FHS). On older systems, the mail spool may be
+ physically located in /var/spool/mail, but all access to the
+ mail spool should be via the /var/mail symlink. The mail
+ spool is part of the base system and not part of the MTA
+ package.
+ </p>
<p>
All Debian MUAs, MTAs, MDAs and other mailbox accessing
<p>
<tt>/etc/aliases</tt> is the source file for the system mail
- aliases (e.g., postmaster, usenet, etc.)--it is the one
- which the sysadmin and <tt>postinst</tt> scripts may edit.
+ aliases (e.g., postmaster, usenet, etc.), it is the one
+ which the sysadmin and <prgn>postinst</prgn> scripts may edit.
After <tt>/etc/aliases</tt> is edited the program or human
editing it must call <prgn>newaliases</prgn>. All MTA
packages must come with a <prgn>newaliases</prgn> program,
configuration. The prompt should make it clear that the
name will not just be used by that package. For example, in
this situation the INN package says:
- <example>
- 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 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>
-
+ --fqdn</tt>.
+ </p>
+ </sect>
<sect>
<heading>News system configuration</heading>
<tt>x-window-manager</tt>. They should also register themselves as an
alternative for <tt>/usr/bin/x-window-manager</tt>, with a priority
calculated as follows:
- <list>
+ <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
<item>
BDF fonts should be converted to PCF fonts with the
<tt>bdftopcf</tt> utility (available in the
- <tt>xutils</tt> package, <tt>gzip</tt>ped, and
+ <tt>xutils</tt> package), <tt>gzip</tt>ped, and
placed in a directory that corresponds to their
resolution:
- <list>
+ <list compact="compact">
<item>
100 dpi fonts should be placed in
<tt>/usr/X11R6/lib/X11/fonts/100dpi/</tt>.
Font packages <em>must not</em> provide the files
<tt>fonts.dir</tt>, <tt>fonts.alias</tt>, or
<tt>fonts.scale</tt> in a font directory.
- <list>
+ <list compact="compact">
<item>
<tt>fonts.dir</tt> files must not be provided at
all.
</p>
<p>
- <em>Packages using the X Window System should abide by the FHS
- standard whenever possible</em>; they should install binaries,
- libraries, manual pages, and other files in FHS-mandated
- locations wherever possible. This means that files must
- not be installed into <tt>/usr/X11R6/bin/</tt>,
- <tt>/usr/X11R6/lib/</tt>, or <tt>/usr/X11R6/man/</tt> unless
- this is necessary for the package to operate properly.
- Configuration files for window managers and display managers
- should be placed in a subdirectory of <tt>/etc/X11/</tt>
- 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
- <tt>/etc/</tt> directory unless otherwise mandated by
- policy. The installation of files into subdirectories of
- <tt>/usr/X11R6/include/X11/</tt> and
- <tt>/usr/X11R6/lib/X11/</tt> is permitted but discouraged;
- package maintainers should determine if subdirectories of
- <tt>/usr/lib/</tt> and <tt>/usr/share/</tt> can be used
- instead (symlinks from the X11R6 directories to
- FHS-compliant locations is encouraged if the program is not
- easily configured to look elsewhere for its files).
- Packages must not provide -- or install files into -- the
- directories <tt>/usr/bin/X11/</tt>,
- <tt>/usr/include/X11/</tt>, or <tt>/usr/lib/X11/</tt>.
- Files within a package should, however, make reference to
- these directories, rather than their X11R6-named
- counterparts <tt>/usr/X11R6/bin/</tt>,
- <tt>/usr/X11R6/include/X11/</tt>, and
- <tt>/usr/X11R6/lib/X11/</tt>, if the resources being
- referred to have not been moved to FHS-compliant locations.
+ <em>Packages using the X Window System should abide by the
+ FHS standard whenever possible</em>; they should install
+ binaries, libraries, manual pages, and other files in
+ FHS-mandated locations wherever possible. This means that
+ files must not be installed into <tt>/usr/X11R6/bin/</tt>,
+ <tt>/usr/X11R6/lib/</tt>, or <tt>/usr/X11R6/man/</tt>
+ unless this is necessary for the package to operate
+ properly. Configuration files for window managers and
+ display managers should be placed in a subdirectory of
+ <tt>/etc/X11/</tt> 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 <tt>/etc/</tt> directory unless otherwise mandated
+ by policy. The installation of files into subdirectories
+ of <tt>/usr/X11R6/include/X11/</tt> and
+ <tt>/usr/X11R6/lib/X11/</tt> is permitted but discouraged;
+ package maintainers should determine if subdirectories of
+ <tt>/usr/lib/</tt> and <tt>/usr/share/</tt> can be used
+ instead (symlinks from the X11R6 directories to
+ FHS-compliant locations is encouraged if the program is
+ not easily configured to look elsewhere for its files).
+ Packages must not provide or install files into the
+ directories <tt>/usr/bin/X11/</tt>,
+ <tt>/usr/include/X11/</tt>, or <tt>/usr/lib/X11/</tt>.
+ Files within a package should, however, make reference to
+ these directories, rather than their X11R6-named
+ counterparts <tt>/usr/X11R6/bin/</tt>,
+ <tt>/usr/X11R6/include/X11/</tt>, and
+ <tt>/usr/X11R6/lib/X11/</tt>, if the resources being
+ referred to have not been moved to FHS-compliant
+ locations.
</p>
<p>
</p>
</sect>
+ <sect>
+ <heading>Perl programs and modules</heading>
+ <p>
+ Perl programs and modules should follow the current Perl
+ policy as defined in the file found on
+ <ftpsite>ftp.debian.org</ftpsite> in
+ <ftppath>/debian/doc/package-developer/perl-policy.txt.gz</ftppath>
+ or your local mirror. In addition, it is included in the
+ <tt>debian-policy</tt> package.
+ </p>
+ </sect>
<sect>
<heading>Emacs lisp programs</heading>
</sect>
</chapt>
- <chapt><heading>Documentation</heading>
+ <chapt id="docs"><heading>Documentation</heading>
<sect>
to the <manref name="undocumented" section="7"> manual page
may be provided. This symbolic link can be created from
<tt>debian/rules</tt> like this:
- <example>
- ln -s ../man7/undocumented.7.gz \
- debian/tmp/usr/share/man/man[1-9]/the_requested_manpage.[1-9].gz
+ <example compact="compact">
+ln -s ../man7/undocumented.7.gz \
+debian/tmp/usr/share/man/man[1-9]/the_requested_manpage.[1-9].gz
</example>
This manpage claims that the lack of a manpage has been
reported as a bug, so you may only do this if it really has
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
+ 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>
is better to use a symbolic link than the <tt>.so</tt>
feature, but there is no need to fiddle with the relevant
parts of the upstream source to change from <tt>.so</tt> to
- symlinks--don't do it unless it's easy. You should not create hard
+ 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 <tt>.so</tt> directives. The filename
in a <tt>.so</tt> in a manpage should be relative to the
Your package should call <prgn>install-info</prgn> to update the Info
<tt>dir</tt>
file, in its post-installation script:
- <example>
- install-info --quiet --section Development Development \
- /usr/share/info/foobar.info
+ <example compact="compact">
+install-info --quiet --section Development Development \
+/usr/share/info/foobar.info
</example></p>
<p>
<p>
You should remove the entries in the pre-removal script:
- <example>
- install-info --quiet --remove /usr/share/info/foobar.info
+ <example compact="compact">
+install-info --quiet --remove /usr/share/info/foobar.info
</example></p>
<p>
with <prgn>dpkg</prgn>. One reasonable way to accomplish
this is to put the following in the package's
<prgn>postinst</prgn>:
- <example>
- if [ "$1" = "configure" ]; then
- if [ -d /usr/doc -a ! -e /usr/doc/#PACKAGE# \
- -a -d /usr/share/doc/#PACKAGE# ]; then
- ln -sf ../share/doc/#PACKAGE# /usr/doc/#PACKAGE#
- fi
- fi
+ <example compact="compact">
+if [ "$1" = "configure" ]; then
+ if [ -d /usr/doc -a ! -e /usr/doc/#PACKAGE# \
+ -a -d /usr/share/doc/#PACKAGE# ]; then
+ ln -sf ../share/doc/#PACKAGE# /usr/doc/#PACKAGE#
+ fi
+fi
</example>
And the following in the package's <prgn>prerm</prgn>:
- <example>
- if [ \( "$1" = "upgrade" -o "$1" = "remove" \) \
- -a -L /usr/doc/#PACKAGE# ]; then
- rm -f /usr/doc/#PACKAGE#
- fi
+ <example compact="compact">
+if [ \( "$1" = "upgrade" -o "$1" = "remove" \) \
+ -a -L /usr/doc/#PACKAGE# ]; then
+ rm -f /usr/doc/#PACKAGE#
+fi
</example>
</p>
</sect>
<p>
Every package must be accompanied by a verbatim copy of its
copyright and distribution license in the file
- /usr/share/doc/<package-name>/copyright. This file must
+ /usr/share/doc/<package>/copyright. This file must
neither be compressed nor be a symbolic link.</p>
<p>
<p>
- /usr/share/doc/<package-name> may be a symbolic link to a
+ /usr/share/doc/<package> may be a symbolic link to a
directory in /usr/share/doc only if two packages both come from
the same source and the first package has a "Depends"
relationship on the second. These rules are important
Any examples (configurations, source files, whatever),
should be installed in a directory
<tt>/usr/share/doc/<var>package</var>/examples</tt>. These
- files should not be referenced by any program--they're there
+ 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
projects / debian / debian-policy.git / blobdiff