<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>
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/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/debian-policy/"
- name="&urlname"></p>
+ 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>
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>
</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 specialized
+ <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 does 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>
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
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>
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>
The location of all installed files and directories must
- comply (with some exceptions
- <footnote>
- <p>In an as yet unreleased version of the standard, the
- location of the mail spool and state information
- directories has changed; and we propose to follow the
- latter, since that would mean that we do not have to
- move things around again when the new version of the
- FHS comes around). The changes are, amongst others,
- s%/var/mail%/var/spool/mail% and
- s%/var/state%/var/lib%</p>
- </footnote>
- ) with the Linux File system Hierarchy Standard
+ comply with the Linux File system Hierarchy Standard
(FHS). 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>.
+ <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 FHS coordinator, at
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>
<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><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 behavior for your package, put in your
<sect1>
<heading>Boot-time initialization</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 initialization 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 initializing 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>
+ <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>
<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
- 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>
+ 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>
<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>
<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.
+ <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>
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>
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
+ 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>
An ever increasing number of packages are using libtool to
do their linking. The latest GNU libtools (>= 1.3a) can take
- advantage of the nmetadata in the installed libtool archive
+ 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
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 file system 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>
<p>
A better scheme is to use logrotate, a GPL'd program
developed by Red Hat, which centralizes log management. It
- has both a config file (<tt>/etc/logrotate.conf</tt>) and a
- directory where packages can drop logrotation info
+ 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>
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>
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/share/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>
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
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.</p>
+ 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>s. If the local system administrator wants
- to customize X applications globally, a file with the same
- name as that of the package should be placed in the
- <tt>/etc/X11/Xresources/</tt> directory instead.
+ <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>
+ <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>
+ <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
- package to destroy a previously-existing
- <tt>/etc/X11/Xresources</tt> <em>file</em>.</p>
-
- <p>
- No package should ever install files into the directories
- <tt>/usr/bin/X11/</tt>, <tt>/usr/doc/X11/</tt>,
- <tt>/usr/include/X11/</tt>, or <tt>/usr/lib/X11/</tt>; these
- directories are actually symbolic links, which <tt>dpkg</tt>
- does not follow when unpacking a package. Instead, use
- <tt>/usr/X11R6/bin/</tt>, <tt>/usr/share/doc/package/</tt>
- (i.e., place files with the rest of your package's
- documentation), <tt>/usr/X11R6/include/</tt>, and
- <tt>/usr/X11R6/lib/</tt>. This restriction governs only the
- paths used by the package as it is unpacked onto the system;
- it is permissible, and even preferable, for files within a
- package (shell scripts, for instance) to refer to the
- <tt>/usr/{bin,include,lib}/X11/</tt> directories rather than
- their <tt>/usr/X11R6/</tt> counterparts -- this way they do
- not have to be modified in the event that the X Window
- System packages install their files into a different
- directory in the future.</p>
+ <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>
- If you package a program that requires the (non-free)
- OSF/Motif library, you should try to determine whether the
- programs works reasonably well with the free
- re-implementation of Motif called LessTif. If so, build the
- package using the LessTif libraries; it can then go into the
- main section of the package repository and become an
- official part of the Debian distribution.</p>
-
- <p>
- If however, the Motif-based program works insufficiently
- well with LessTif, you should instead provide "-smotif" and "-dmotif"
- versions (appending these identifiers to the name of the
- package), which are statically and dynamically linked
- against the Motif libraries, respectively. (All known
- versions of OSF/Motif permit redistribution of
- statically-linked binaries using the library, but check the
- license on your copy of Motif to be sure.) This two-package
- approach allows users without Motif to use the package,
- whereas users with Motif installed can enjoy the advantages
- of the dynamically-linked version (a considerable savings in
- disk space usage, download time, etc.). Neither "-smotif"
- nor "-dmotif" packages can go into the main section; if the
- licensing on the package is compatible with the Debian Free
- Software Guidelines, it may go into the contrib section;
- otherwise it must go into the non-free section.
+
+ <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 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>
<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>
<p>
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 Window 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/share/man/man6</tt>.</p>
</sect>
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>
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 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">
the upstream changelog file is HTML formatted, it must be
accessible as
<tt>/usr/share/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>
+ 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>,
projects / debian / debian-policy.git / blobdiff