Christoph Lameter contributed the "Web Standard"
The debian-policy mailing list has taken responsibility for the
contents of this document since September 1998, with the package
- maintainers responsible for packagingn adminstrivia only.
+ maintainers responsible for packaging adminstrivia only.
-->
<book>
GNU/Linux distribution. This includes the structure and
contents of the Debian archive, several design issues of the
operating system, as well as technical requirements that each
- package must satisfy to be included in the distribution.
+ package must satisfy to be included in the distribution. The
+ policy package itself is maintained by a group of maintainers
+ that have no editorial powers. At the moment, the list of
+ maintainers is:
+ <enumlist>
+ <item>
+ <p>Michael Alan Dorman <email>mdorman@debian.org</email></p>
+ </item>
+ <item>
+ <p>Richard Braakman <email>dark@xs4all.nl</email></p>
+ </item>
+ <item>
+ <p>Philip Hands <email>phil@hands.com</email></p>
+ </item>
+ <item>
+ <p>Julian Gilbey <email>J.D.Gilbey@qmw.ac.uk</email></p>
+ </item>
+ <item>
+ <p>Manoj Srivastava <email>srivasta@debian.org</email></p>
+ </item>
+ </enumlist>
</abstract>
+
<copyright>
<copyrightsummary>
Copyright ©1996,1997,1998 Ian Jackson
warranty of merchantability or fitness for a particular
purpose. See the GNU General Public License for more
details.
- </p>
+ </p>
+
<p>
A copy of the GNU General Public License is available as
- <tt>/usr/doc/copyright/GPL</tt> in the Debian GNU/Linux
+ <tt>/usr/share/common-licences/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="&urlname">. You can also obtain it by writing to the
+ <url id="http://www.gnu.org/copyleft/gpl.html"
+ name="The GNU 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>
mechanisms involved in package creation, installation, and
removal. This information can be found in the <em>Debian
Packaging Manual</em> and the <em>Debian System
- Administrators' Manual</em>.
+ Administrators' Manual</em>. Please note that the
+ footnotes present in this manual are merely informative,
+ and are not part of Debian policy itself.
</p>
<p>
This document assumes familiarity with these other two
<heading>New versions of this document</heading>
<p>
The current version of this document is always accessible from the
- Debian FTP server at
- <url
- id="ftp://ftp.debian.org/debian/doc/manuals/debian-policy.html.tar.gz" name="&urlname">
+ Debian FTP server <ftpsite>ftp.debian.org</ftpsite> at
+ <ftppath>/debian/doc/package-developer/debian-policy.html.tar.gz</ftppath>
or from the Debian WWW server at
- <url id="http://www.debian.org/doc/manuals/debian-policy/"
- name="&urlname"></p>
+ <url id="http://www.debian.org/doc/debian-policy/"
+ name="The Debian Policy Manual">.</p>
<p>
In addition, this manual is distributed via the Debian package
- <tt>debian-policy</tt>
+ <tt>debian-policy</tt>.
</p>
</sect>
<sect>
<sect1>
<heading>The Debian Free Software Guidelines</heading>
<p>
- The Debian Free Software Guidelines (DFSG) as is our
+ The Debian Free Software Guidelines (DFSG) is our
definition of `free' software.
<taglist>
- <tag>>Free Redistribution
+ <tag>Free Redistribution
</tag>
<item>
<p>
program is extracted from Debian and used or
distributed without Debian but otherwise within the
terms of the program's license, all parties to whom
- the program is redistributed should have the same
+ the program is redistributed must have the same
rights as those that are granted in conjunction with
the Debian system.
</p>
non-free programs,
</p>
</item>
- <item>
- <p>
- packages which we don't want to support because they are too
- buggy, and
- </p>
- </item>
- <item>
- <p>
- packages which fail to meet some other policy requirements in
- a serious way.
- </p>
- </item>
</list>
</p>
</sect1>
<p>
Every package must be accompanied by a verbatim copy of its
copyright and distribution license in the file
- /usr/doc/<package-name>/copyright (see <ref
+ /usr/share/doc/<package-name>/copyright (see <ref
id="copyrightfile"> for details).</p>
<p>
We reserve the right to restrict files from being included
<heading>Subsections</heading>
<p>
- The packages in the <em>main</em>, <em>contrib</em>, and
- <em>non-free</em> sections are grouped further into
- <em>subsections</em> to simplify handling of them.</p>
+ The packages in all the sections (<em>main</em>,
+ <em>contrib</em>, <em>non-US/main</em>, <em>non-free</em>,
+ <em>non-US/contrib</em>, and <em>non-US/non-free</em>) are
+ grouped further into <em>subsections</em> to simplify
+ handling.</p>
<p>
The section for each package is specified in the package's
expect to find on any Unix-like system. If the
expectation is that an experienced Unix person who
found it missing would say `What the F*!@<+ is
- going on, where is <prgn>foo</prgn>', it should be in
+ going on, where is <prgn>foo</prgn>', it must be in
<tt>important</tt>. This is an important criterion
because we are trying to produce, amongst other
things, a free Unix. Other packages without which the
- system will not run well or be usable should also be
- here. This does <em>not</em> include Emacs or X11 or
- TeX or any other large applications. The
- <tt>important</tt> packages are just a bare minimum of
- commonly-expected and necessary tools.</p>
+ system will not run well or be usable must also be
+ here. This does <em>not</em> include Emacs, the X
+ Window System, TeX or any other large applications.
+ The <tt>important</tt> packages are just a bare
+ minimum of commonly-expected and necessary tools.</p>
</item>
<tag><tt>standard</tt></tag>
<item>
required, but that's not what is meant here.) This is
all the software that you might reasonably want to
install if you didn't know what it was or don't have
- specialised requirements. This is a much larger system
- and includes X11, a full TeX distribution, and lots of
- applications.</p>
+ specialized requirements. This is a much larger system
+ and includes the X Window System, a full TeX
+ distribution, and many applications.</p>
</item>
<tag><tt>extra</tt></tag>
<item>
- <p>
- This contains packages that conflict with others with
- higher priorities, or are only likely to be useful if
- you already know what they are or have specialised
+ <p>
+ This contains all packages that conflict with others
+ with required, important, standard or optional
+ priorities, or are only likely to be useful if you
+ already know what they are or have specialised
requirements.
</p>
</item>
<p>
Packages may not depend on packages with lower priority
- values. If this should happen, one of the priority values
- will have to be adapted.
+ values (excluding build-time dependencies). In order to
+ ensure this, the priorities of one or more packages may have
+ to be adjusted.
</p>
</sect>
<p>
If the maintainer of a package quits from the Debian
- project the Debian QA Group takes over the maintainership
- of the package until someone else volunteers for that
- task. These packages are called <em>orphaned
- packages</em>.
+ project the Debian QA Group
+ <email>debian-qa@lists.debian.org</email> takes over the
+ maintainership of the package until someone else
+ volunteers for that task. These packages are called
+ <em>orphaned packages</em>.
</p>
</sect1>
<heading>The description of a package</heading>
<p>
- Every Debian package should have an extended description
+ Every Debian package must have an extended description
stored in the appropriate field of the control record.</p>
<p>
- The description should be written so that it tells the
- user what they need to know to decide whether to install
- the package. This description should not just be copied
- from the blurb for the program. Instructions for
- configuring or using the package should not be
- included--that is what installation scripts, manual pages,
- Info files, etc. are for. Copyright statements and other
- administrivia should not be included--that is what the
- copyright file is for.</p>
+ The description must be written so that it tells the user
+ what they need to know to decide whether to install the
+ package. This description should not just be copied from
+ the blurb for the program. Instructions for configuring
+ or using the package must not be included -- that is what
+ installation scripts, manual pages, Info files, etc. are
+ for. Copyright statements and other administrivia must
+ not be included -- that is what the copyright file is
+ for.</p>
</sect1>
<p>
Sometimes, there are several packages doing more-or-less
the same job. In this case, it's useful to define a
- <em>virtual package</em> who's name describes the function
+ <em>virtual package</em> whose name describes the function
the packages have. (The virtual packages just exist
logically, not physically--that's why they are called
<em>virtual</em>.) The packages with this particular
<p>
Since these packages can not easily be removed (you'll
have to specify an extra <em>force option</em> to
- <prgn>dpkg</prgn>) this flag should only be used where
+ <prgn>dpkg</prgn>) this flag must only be used where
absolutely necessary.
- A shared library package should not be tagged
+ A shared library package must not be tagged
<em>essential</em>--the dependencies will prevent its
premature removal, and we need to be able to remove it
when it has been superseded.</p>
<heading>Maintainer scripts</heading>
<p>
- The package installation scripts should avoid producing
+ The package installation scripts must avoid producing
output which it is unnecessary for the user to see and
should rely on <prgn>dpkg</prgn> to stave off boredom on
the part of a user installing many packages. This means,
<prgn>install-info</prgn>.</p>
<p>
- Packages should try to minimise the amount of prompting
+ Packages should try to minimize the amount of prompting
they need to do, and they should ensure that the user will
only ever be asked each question once. This means that
packages should try to use appropriate shared
configuration files (such as <tt>/etc/papersize</tt> and
- <tt>/etc/nntpserver</tt>), rather than each prompting for
+ <tt>/etc/news/server</tt>), rather than each prompting for
their own list of required pieces of information.</p>
<p>
and prompt the user to hit return to acknowledge the
message. Copyright messages do not count as vitally
important (they belong in
- <tt>/usr/doc/<var>package</var>/copyright</tt>); neither
+ <tt>/usr/share/doc/<var>package</var>/copyright</tt>); neither
do instructions on how to use a program (these should be
in on line documentation, where all the users can see
them).</p>
correctly all the packages which supply an instance of the
`shared' command name (or, in general, filename) must use
it. You can use <tt>Conflicts</tt> to force the
- deinstallation of other packages supplying it which do not
+ De-installation of other packages supplying it which do not
(yet) use <prgn>update-alternatives</prgn>. It may in
this case be appropriate to specify a conflict on earlier
- versions on something--this is an exception to the usual
+ versions of something--this is an exception to the usual
rule that this is not allowed.</p>
</sect1>
</sect>
changed when only cosmetic, typographical or other edits
which do not change the meaning are made, or changes which
do not affect the contents of packages.</p>
+
+ <p>
+ For package maintainers, only the first 3 digits of the
+ manual version are significant in representing the
+ <em>Standards-Version</em>, and either these 3 digits or
+ the complete 4 digits can be specified--that's up to the
+ maintainer.
+ <footnote>
+ <p>
+ In the past, people specified 4 digits in the
+ Standards-Version field, like `2.3.0.0'. Since any
+ `patch-level changes' don't introduce new policy, it
+ was thought it would be better to relax policy and
+ only require that the first 3 digits are specified. (4
+ digits can still be used if someone wants to do so.)
+ </p>
+ </footnote>
+ </p>
<p>
You should regularly, and especially if your package has
release it.</p></sect1>
+ <sect1>
+ <heading>Package relationships</heading>
+
+ <p>
+ Source packages must specify which binary packages they
+ require to be installed or not to be installed in order to
+ build correctly. For example, if building a package
+ requires a certain compiler, then the compiler must be
+ specified as a build-time dependency.
+ </p>
+
+ <p>
+ It will not be necessary to explicitly specify build-time
+ relationships on a minimal set of packages that are always
+ needed to compile, link and put in a Debian package a
+ standard "Hello World!" program written in C or C++. The
+ required packages are called <em>build-essential</em>, and
+ an informational list can be found in
+ <tt>/usr/share/doc/build-essential/list</tt> (which is
+ contained in the <tt>build-essential</tt> package).
+
+ </p>
+
+ <p>
+ When specifying the set of build-time dependencies, one
+ should list only those packages explicitly required by the
+ build. It is not necessary to list packages which are
+ required merely because some other package in the list of
+ build-time dependencies depends on them. The reason is
+ that dependencies change, and you should list only those
+ <em>you</em> need. What others need is their business.
+ </p>
+
+ <p>
+ It is a bug if, after unpacking a source package on a
+ system with the build-essential packages installed and
+ satisfying the build-time relationships (including the
+ implied relationships), one cannot build the package and
+ produce a working binary package suitable for installation
+ into the binary distribution corresponding to the source
+ distribution which contained the source package. This
+ means in particular that version clauses should be used
+ rigorously in build-time relationships so that one cannot
+ produce bad or inconsistently configured packages when the
+ relationships are properly satisfied.
+ </p>
+
<sect1>
<heading>Changes to the upstream sources</heading>
<p>
A copy of the file which will be installed in
- <tt>/usr/doc/<var>package</var>/copyright</tt> should be
+ <tt>/usr/share/doc/<var>package</var>/copyright</tt> should be
in <tt>debian/copyright</tt>.</p>
<p>
<sect>
- <heading>Filesystem hierarchy</heading>
+ <heading>File system hierarchy</heading>
<sect1>
- <heading>Linux Filesystem Structure</heading>
+ <heading>Linux File system Structure</heading>
<p>
The location of all installed files and directories must
- comply fully with the Linux Filesystem Structure (FSSTND).
- The latest version of this document can be found alongside
- this manual or on <ftpsite>tsx-11.mit.edu</ftpsite> in
- <ftppath>/pub/linux/docs/linux-standards/fsstnd/</ftppath>.
+ 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/">.<footnote>
+ <p>The Debian distribution currently distributes a draft
+ version of FHS 2.1 because several significant details
+ have changed between the currently released 2.0
+ version and the to-be-released 2.1 version.</p>
+ </footnote>
Specific questions about following the standard may be
asked on <prgn>debian-devel</prgn>, or referred to Daniel
- Quinlan, the FSSTND coordinator, at
+ Quinlan, the FHS coordinator, at
<email>quinlan@pathname.com</email>.</p></sect1>
<heading>Site-specific programs</heading>
<p>
- As mandated by the FSSTND no package should place any
+ As mandated by the FHS no package should place any
files in <tt>/usr/local</tt>, either by putting them in
- the filesystem archive to be unpacked by <prgn>dpkg</prgn>
+ the file
system archive to be unpacked by <prgn>dpkg</prgn>
or by manipulating them in their maintainer scripts.</p>
<p>
<tt>/usr/local</tt>, not <em>in</em>
<tt>/usr/local</tt>. The directory <tt>/usr/local</tt>
itself may only contain the sub-directories listed in
- FSSTND, section 4.8. However, you may create directories
+ FHS, section 4.6. However, you may create directories
below them as you wish. You may not remove any of the
- directories listed in 4.8, even if you created them.</p>
+ directories listed in 4.6, even if you created them.</p>
<p>
Since <tt>/usr/local</tt> may be mounted read-only from a
local additions to a package, you must ensure that
settings in <tt>/usr/local</tt> take precedence over the
equivalents in <tt>/usr</tt>.</p>
-
+
<p>
- The <tt>/usr/local</tt> directory itself and all the subdirectories
- created by the package should have permissions 2775 (group-writable
- and set-group-id) and be owned by <tt>root.staff</tt>.</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>
+
+ <p>
+ The <tt>/usr/local</tt> directory itself and all the
+ subdirectories created by the package should have
+ permissions 2775 (group-writable and set-group-id) and be
+ owned by <tt>root.staff</tt>.</p>
</sect1>
</sect>
<p>
Apart from this we should have dynamically allocated ids,
which should by default be arranged in some sensible
- order--but the behaviour should be configurable.</p>
+ order--but the behavior should be configurable.</p>
<p>
No package except <tt>base-passwd</tt> may modify
<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
- behaviour.</p>
+ behavior.</p>
</item>
<tag>30000-59999:</tag>
<heading>System run levels</heading>
- <sect1>
+ <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> <p>
-
- These scripts are being referenced by symbolic links in
+ section="8">).</p>
+
+ <p>
+ There are at least two different, yet functionally
+ equivalent, ways of handling these scripts. For the sake
+ of simplicity, this document describes only the symbolic
+ link method. However, it may not be assumed that this
+ method is being used, and any manipulation of the various
+ runlevel behaviours must be performed using
+ <prgn>update-rc.d</prgn> as described below and not by
+ manually installing 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>
- <p>
+ <p>
The names of the links all have the form
- <tt>S<var>mm/<var>script</var></var></tt> or
- <tt>K<var>mm/<var>script</var></var></tt> where
+ <tt>S<var>mm</var><var>script</var></tt> or
+ <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>.
+ 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
executed, each with the single argument <tt>stop</tt>,
<p>
These scripts should not fail obscurely when the
configuration files remain but the package has been
- removed, as the default in <prgn>dpkg</prgn> is to leave
- configuration files on the system after the package has
- been removed. Only when it is executed with the
- <tt>--purge</tt> option will dpkg remove configuration
- files. Therefore, you should include a <tt>test</tt>
- statement at the top of the script, like this:
+ removed, as configuration files remain on the system after
+ the package has been removed. Only when <prgn>dpkg</prgn>
+ is executed with the <tt>--purge</tt> option will
+ configuration files be removed. In particular, 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
+ 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></sect1>
+ test -f <var>program-executed-later-in-script</var> || exit 0
+ </example></p>
+ </sect1>
<sect1>
<heading>Managing the links</heading>
<p>
- A program is provided, <prgn>update-rc.d</prgn>, to make
- it easier for package maintainers to arrange for the
+ A program is provided, <prgn>update-rc.d</prgn>, to handle
+ the it easier for package maintainers to arrange for the
proper creation and removal of
- <tt>/etc/rc<var>n</var>.d</tt> symbolic links from their
+ <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>
<p>
You should use this script to make changes to
- <tt>/etc/rc<var>n</var>.d</tt> and <em>never</em> include
- any <tt>/etc/rc<var>n</var>.d</tt> symbolic links in the
- actual archive.</p>
+ <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>
<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 simply adding, moving, or removing the
- symbolic links in <tt>/etc/rc<var>n</var>.d</tt>.</p>
+ 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>
<p>
- To get the default behaviour for your package, put in your
+ To get the default behavior for your package, put in your
<tt>postinst</tt> script
<example>
- update-rc.d <var>package</var> default >/dev/null
+ update-rc.d <var>package</var> defaults >/dev/null
</example>
and in your <tt>postrm</tt>
<example>
<sect1>
- <heading>Boot-time initialisation</heading>
-
- <p>
- There is another directory, <tt>/etc/rc.boot</tt>, which
- contains scripts which are run once per machine boot.
- This facility is provided for initialisation of hardware
- devices, cleaning up of leftover files, and so forth.</p>
-
- <p>
- For example, the <prgn>kbd</prgn> package provides a
- script here for initialising the keyboard layout and
- console font and mode.</p>
-
- <p>
- The files in <tt>/etc/rc.boot</tt> should <em>not</em> be
- links into <tt>/etc/init.d</tt>--they should be the
- scripts themselves.</p>
-
- <p>
- <tt>rc.boot</tt> should <em>not</em> be used for starting
- general-purpose daemons and similar activities. This
- should be done using the <tt>rc<var>n</var>.d</tt> scheme,
- above, so that the services can be started and stopped
- cleanly when the runlevel changes or the machine is to be
- shut down or rebooted.</p></sect1>
-
-
- <sect1>
+ <heading>Boot-time initialization</heading>
+
+ <p>
+ There used to be another directory, <tt>/etc/rc.boot</tt>,
+ which contained scripts which were run once per machine
+ boot. This has been deprecated in favour of links from
+ <tt>/etc/rcS.d</tt> to files in <tt>/etc/init.d</tt> as
+ described in <ref id="/etc/init.d">. No packages may
+ 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> filesystem archive! <em>This will cause
+ <tt>.deb</tt> file system archive! <em>This will cause
problems!</em> You should 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
+ <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> <em>Do</em>,
- however, include the <tt>/etc/init.d</tt> scripts in
- conffiles. (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
- deinstalling 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>
+ problems!</em> <em>Do</em>, 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>
and having named running in all runlevels, it can say in
its <tt>postinst</tt>:
<example>
- update-rc.d bind default >/dev/null
+ update-rc.d bind defaults >/dev/null
</example>
And in its <tt>postrm</tt>, to remove the links when the
package is purged:
<heading>Cron jobs</heading>
<p>
- Packages may not touch the configuration file
+ Packages may not modify the configuration file
<tt>/etc/crontab</tt>, nor may they modify the files in
<tt>/var/spool/cron/crontabs</tt>.</p>
/etc/cron.weekly
/etc/cron.monthly
</example>
- As these directory names say, the files within them are executed on
- a daily, weekly, or monthly basis, respectively.</p>
-
+ 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 have to be
+ scripts (shell scripts, Perl scripts, etc.) so that they can
+ easily be modified by the local system administrator. In
+ addition, they must 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/<package-name></tt> tagged as
- configuration file. This file uses the same syntax as
- <tt>/etc/crontab</tt> and is processed by <prgn>cron</prgn>
- automatically. (Note, that scripts in the
+ 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>
- All files installed in any of these directories have to be
- scripts (shell scripts, Perl scripts, etc.) so that they can
- easily be modified by the local system administrator. In
- addition, they have to be registered as configuration
- file.</p>
-
+
<p>
- The scripts in these directories have to 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 the configuration files are
- kept on the system in this situation.</p></sect>
-
-
+ 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>Console messages</heading>
in the script. If you have more than one daemon to
start, you should do the following:
<example>
- echo -n "Starting remote filesystem services:"
+ 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
</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
- behaviour by saying
+ behavior by saying
<example>
echo -n "Doing something very useful..."
do_something
<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</ftppath>
+ or your local mirror. In addition, it is included in the
+ <tt>debian-policy</tt> package.
+ </p>
+
<p>
The Debian <tt>menu</tt> packages provides a unique
interface between packages providing applications and
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></sect>
-
+ 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</ftppath>
+ or your local mirror. In addition, it is included in the
+ <tt>debian-policy</tt> package.
+ </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).
+ </p>
+
+ <p>
+ Registration of MIME type handlers allows programs like mail
+ user agents and web browsers to to invoke these handlers to
+ view, edit or display MIME types they don't support
+ directly.
+ </p>
+ </sect>
+
<sect>
<heading>Keyboard configuration</heading>
<item><p>emacs: the help prefix</p></item>
</taglist>
- The interpretation of any keyboard events should be
- independent of the terminal that's used (either the console,
- X windows, rlogin/telnet session, etc.).</p>
+ 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>
<p>
The following list explains how the different programs
<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 behaviour
+ 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
</sect>
</chapt>
<chapt>
- <heading>Files</heading>
-
+ <heading>Files</heading>
+
+
+ <sect>
+ <heading>Binaries</heading>
- <sect>
- <heading>Binaries</heading>
-
- <p>
- It is not allowed that two packages install programs with
- different functionality but with the same filenames. (The
- case of two programs having the same functionality but
- different implementations is handled via `alternatives.')
- If this case happens, one of the programs has to be
- renamed. The maintainers should report this to the
- developers' mailing and try to find a consensus about
- which package will have to be renamed. If a consensus can
- not be reached, <em>both</em> programs must be
- renamed.</p>
-
- <p>
- Generally the following compilation parameters should be used:
- <example>
- CC = gcc
- CFLAGS = -O2 -g -Wall # sane warning options vary between programs
- LDFLAGS = # none
- install -s # (or use strip on the files in debian/tmp)
- </example></p>
-
- <p>
- Note that all installed binaries should be stripped,
- either by using the <tt>-s</tt> flag to
- <prgn>install</prgn>, or by calling <prgn>strip</prgn> on
- the binaries after they have been copied into
- <tt>debian/tmp</tt> but before the tree is made into a
- package.</p>
-
- <p>
- The <tt>-g</tt> flag is useful on compilation so that you
- have available a full set of debugging symbols in your
- built source tree, in case anyone should file a bug report
- involving (for example) a core dump.</p>
-
- <p>
- The <tt>-N</tt> flag should not be used. On a.out systems
- it may have been useful for some very small binaries, but
- for ELF it has no good effect.</p>
-
- <p>
+ <p>
+ It is not allowed that two packages install programs with
+ different functionality but with the same filenames. (The
+ case of two programs having the same functionality but
+ different implementations is handled via `alternatives.')
+ If this case happens, one of the programs has to be
+ renamed. The maintainers should report this to the
+ developers' mailing and try to find a consensus about
+ which package will have to be renamed. If a consensus can
+ not be reached, <em>both</em> programs must be
+ renamed.</p>
+
+ <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></p>
+
+ <p>
+ Note that by default all installed binaries should be stripped,
+ either by using the <tt>-s</tt> flag to
+ <prgn>install</prgn>, or by calling <prgn>strip</prgn> on
+ the binaries after they have been copied into
+ <tt>debian/tmp</tt> but before the tree is made into a
+ package.</p>
+
+ <p>
+ The <tt>-N</tt> flag should not be used. On a.out systems
+ it may have been useful for some very small binaries, but
+ for ELF it has no good effect.</p>
+
+ <p>
+ Debugging symbols are useful for error diagnosis, investigation
+ of core dumps (which may be submitted by users in bug reports),
+ or testing and developing the software. Therefore it is
+ recommended to support building the package with
+ debugging information through the following interface:
+ If the environment variable <tt>DEB_BUILD_OPTIONS</tt>
+ contains the string <tt>debug</tt>, compile the software with
+ debugging information (usually this involves adding the
+ <tt>-g</tt> flag to <tt>CFLAGS</tt>). This allows to generate
+ a build tree with debugging information. If the environment
+ variable <tt>DEB_BUILD_OPTIONS</tt> contains the
+ string <tt>nostrip</tt>, do not strip the files at installation
+ time. This allows to generate a package with debugging
+ information included. The following makefile snippet
+ is only an example how to test for either
+ condition:
+ <footnote>
+ <p>
+ Rationale: Building by default with -g causes more
+ wasted CPU cycles since the information is stripped away
+ anyway. The package can by default build without -g if
+ it also provides a mechanism to easily be rebuilt with
+ debugging information. This can be done by providing a
+ "build-debug" make target, or allowing the user to
+ specify "BUILD_DEBUG=yes" in the environment while
+ compiling that package.
+ </p>
+ <p>Now this has several added benefits:
+ <list>
+ <item>
+ <p>
+ It is actually easier to build debugging bins and
+ libraries this way (no more editing debian/rules
+ or similar) since it provides a documented way of
+ getting this type of build.</p>
+ </item>
+ <item>
+ <p>
+ There will be much less wasted cpu time for the
+ autobuilders since not having debugging
+ information (and hence also not having to strip
+ it) will increase the speed of compiles. This
+ skips an entire pass of the compiler,
+ </p>
+ </item>
+ </list>
+ </p>
+ </footnote>
+
+ <example>
+ CFLAGS = -O2 -Wall
+ INSTALL = install
+
+ ifneq (,$(findstring debug,$(DEB_BUILD_OPTIONS)))
+ CFLAGS += -g
+ ifneq (,$(findstring nostrip,$(DEB_BUILD_OPTIONS)))
+ INSTALL += -s
+ endif
+ endif
+ </example></p>
+
+ <p>
It is up to the package maintainer to decide what
compilation options are best for the package. Certain
binaries (such as computationally-intensive programs) may
<p>
Note that under some circumstances it may be useful to
install a shared library unstripped, for example when
- building a separate package to support debugging.</p>
-
- <p>
- Please make sure that you use only released versions of
- shared libraries to build your packages; otherwise other
- users will not be able to run your binaries
- properly. Producing source packages that depend on
- unreleased compilers is also usually a bad
- idea.</p></sect>
+ building a separate package to support debugging.
+ </p>
+
+ <p>
+ An ever increasing number of packages are using libtool to
+ do their linking. The latest GNU libtools (>= 1.3a) can take
+ advantage of the metadata in the installed libtool archive
+ files (`*.la'). The main advantage of libtool's .la files is
+ that it allows libtool to store and subsequently access
+ metadata with respect to the libraries it builds. libtool
+ will search for those files, which contain a lot of useful
+ information about a library (e.g. dependency libraries for
+ static linking). Also, they're <em>essential</em> for
+ programs using libltdl.
+ </p>
+
+ <p>
+ Certainly libtool is fully capable of linking against shared
+ libraries which don't have .la files, but being a mere shell
+ script it can add considerably to the build time of a
+ libtool using package if that shell-script has to derive all
+ this information from first principles for each library every
+ time it is linked. With the advent of libtool-1.4 (and to a
+ lesser extent libtool-1.3), the .la files will also store
+ information about inter-library dependencies which cannot
+ necessarily be derived after the .la file is deleted.
+ </p>
+
+ <p>
+ Packages that use libtool to create shared libraries must
+ include the <em>.la</em> files in the <em>-dev</em>
+ packages, with the exception that if the package relies on
+ libtool's <em>libltdl</em> library, in which case the .la
+ files must go in the run-time library package. This is a
+ good idea in general, and especially for static linking
+ issues.
+ </p>
+
+ <p>
+ Please make sure that you use only released versions of
+ shared libraries to build your packages; otherwise other
+ users will not be able to run your binaries
+ properly. Producing source packages that depend on
+ unreleased compilers is also usually a bad
+ idea.
+ </p>
+ </sect>
<sect>
<prgn>csh</prgn> and <prgn>tcsh</prgn> should be avoided
as scripting languages. See <em>Csh Programming
Considered Harmful</em>, one of the <tt>comp.unix.*</tt>
- FAQs. It can be found on <ftpsite>rtfm.mit.edu</ftpsite>
- in
- <ftppath>/pub/usenet-by-group/comp.unix.programmer/Csh_Programming_Considered_Harmful</ftppath>.
- If an upstream package comes with <prgn>csh</prgn> scripts
- then you must make sure that they start with
- <tt>#!/bin/csh</tt> and make your package depend on the
- <prgn>c-shell</prgn> virtual package.</p>
+ FAQs. It can be found on
+ <url id="http://language.perl.com/versus/csh.whynot">, or
+ <url id="http://www.cpan.org/doc/FMTEYEWTK/versus/csh.whynot">
+ or even on <ftpsite>ftp.cpan.org</ftpsite>
+ <ftppath>/pub/perl/CPAN/doc/FMTEYEWTK/versus/csh.whynot</ftppath>.
+ If an upstream package comes with <prgn>csh</prgn> scripts
+ then you must make sure that they start with
+ <tt>#!/bin/csh</tt> and make your package depend on the
+ <prgn>c-shell</prgn> virtual package.</p>
<p>
Any scripts which create files in world-writable
<heading>Symbolic links</heading>
<p>
- In general, symbolic links within a toplevel directory
+ In general, symbolic links within a top-level directory
should be relative, and symbolic links pointing from one
- toplevel directory into another should be absolute. (A
- toplevel directory is a sub-directory of the root
+ top-level directory into another should be absolute. (A
+ top-level directory is a sub-directory of the root
directory `/'.)</p>
<p>
Debian uses the serial devices
<tt>/dev/tty*</tt>. Programs using the old
<tt>/dev/cu*</tt> devices should be changed to use
- <tt>/dev/tty*</tt>.</p></sect>
-
+ <tt>/dev/tty*</tt>.</p>
+ </sect>
- <sect>
+ <sect id="config files">
<heading>Configuration files</heading>
-
+ <sect1>
+ <heading>Definitions</heading>
+ <p>
+ <taglist>
+ <tag>configuration file</tag>
+ <item><p>
+ A file that affects the operation of program, or
+ provides site- or host-specific information, or
+ otherwise customizes the behavior of program.
+ Typically, configuration files are intended to be
+ modified by the system administrator (if needed or
+ desired) to conform to local policy or provide more
+ useful site-specific behavior.</p>
+ </item>
+
+ <tag><tt>conffile</tt></tag>
+ <item><p>
+ A file listed in a package's <tt>conffiles</tt>
+ file, and is treated specially by <prgn>dpkg</prgn>
+ (see the <em>Debian Packaging Manual</em>).</p>
+ </item>
+ </taglist>
+ </p>
+
+ <p>
+ The distinction between these two is important; they are
+ not interchangeable concepts. Almost all
+ <tt>conffiles</tt> are configuration files, but many
+ configuration files are not <tt>conffiles</tt>.</p>
+
+ <p>
+ Note that a script that embeds configuration information
+ (such as most of the files in <tt>/etc/init.d</tt> and
+ <tt>/etc/cron.{daily,weekly,monthly}</tt>) is de-facto a
+ configuration file and should be treated as such.</p>
+ </sect1>
+
+ <sect1>
+ <heading>Location</heading>
<p>
Any configuration files created or used by your package
- should reside in <tt>/etc</tt>. If there are several you
- should consider creating a subdirectory named after your
- package.</p>
-
+ should reside in <tt>/etc</tt>. If there are several you
+ should consider creating a subdirectory of <tt>/etc</tt>
+ named after your package.</p>
+
<p>
- It is almost certain that any file in <tt>/etc</tt> that
- is in your package's filesystem archive should be listed
- in <prgn>dpkg</prgn>'s <tt>conffiles</tt> control area
- file. (See the <em>Debian Packaging
- Manual</em>).</p>
-
+ If your packages creates or uses configuration files
+ outside of <tt>/etc</tt>, and it is not feasible to modify
+ the package to use the <tt>/etc</tt>, you should still put
+ the files in <tt>/etc</tt> and create symbolic links to
+ those files from the location that the package
+ requires.</p>
+ </sect1>
+
+ <sect1>
+ <heading>Behavior</heading>
+ <p>
+ Configuration file handling must conform to the following
+ behavior:
+ <list>
+ <item>
+ <p>local changes must be preserved during a package
+ upgrade</p>
+ </item>
+ <item>
+ <p>configuration files should be preserved when the
+ package is removed, and only deleted when the
+ package is purged.</p>
+ </item>
+ </list></p>
+
+ <p>
+ The easy way to achieve this behavior is to make the
+ configuration file a <tt>conffile</tt>. This is
+ appropriate if it is possible to distribute a default
+ version that will work for most installations, although
+ some system administrators may choose to modify it. This
+ implies that the default version will be part of the
+ package distribution, and must not be modified by the
+ maintainer scripts during installation (or at any other
+ time).</p>
+
+ <p>
+ In order to ensure that local changes are preserved
+ correctly, no package may contain or make hard links to
+ conffiles.
+ <footnote>
+ <p>
+ Rationale: There are two problems with hard links.
+ The first is that some editors break the link while
+ editing one of the files, so that the two files may
+ unwittingly become different. The second is that
+ <prgn>dpkg</prgn> might break the hard link while
+ upgrading <tt>conffile</tt>s.
+ </p>
+ </footnote>
+
+ <p>
+ The other way to do it is to via the maintainer scripts.
+ In this case, the configuration file must not be listed as
+ a <tt>conffile</tt> and must not be part of the package
+ distribution. If the existence of a file is required for
+ the package to be sensibly configured it is the
+ responsibility of the package maintainer to write scripts
+ which correctly create, update, maintain and
+ remove-on-purge the file. These scripts must be idempotent
+ (i.e. must work correctly if <prgn>dpkg</prgn> needs to
+ re-run them due to errors during installation or removal),
+ must cope with all the variety of ways <prgn>dpkg</prgn>
+ can call maintainer scripts, must not overwrite or
+ otherwise mangle the user's configuration without asking,
+ must not ask unnecessary questions (particularly during
+ upgrades), and otherwise be good citizens.</p>
+
+ <p>
+ The scripts need not configure every possible option for
+ the package, but only those necessary to get the package
+ running on a given system. Ideally the sysadmin should not
+ have to do any configuration other than that done
+ (semi-)automatically by the <tt>postinst</tt> 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
+ configuration file does not already exist. In certain
+ cases it is useful for there to be an example or template
+ file which the maintainer scripts use. Such files should
+ be in <tt>/usr/share/doc</tt> if they are examples or
+ <tt>/usr/lib</tt> if they are templates, and should be
+ perfectly ordinary <prgn>dpkg</prgn>-handled files
+ (<em>not</em> <tt>conffiles</tt>).</p>
+
+ <p>
+ These two styles of configuration file handling <em>must
+ not be mixed</em>, for that way lies madness:
+ <prgn>dpkg</prgn> will ask about overwriting the file
+ every time the package is upgraded.</p>
+
+ </sect1>
+
+ <sect1>
+ <heading>Sharing configuration files</heading>
<p>
Only packages that are tagged <em>conflicting</em> with
each other may specify the same file as
- <tt>conffile</tt>. A package may not modify a
- configuration file of another package.</p>
-
+ <tt>conffile</tt>.</p>
+
<p>
- If two or more packages use the same configuration file,
- one of these packages has to be defined as <em>owner</em>
- of the configuration file, i.e., it has to list the file
- as <tt>conffile</tt> and has to provide a program that
- modifies the configuration file.</p>
-
+ The maintainer scripts should not alter the conffile of
+ <em>any</em> package, including the one the scripts belong
+ to.</p>
+
<p>
- The other packages have to depend on the <em>owner</em>
- package and use that program to update the configuration
- file.</p>
-
+ If two or more packages use the same configuration file
+ and it is reasonable for both to be installed at the same
+ time, one of these packages must be defined as
+ <em>owner</em> of the configuration file, i.e. it will be
+ the package to list that distributes the file and lists it
+ as a <tt>conffile</tt>. Other packages that use the
+ configuration file should depend on the owning package if
+ they require the configuration file to operate. If the
+ other package will use the configuration file if present,
+ but is capable of operating without it, no dependency need
+ be declared.</p>
+
<p>
- Sometimes it's appropriate to build a new package, which
- just provides the basic <em>infrastructure</em> for the
- other packages and which manages the shared configuration
- files. (Check out the <prgn>sgml-base</prgn> package as an
- example.)</p>
-
+ If it is desirable for two or more related packages to
+ share a configuration file <em>and</em> for all of the
+ related packages to be able to modify that configuration
+ file, then the following should done:
+ <enumlist>
+ <item>
+ <p>
+ have one of the related packages (the "core"
+ package) manage the configuration file with
+ maintainer scripts as described in the previous
+ section.</p>
+ </item>
+ <item><p>
+ the core package should also provide a program that
+ the other packages may use to modify the
+ configuration file.</p>
+ </item>
+ <item>
+ <p>
+ the related packages must use the provided program
+ to make any modifications to the configuration file.
+ They should either depend on the core package to
+ guarantee that the configuration modifier program is
+ available or accept gracefully that they cannot
+ modify the configuration file if it is not.</p>
+ </item>
+ </enumlist></p>
+
+ <p>
+ Sometimes it's appropriate to create a new package which
+ provides the basic infrastructure for the other packages
+ and which manages the shared configuration files. (Check
+ out the <tt>sgml-base</tt> package as an example.)</p>
+ </sect1>
+
+ <sect1>
+ <heading>User configuration files ("dotfiles")</heading>
+
<p>
Files in <tt>/etc/skel</tt> will automatically be copied
- into new user accounts by <prgn>adduser</prgn>. They
+ into new user accounts by <prgn>adduser</prgn>. They
should not be referenced there by any program.</p>
-
+
<p>
Therefore, if a program needs a dotfile to exist in
advance in <tt>$HOME</tt> to work sensibly that dotfile
should be installed in <tt>/etc/skel</tt> (and listed in
conffiles, if it is not generated and modified dynamically
by the package's installation scripts).</p>
-
+
<p>
However, programs that require dotfiles in order to
operate sensibly (dotfiles that they do not create
themselves automatically, that is) are a bad thing, and
programs should be configured by the Debian default
installation as close to normal as possible.</p>
-
+
<p>
Therefore, if a program in a Debian package needs to be
configured in some way in order to operate sensibly that
configuration should be done in a site-wide global
- configuration file elsewhere in <tt>/etc</tt>. Only if
- the program doesn't support a site-wide default
- configuration and the package maintainer doesn't have time
- to add it should a default per-user file be placed in
+ configuration file elsewhere in <tt>/etc</tt>. Only if the
+ program doesn't support a site-wide default configuration
+ and the package maintainer doesn't have time to add it
+ should a default per-user file be placed in
<tt>/etc/skel</tt>.</p>
-
+
<p>
<tt>/etc/skel</tt> should be as empty as we can make it.
This is particularly true because there is no easy
mechanism for ensuring that the appropriate dotfiles are
copied into the accounts of existing users when a package
is installed.</p>
-
- <p>
- Ideally the sysadmin should not have to do any
- configuration other than that done (semi-)automatically by
- the <tt>postinst</tt> script.</p>
+ </sect1>
</sect>
<sect>
<heading>Log files</heading>
-
+ <p>
+ The traditional approach to log files has been to set up ad
+ hoc log rotation schemes using simple shell scripts and
+ cron. While this approach is highly customizable, it
+ requires quite a lot of sysadmin work. Even though the
+ original Debian system helped a little by automatically
+ installing a system which can be used as a template, this
+ was deemed not enough.
+ </p>
+
+ <p>
+ A better scheme is to use logrotate, a GPL'd program
+ developed by Red Hat, which centralizes log management. It
+ has both a configuration file (<tt>/etc/logrotate.conf</tt>)
+ and a directory where packages can drop logrotation info
+ (<tt>/etc/logrotate.d</tt>).
+ </p>
+
<p>
Log files should usually be named
<tt>/var/log/<var>package</var>.log</tt>. If you have many
<p>
Make sure that any log files are rotated occasionally so
that they don't grow indefinitely; the best way to do this
- is to use <prgn>savelog</prgn> program in an
- <tt>/etc/cron.daily</tt>, <tt>/etc/cron.weekly</tt> or
- <tt>/etc/cron.monthly</tt> script. Here is a good example:
+ is to drop a script into the directory
+ <tt>/etc/logrotate.d</tt> and use the facilities provided by
+ logrotate. Here is a good example for a logrotate config
+ file (for more information see <manref name="logrotate"
+ section="8">):
<example>
- [ -d /var/log/apache/. ] || exit 0
- umask 022
- cd /var/log/apache
- if [ -fs access.log ]
- then
- savelog -c 7 access.log > /dev/null
- fi
- </example></p>
+ /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
+ rotation.
+
+ </p>
<p>
Make sure that any log files are removed when the package is
<p>
Note that changing the numeric value of an id associated with a name
- is very difficult, and involves searching the filesystem for all
+ is very difficult, and involves searching the file system for all
appropriate files. You need to think carefully whether a static or
dynamic id is required, since changing your mind later will cause
problems.</p>
<p>
If a package wants to install an example entry into
<tt>/etc/inetd.conf</tt>, the entry has to be preceded with
- exactly one hash character (#). Such lines are treated as
- `commented out by user' by the <prgn>update-inetd</prgn>
- script and are not changed or activated during a package
- updates.</p></sect>
+ exactly one hash character (<tt>#</tt>). Such lines are
+ treated as `commented out by user' by the
+ <prgn>update-inetd</prgn> script and are not changed or
+ activated during a package updates.</p></sect>
+
+ <sect>
+ <heading>Using pseudo-ttys and modifying wtmp, utmp and lastlog</heading>
+ <p>
+ Some programs need to create pseudo-ttys. This should be done
+ using Unix98 ptys if the C library supports it. The resulting
+ program must not be installed setuid root, unless that
+ is required for other functionality.
+ </p>
+
+ <p>
+ The files <tt>/var/run/utmp</tt>, <tt>/var/log/wtmp</tt> and
+ <tt>/var/log/lastlog</tt> must be installed writeable by
+ group utmp. Programs who need to modify those files must
+ be installed install setgid utmp.
+ </p>
+ </sect>
+
<sect>
<heading>Editors and pagers</heading>
Thus, every program that launches an editor or pager has to
use the EDITOR or PAGER environment variables to determine
the editor/pager the user wants to get started. If these
- variables are not set, the programs `/usr/bin/editor' and
- `/usr/bin/pager' have to be used, respectively.</p>
+ variables are not set, the programs <tt>/usr/bin/editor</tt>
+ and <tt>/usr/bin/pager</tt> have to be used, respectively.</p>
<p>
These two files are managed through `alternatives.' That is,
every package providing an editor or pager has to call the
- `update-alternatives' script to register these programs.</p>
+ <prgn>update-alternatives</prgn> script to register these
+ programs.</p>
<p>
If it is very hard to adapt a program to make us of the
EDITOR and PAGER variable, that program should be configured
- to use `/usr/bin/sensible-editor' and
- `/usr/bin/sensible-pager' as editor or pager program,
+ to use <tt>/usr/bin/sensible-editor</tt> and
+ <tt>/usr/bin/sensible-pager</tt> as editor or pager program,
respectively. These are two scripts provided in the Debian
base system that check the EDITOR and PAGER variables and
launches the appropriate program or falls back to
- `/usr/bin/editor' and `/usr/bin/pager', automatically.</p>
+ <tt>/usr/bin/editor</tt> and <tt>/usr/bin/pager</tt>,
+ automatically.</p>
+ <p>
+ A program may also use the VISUAL environment variable to
+ determine the user's choice of editor. If it exists, it
+ should take precedence over EDITOR. This is in fact what
+ <tt>/usr/bin/sensible-editor</tt> does.</p>
+
<p>
Since the Debian base system already provides an editor and
a pager program, there is no need for a package to depend on
<p>
Html documents for a package are stored in
- /usr/doc/<var>package</var> and can be referred to as
+ <tt>/usr/share/doc/<var>package</var></tt> but should
+ be accessed via symlinks as
+ <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>
<p>
Web Applications should try to avoid storing files in
the Web Document Root. Instead use the
- /usr/doc/<package> directory for documents and
+ /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>
<p>
The mail spool is <tt>/var/spool/mail</tt> and the interface
to send a mail message is <tt>/usr/sbin/sendmail</tt> (as
- per the FSSTND). The mail spool is part of the base system
+ per the FHS). The mail spool is part of the base system
and not part of the MTA package.</p>
<p>
- All Debian MUAs and MTAs have to use the <tt>maillock</tt>
- and <tt>mailunlock</tt> functions provided by the
- <tt>liblockfile</tt> packages to lock and unlock mail
- boxes. These functions implement a NFS-safe locking
- mechanism. (It is ok if MUAs and MTAs don't link against
- liblockfile but use a <em>compatible</em> mechanism. Please
- compare the mechanisms very carefully!)</p>
-
+ All Debian MUAs, MTAs, MDAs and other mailbox accessing
+ programs (like IMAP daemons) have to lock the mailbox in a
+ NFS-safe way. This means that <tt>fcntl()</tt> locking has
+ to be combined with dot locking. To avoid dead locks, a
+ program has to use <tt>fcntl()</tt> first and dot locking
+ after this or alternatively implement the two locking
+ methods in a non blocking way<footnote>
+ <p>
+ If it is not possible to establish both locks, the
+ system shouldn't wait for the second lock to be
+ established, but remove the first lock, wait a (random)
+ time, and start over locking again.</p>
+ </footnote>. Using the functions <tt>maillock</tt> and
+ <tt>mailunlock</tt> provided by the
+ <tt>liblockfile*</tt><footnote>
+ <p>
+ <tt>liblockfile</tt> version >>1.01</p>
+ </footnote> packages is the recommended way to realize this.
+ </p>
+
<p>
Mailboxes are generally 660 <tt><var>user</var>.mail</tt>
unless the user has chosen otherwise. A MUA may remove a
<p>
The location for the <prgn>rmail</prgn> program used by UUCP
for incoming mail is <tt>/usr/sbin/rmail</tt>, as per the
- F
SSTND. Likewise, <prgn>rsmtp</prgn>, for receiving
+ F
HS. Likewise, <prgn>rsmtp</prgn>, for receiving
batch-SMTP-over-UUCP, is in <tt>/usr/sbin/rsmtp</tt> if it
is supported.</p>
<sect>
- <heading>Programs for the X Windows system</heading>
+ <heading>Programs for the X Window System</heading>
<p>
- Some programs can be configured with or without support for
- X Windows. Typically these binaries produced when
- configured for X will need the X shared libraries to
- run.</p>
-
+ Some programs can be configured with or without support for the X
+ Window System. Typically, binaries produced with support for X
+ will need the X shared libraries to run.
+ </p>
+
<p>
Such programs should be configured <em>with</em> X support,
- and should declare a dependency on <tt>xlib6g</tt> (for the
- X11R6 libraries). Users who wish to use the program can
- install just the relatively small <tt>xlib6g</tt> package,
- and do not need to install the whole of X.</p>
-
+ and should declare a dependency on <tt>xlib6g</tt> (which
+ contains X shared libraries). Users who wish to use the
+ program can install just the relatively small
+ <tt>xfree86-common</tt> and <tt>xlib6g</tt> packages, and do
+ not need to install the whole of X.
+ <footnote>
+ <p>Note: With the release of the new X window System
+ version (4.X), there probably shall be a sweeping change
+ in the X Window System Policy in the future.</p>
+ </footnote>
+ </p>
+
<p>
Do not create two versions (one with X support and one
without) of your package.</p>
<p>
- <em>Application defaults</em> files have to be installed in
- the directory
- <tt>/usr/X11R6/lib/X11/app-defaults/</tt>. They are
- considered as part of the program code. Thus, they should
- not be modified and should not be tagged as
- <em>conffile</em>. If the local system administrator wants
- to customise X applications globally, the file
- <tt>/etc/X11/Xresources</tt> should be used.</p>
-
+ <em>Packages which provide an X server</em> that, directly or
+ indirectly, communicates with real input and display hardware
+ should declare in their control data that they provide the
+ virtual package <tt>xserver</tt>.
+ <footnote>
+ <p>
+ Rationale: implement current practice, and provide an
+ actual policy for usage of the "xserver" virtual package
+ which appears in the virtual packages list.
+ In a nutshell, X servers that interface directly with
+ the display and input hardware or via another subsystem
+ (e.g., GGI) should provide xserver. Things like Xvfb,
+ Xnest, and Xprt should not.
+ </p>
+ </footnote>
+ </p>
+
<p>
- If you package a program that requires a non-free Motif
- library, it would be good if you can provide a "foo-smotif"
- and a "foo-dmotif" package, containing a (against Motif
- libraries) statically and a dynamically linked version,
- respectively. This way, users without Motif can use the
- package too, while users that have Motif installed get the
- advantages of a dynamically linked version.</p>
-
+ <em>Packages that provide a terminal emulator</em> for the X
+ Window System which support a terminal type with a terminfo
+ description provided in the <tt>ncurses-base</tt> package
+ should declare in their control data that they provide the
+ virtual package <tt>x-terminal-emulator</tt>. They should
+ also register themselves as an alternative for
+ <tt>/usr/bin/x-terminal-emulator</tt>, with a priority of
+ 20.
+ </p>
+
+ <p>
+ <em>Packages that provide window managers</em> should declare in
+ their control data that they provide the virtual package
+ <tt>x-window-manager</tt>. They should also register themselves as an
+ alternative for <tt>/usr/bin/x-window-manager</tt>, with a priority
+ calculated as follows:
+ <list>
+ <item>Start with a priority of 20.</item>
+ <item>If the window manager supports the Debian menu system,
+ add 20 points if this support is available in the
+ package's default configuration (i.e., no
+ configuration files belonging to the system or user
+ have to be edited to activate the feature); if
+ configuration files must be modified, add only 10
+ points.</item>
+ <item>If the window manager permits the X session to be
+ restarted using a <em>different</em> window manager
+ (without killing the X server) in its default
+ configuration, add 10 points; otherwise add
+ none.</item>
+ </list>
+ </p>
+
<p>
- However, if your package works reliably with lesstif, you
- should package it with lesstif, and not with Motif at
- all.</p>
+ <em>Packages that provide fonts for the X Window System</em>
+ must do a number of things to ensure that they are both
+ available without modification of the X or font server
+ configuration, and that they do not corrupt files used by
+ other font packages to register information about themselves.
+ <enumlist>
+ <item>
+ Fonts of any type supported by the X Window System
+ should be be in a separate binary package from any
+ executables, libraries, or documentation (except that
+ specific to the fonts shipped); if a program or
+ library is <em>unusable</em> without one or more
+ specific fonts, the package containing the program or
+ library should declare a dependency on the package(s)
+ containing the font(s) it requires.
+ </item>
+ <item>
+ BDF fonts should be converted to PCF fonts with the
+ <tt>bdftopcf</tt> utility (available in the
+ <tt>xbase-clients</tt> package, <tt>gzip</tt>ped, and
+ placed in a directory that corresponds to their
+ resolution:
+ <list>
+ <item>
+ 100 dpi fonts should be placed in
+ <tt>/usr/X11R6/lib/X11/fonts/100dpi/</tt>.
+ </item>
+ <item>
+ 75 dpi fonts should be placed in
+ <tt>/usr/X11R6/lib/X11/fonts/75dpi/</tt>.
+ </item>
+ <item>
+ Character-cell fonts, cursor fonts, and other
+ low-resolution fonts should be placed in
+ <tt>/usr/X11R6/lib/X11/fonts/misc/</tt>.
+ </item>
+ </list>
+ </item>
+ <item>
+ Speedo fonts should be placed in
+ <tt>/usr/X11R6/lib/X11/fonts/Speedo/</tt>.
+ </item>
+ <item>
+ Type 1 fonts should be placed in
+ <tt>/usr/X11R6/lib/X11/fonts/Type1/</tt>. If font
+ metric files are available, they may be placed here as
+ well.
+ </item>
+ <item>
+ Subdirectories of <tt>/usr/X11R6/lib/X11/fonts/</tt>
+ other than those listed above should be neither created nor
+ used. (The <tt>PEX</tt> and <tt>cyrillic</tt> directories are
+ excepted for historical reasons, but installation of files into
+ these directories remains discouraged.)
+ </item>
+ <item>
+ Font packages may, instead of placing files directly in
+ the X font directories listed above, provide symbolic links in
+ the font directory which point to the files' actual location
+ in the filesystem. Such a location should comply with the
+ FHS.
+ </item>
+ <item>
+ Font packages should not contain both 75dpi and 100dpi
+ versions of a font. If both are available, they should be
+ provided in separate binary packages with "-75dpi" or "-100dpi"
+ appended to the names of the packages containing the
+ corresponding fonts.
+ </item>
+ <item>
+ Fonts destined for the <tt>misc</tt> subdirectory should
+ not be included in the same package as 75dpi or 100dpi fonts;
+ instead, they should be provided in a separate package with
+ "-misc" appended to its name.
+ </item>
+ <item>
+ 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>
+ <item>
+ <tt>fonts.dir</tt> files must not be provided at
+ all.
+ </item>
+ <item>
+ <tt>fonts.alias</tt> and <tt>fonts.scale</tt>
+ files, if needed, should be provided in the
+ directory
+ <tt>/etc/X11/fonts/<em>fontdir</em>/<em>package</em>.<em>extension</em></tt>,
+ where <em>fontdir</em> is the name of the
+ subdirectory of
+ <tt>/usr/X11R6/lib/X11/fonts/</tt> where the
+ package's corresponding fonts are stored (e.g.,
+ <tt>75dpi</tt> or <tt>misc</tt>),
+ <em>package</em> is the name of the package that
+ provides these fonts, and <em>extension</em> is
+ either <tt>scale</tt> or <tt>alias</tt>,
+ whichever corresponds to the file
+ contents.
+ </item>
+ </list>
+ </item>
+ <item>
+ Font packages must declare a dependency on
+ <tt>xbase-clients</tt> and, in the package
+ post-installation and post-removal scripts, invoke the
+ <tt>mkfontdir</tt> command on each directory into
+ which they installed fonts.
+ </item>
+ <item>
+ Font packages that provide one or more
+ <tt>fonts.scale</tt> files as described above must declare a
+ versioned dependency on <tt>xbase-clients (>=
+ 3.3.3.1-5)</tt> and invoke <tt>update-fonts-scale</tt> on each
+ directory into which they installed fonts
+ <em>before</em> invoking <tt>mkfontdir</tt> on that
+ directory. This invocation must occur in both the
+ post-installation and post-removal scripts.
+ </item>
+ <item>
+ Font packages that provide one or more
+ <tt>fonts.alias</tt> files as described above must
+ declare a versioned dependency on <tt>xbase-clients
+ (>= 3.3.3.1-5)</tt> and, in the package
+ post-installation and post-removal scripts, invoke
+ <tt>update-fonts-alias</tt> on each directory into
+ which they installed fonts.
+ </item>
+ <item>
+ Font packages must not provide alias names for the
+ fonts they include which collide with alias names already in
+ use by fonts already packaged.
+ </item>
+ <item>
+ Font packages must not provide fonts with the same XLFD
+ registry name as another font already packaged.
+ </item>
+ </enumlist>
+ </p>
+
+ <p>
+ <em>Application defaults</em> files must be installed in the
+ directory <tt>/usr/X11R6/lib/X11/app-defaults/</tt>. They should
+ not be registered as <em>conffile</em>s or otherwise treated as
+ configuration files. Customization of programs' X resources may
+ be supported with the provision of a file with the same name as
+ that of the package placed in the <tt>/etc/X11/Xresources/</tt>
+ directory, which should be registered as a <em>conffile</em>.
+ <em>Important:</em> packages that install files into the
+ <tt>/etc/X11/Xresources/</tt> directory <em>must</em> declare a
+ conflict with <tt>xbase (<< 3.3.2.3a-2)</tt>; if this is
+ not done it is possible for the installing package to destroy a
+ previously-existing <tt>/etc/X11/Xresources</tt> <em>file</em>
+ which had been customized by the system administrator.
+ <footnote>
+ <p>Rationale: clarifies the language to properly
+ address the package maintainer, not the system
+ administrator, as to how to manage
+ /etc/X11/Xresources.</p>
+ </footnote>
+ </p>
+
<p>
- Note, that packages that require non-free Motif libraries
- can't go into the main section. If your package is free
- otherwise, it should go into contrib. Otherwise it has to go
- into non-free.</p></sect>
+ <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 should
+ 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>
+ <em>Programs that require the non-DFSG-compliant OSF/Motif
+ library</em> should be compiled against and tested with
+ LessTif (a free re-implementation of Motif) instead. If the
+ maintainer judges that the program or programs do not work
+ sufficiently well with LessTif to be distributed and
+ supported, but do so when compiled against Motif, then two
+ versions of the package should be created; one linked
+ statically against Motif and with <tt>-smotif</tt> appended
+ to the package name, and one linked dynamically against
+ Motif and with <tt>-dmotif</tt> appended to the package
+ name. Both Motif-linked versions are dependent upon
+ non-DFSG-compliant software and thus cannot be uploaded to
+ the main distribution; if the software is itself
+ DFSG-compliant it may be uploaded to the contrib
+ distribution. While known existing versions of OSF/Motif
+ permit unlimited redistribution of binaries linked against
+ the library (whether statically or dynamically), it is the
+ package maintainer's responsibility to determine whether
+ this is permitted by the license of the copy of OSF/Motif in
+ his or her possession.
+ </p>
+ </sect>
<sect>
<heading>Games</heading>
<p>
- The permissions on /var/lib/games are 755
+ The permissions on /var/games are 755
<tt>root.root</tt>.</p>
<p>
security hole.</p>
<p>
- As described in the FSSTND, binaries of games should be
+ As described in the FHS, binaries of games should be
installed in the directory <tt>/usr/games</tt>. This also
- applies to games that use the X windows system. Manual pages
+ applies to games that use the X Window System. Manual pages
for games (X and non-X games) should be installed in
- <tt>/usr/man/man6</tt>.</p>
+ <tt>/usr/share/man/man6</tt>.</p>
</sect>
</chapt>
<p>
You must install manual pages in <prgn>nroff</prgn> source
- form, in appropriate places under <tt>/usr/man</tt>. You
- should only use sections 1 to 9 (see the FSSTND for more
+ form, in appropriate places under <tt>/usr/share/man</tt>. You
+ should only use sections 1 to 9 (see the FHS for more
details). You must <em>not</em> install a preformatted `cat
page'.</p>
<tt>debian/rules</tt> like this:
<example>
ln -s ../man7/undocumented.7.gz \
- debian/tmp/usr/man/man[1-9]/the_requested_manpage.[1-9].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
absolute filenames in <tt>.so</tt> directives. The filename
in a <tt>.so</tt> in a manpage should be relative to the
base of the manpage tree (usually
- <tt>/usr/man</tt>).</p></sect>
+ <tt>/usr/share/man</tt>).</p></sect>
<sect>
<heading>Info documents</heading>
<p>
- Info documents should be installed in <tt>/usr/info</tt>.
+ Info documents should be installed in <tt>/usr/share/info</tt>.
They should be compressed with <tt>gzip -9</tt>.</p>
<p>
file, in its post-installation script:
<example>
install-info --quiet --section Development Development \
- /usr/info/foobar.info
+ /usr/share/info/foobar.info
</example></p>
<p>
It is a good idea to specify a section for the location of
your program; this is done with the <tt>--section</tt>
switch. To determine which section to use, you should look
- at <tt>/usr/info/dir</tt> on your system and choose the most
+ at <tt>/usr/share/info/dir</tt> on your system and choose the most
relevant (or create a new section if none of the current
sections are relevant). Note that the <tt>--section</tt>
flag takes two arguments; the first is a regular expression
<p>
You must remove the entries in the pre-removal script:
<example>
- install-info --quiet --remove /usr/info/foobar.info
+ install-info --quiet --remove /usr/share/info/foobar.info
</example></p>
<p>
Any additional documentation that comes with the package can
be installed at the discretion of the package maintainer.
Text documentation should be installed in a directory
- <tt>/usr/doc/<var>package</var></tt>, where
+ <tt>/usr/share/doc/<var>package</var></tt>, where
<var>package</var> is the name of the package, and
compressed with <tt>gzip -9</tt> unless it is small.</p>
<p>
It is often a good idea to put text information files
(<tt>README</tt>s, changelogs, and so forth) that come with
- the source package in <tt>/usr/doc/<var>package</var></tt>
+ the source package in <tt>/usr/share/doc/<var>package</var></tt>
in the binary package. However, you don't need to install
the instructions for building and installing the package, of
course!</p>
</sect>
-
+
+ <sect id="usrdoc">
+ <heading>Accessing the documentation</heading>
+
+ <p>
+ Former Debian releases placed all additional documentation
+ in <tt>/usr/doc/<var>package</var></tt>. To realize a
+ smooth migration to
+ <tt>/usr/share/doc/<var>package</var></tt>, each package
+ must maintain a symlink <tt>/usr/doc/<var>package</var></tt>
+ that points to the new location of its documentation in
+ <tt>/usr/share/doc/<var>package</var></tt><footnote>These
+ symlinks will be removed in the future, but they have to be
+ there for compatibility reasons until all packages have
+ moved and the policy is changed accordingly.</footnote>.
+ The symlink must be created when the package is installed;
+ it cannot be contained in the package itself due to problems
+ 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>
+ 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>
+ </p>
+ </sect>
+
<sect>
<heading>Preferred documentation formats</heading>
<p>
If your package comes with extensive documentation in a
- markup format that can be converted to various other formats
+ mark up format that can be converted to various other formats
you should if possible ship HTML versions in a binary
package, in the directory
- <tt>/usr/doc/<var>appropriate package</var></tt> or its
+ <tt>/usr/share/doc/<var>appropriate package</var></tt> or its
subdirectories.
<footnote>
<p>The rationale: The important thing here is that HTML
<p>
Every package must be accompanied by a verbatim copy of its
copyright and distribution license in the file
- /usr/doc/<package-name>/copyright. This file must
+ /usr/share/doc/<package-name>/copyright. This file must
neither be compressed nor be a symbolic link.</p>
<p>
involved with its creation.</p>
<p>
- /usr/doc/<package-name> may be a symbolic link to a
- directory in /usr/doc only if two packages both come from
+ /usr/share/doc/<package-name> 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
because copyrights must be extractable by mechanical
<p>
Packages distributed under the UCB BSD license, the Artistic
license, the GNU GPL, and the GNU LGPL should refer to the
- files /usr/doc/copyright/BSD, /usr/doc/copyright/Artistic,
- /usr/doc/copyright/GPL, and /usr/doc/copyright/LGPL.</p>
+ files /usr/share/common-licenses/BSD,
+ /usr/share/common-licenses/Artistic,
+ /usr/share/common-licenses/GPL, and
+ /usr/share/common-licenses/LGPL.
+ <footnote>
+ <p>
+ Why "licenses" and not "copyright"? Because
+ <tt>/usr/doc/copyright</tt> used to contain all the
+ copyright files, plus the four common licenses GPL,
+ LGPL, Artistic and BSD. Now individual copyright files
+ for packages are no longer in a common directory. Once
+ <tt>/usr/doc/copyright</tt> is almost empty it makes
+ sense to rename "copyright" to "licenses"
+ </p>
+ <p>
+ Why "common-licenses" and not "licenses"? Because if I
+ put just "licenses" I'm sure I will receive a bug report
+ saying "license foo is not included in the licenses
+ directory. They are not all the licenses, just a few
+ common ones. I could use /usr/share/doc/common-licenses
+ but I think this is too long, and, after all, the GPL
+ does not "document" anything, it is merely a license.
+ </p>
+ </footnote>
+ </p>
<p>
Do not use the copyright file as a general <tt>README</tt>
file. If your package has such a file it should be
- installed in <tt>/usr/doc/<var>package</var>/README</tt> or
+ installed in <tt>/usr/share/doc/<var>package</var>/README</tt> or
<tt>README.Debian</tt> or some other appropriate place.</p>
</sect>
<p>
Any examples (configurations, source files, whatever),
should be installed in a directory
- <tt>/usr/doc/<var>package</var>/examples</tt>. These files
- should not be referenced by any program--they're there for
- the benefit of the system administrator and users, as
- documentation only.</p>
+ <tt>/usr/share/doc/<var>package</var>/examples</tt>. These
+ files should not be referenced by any program--they're there
+ for the benefit of the system administrator and users, as
+ documentation only. Architecture-specific example files
+ should be installed in a directory
+ <tt>/usr/lib/<var>package</var>/examples</tt>, and files in
+ <tt>/usr/share/doc/<var>package</var>/examples</tt> symlink
+ to files in it. Or the latter directory may be a symlink to
+ the former.</p>
</sect>
<sect id="instchangelog">
<tt>debian/changelog</tt> file from your Debian source tree,
and a copy of the upstream changelog file if there is one.
The debian/changelog file should be installed in
- <tt>/usr/doc/<var>package</var></tt> as
+ <tt>/usr/share/doc/<var>package</var></tt> as
<tt>changelog.Debian.gz</tt>. If the upstream changelog
- file is text formatted, it must be accessable as
- <tt>/usr/doc/<var>package</var>/changelog.gz</tt>. If the
- upstream changelog file is HTML formatted, it must be
- accessable as <tt>/usr/doc/<var>package</var>/changelog.html.gz</tt>.
- If the upstream changelog files do not already conform to
- this naming convention, then this may be achieved by either
- renaming the files or adding a symbolic link at the
- packaging developer's discretion. </p>
+ file is text formatted, it must be accessible as
+ <tt>/usr/share/doc/<var>package</var>/changelog.gz</tt>. If
+ the upstream changelog file is HTML formatted, it must be
+ accessible as
+ <tt>/usr/share/doc/<var>package</var>/changelog.html.gz</tt>.
+ A plain text version of the changelog must be accessible as
+ <tt>/usr/doc/<var>package</var>/changelog.gz</tt> (this can
+ be created by <tt>lynx -dump -nolist</tt>). If the upstream
+ changelog files do not already conform to this naming
+ convention, then this may be achieved by either renaming the
+ files or adding a symbolic link at the packaging developer's
+ discretion.
+ <footnote>
+ <p>
+ Rationale: People should not have to look into two
+ places ofr upstream changelogs merely because they are
+ in HTML format.
+ </p>
+ </footnote>
+ </p>
<p>
Both should be installed compressed using <tt>gzip -9</tt>,
the Debian changelog and the upstream one because there is
no separate upstream maintainer then that changelog should
usually be installed as
- <tt>/usr/doc/<var>package</var>/changelog.gz</tt>; if there
- is a separate upstream maintainer, but no upstream
+ <tt>/usr/share/doc/<var>package</var>/changelog.gz</tt>; if
+ there is a separate upstream maintainer, but no upstream
changelog, then the Debian changelog should still be called
<tt>changelog.Debian.gz</tt>.</p>
</sect>
projects / debian / debian-policy.git / blobdiff