<!entity % versiondata SYSTEM "version.ent"> %versiondata;
]>
<debiandoc>
-<!--
- Debian GNU/Linux Policy Manual.
- Copyright (C)1996,1997,1998 Ian Jackson and Christian Schwarz;
- released under the terms of the GNU
- General Public License, version 2 or (at your option) any later.
- Initial version 1996, Ian Jackson, ijackson@gnu.ai.mit.edu
- Revised November 27, 1996, David A. Morris, bweaver@debian.org
- New sections March 15, 1997, Christian Schwarz, schwarz@debian.org
- Reworked/Restructured April-July 1997, Christian Schwarz, schwarz@debian.org
- Maintainer since 1997, Christian Schwarz, schwarz@debian.org
- Christoph Lameter contributed the "Web Standard"
- -->
-
-<book>
-
-<title>Debian Policy Manual
-<author>Ian Jackson <email/ijackson@gnu.ai.mit.edu/
-<author>Christian Schwarz <email/schwarz@debian.org/
-<author>revised: David A. Morris <email/bweaver@debian.org/
-<version>version &version;, &date;
-
-<abstract>
-This manual describes the policy requirements for the Debian 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.
-</abstract>
-
-<copyright>Copyright ©1996,1997,1998 Ian Jackson and Christian Schwarz.
-<p>
-
-This manual is free software; you may redistribute it and/or modify it
-under the terms of the GNU General Public License as published by the
-Free Software Foundation; either version 2, or (at your option) any
-later version.
-<p>
-
-This is distributed in the hope that it will be useful, but
-<em>without any warranty</em>; without even the implied warranty of
-merchantability or fitness for a particular purpose. See the GNU
-General Public License for more details.
-<p>
-
-A copy of the GNU General Public License is available as
-<tt>/usr/doc/copyright/GPL</tt> in the Debian GNU/Linux
-distribution or on the World Wide Web at
-<url id="http://www.gnu.org/copyleft/gpl.html">. You can also obtain it
-by writing to the Free Software Foundation, Inc., 59 Temple Place -
-Suite 330, Boston, MA 02111-1307, USA.
-<p>
-
-<toc sect>
-
-<chapt id="scope">About this manual
-<p>
-
-<sect>Scope
-<p>
-
-This manual describes the policy requirements for the Debian 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.
-<p>
-
-This manual does <em/not/ describe the technical 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>.
-<p>
-
-This document assumes familiarity with these other two manuals.
-Unfortunately, the <em>System Administrators' Manual</em> does not
-exist yet.
-<p>
-
-Much of the information presented in this manual will be useful even
-when building a package which is to be distributed in some other way
-or is for local use.
-<p>
-
-<sect>New versions of this document
-<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">
-or from the Debian WWW server at
-<url id="http://www.debian.org/doc/manuals/debian-policy/">
-<p>
-
-There is also a home page for the <em>Debian Policy Manual</em> that
-contains links to the current development version of this document as
-well as an archive of old versions. The URL is
-<url id="http://fatman.mathematik.tu-muenchen.de/~schwarz/debian-policy/">
-<p>
-
-In addition, this manual is distributed via the Debian package
-<tt>debian-policy</tt>
-<p>
-
-<sect>Feedback
-<p>
-
-As the Debian GNU/Linux system is continuously evolving this manual is
-changed from time to time.
-<p>
-
-While the authors of this document tried hard not to include any typos
-or other errors these still occur. If you discover an error in this
-manual or if you want to tell us any comments, suggestions, or critics
-please send an email to the Debian Policy Manager, Christian
-Schwarz <email>schwarz@debian.org</email>, the developers' mailing
-list <email>debian-devel@lists.debian.org</email>, or submit a bug report
-against the <tt>debian-policy</tt> package.
-<p>
-
-<chapt>The Debian Archive
-<p>
-
-The Debian GNU/Linux system is maintained and distributed as a
-collection of <em>packages</em>. Since there are so many of them (over
-1000) they are split into <em>sections</em> and <em>priorities</em> to
-simplify handling of them.
-<p>
-
-The effort of the Debian project is to build a free operating system,
-but not every package we want to make accessible is <em>free</em> in
-our sense (see Debian Free Software Guidelines, below), or may be
-imported/exported without restrictions. Thus, the archive is split
-into the sections <em/main/, <em/non-us/, <em/non-free/, and
-<em/contrib/.
-<p>
-
-The <em/main/ section forms the <em>Debian GNU/Linux distribution</em>.
-<p>
-
-Packages in the other sections are not considered as part of the
-Debian distribution, though we support their use, and we provide
-infrastructure for them (such as our bug-tracking system and mailing
-lists). This Debian Policy Manual applies to these packages as well.
-<p>
-
-<sect id="pkgcopyright">Package copyright and sections
-<p>
-
-The aims of this policy are:
-<p>
-
-<list compact>
-<item>
-We want to make as much software available as we can.<p>
-<item>
-We want to encourage everyone to write free software.<p>
-<item>
-We want to make it easy for people to produce CD-ROMs of our system
-without violating any licenses, import/export restrictions, or any
-other laws.<p>
-</list>
-<p>
-
-<sect1>The Debian Free Software Guidelines
-<p>
-
-The Debian Free Software Guidelines (DFSG) as is our definition of `free'
-software.
-<p>
-
-<enumlist>
-<item>Free Redistribution
-<p>
-The license of a Debian component may not restrict any party from
-selling or giving away the software as a component of an aggregate
-software distribution containing programs from several different
-sources. The license may not require a royalty or other fee for such
-sale.
-<p>
-
-<item>Source Code
-<p>
-
-The program must include source code, and must allow distribution in
-source code as well as compiled form.
-<p>
-
-<item>Derived Works
-<p>
-
-The license must allow modifications and derived works, and must allow
-them to be distributed under the same terms as the license of the original
-software.
-<p>
-
-<item>Integrity of The Author's Source Code
-<p>
-
-The license may restrict source-code from being distributed in modified
-form <em/only/ if the license allows the distribution of ``patch files''
-with the source code for the purpose of modifying the program at build
-time. The license must explicitly permit distribution of software built
-from modified source code. The license may require derived works to
-carry a different name or version number from the original software.
-(This is a compromise. The Debian group encourages all authors to not
- restrict any files, source or binary, from being modified.)
-<p>
-
-<item>No Discrimination Against Persons or Groups
-<p>
-
-The license must not discriminate against any person or group of
-persons.
-<p>
-
-<item>No Discrimination Against Fields of Endeavor
-<p>
-
-The license must not restrict anyone from making use of the program
-in a specific field of endeavor. For example, it may not restrict the
-program from being used in a business, or from being used for genetic
-research.
-<p>
-
-<item>Distribution of License
-<p>
-
-The rights attached to the program must apply to all to whom the
-program is redistributed without the need for execution of an
-additional license by those parties.
-<p>
-
-<item>License Must Not Be Specific to Debian
-<p>
-
-The rights attached to the program must not depend on the program's
-being part of a Debian system. If the program is extracted from Debian
-and used or 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 rights as those that are granted in conjunction with
-the Debian system.
-<p>
-
-<item>License Must Not Contaminate Other Software
-<p>
-
-The license must not place restrictions on other software that is
-distributed along with the licensed software. For example, the
-license must not insist that all other programs distributed on the
-same medium must be free software.
-<p>
-
-<item>Example Licenses
-<p>
-The ``GPL,'' ``BSD,'' and ``Artistic'' licenses are examples of licenses
-that we consider <em/free/.
-
-</enumlist>
-<p>
-
-<sect1>The main section
-<p>
-
-Every package in "main" must comply with the DFSG (Debian Free
-Software Guidelines).
-<p>
-
-In addition, the packages in "main"
-<p>
-
-<list compact>
-<item>must not require a package outside of "main" for compilation or
-execution (thus, the package may not declare a "Depends" or
-"Recommends" relationship on a non-main package),
-<p>
-<item>must not be so buggy that we refuse to support them,
-<p>
-<item>must meet all policy requirements presented in this manual.
-</list>
-<p>
-
-<sect1>The contrib section
-<p>
-
-Every package in "contrib" must comply with the DFSG.
-<p>
-
-Examples of packages which would be included in "contrib" are
-<p>
-<list compact>
-<item>free packages which require "contrib", "non-free", or "non-US"
- packages or packages which are not in our archive at all for
- compilation or execution,
-<p>
-<item>wrapper packages or other sorts of free accessories for
- non-free programs,
-<p>
-<item>packages which we don't want to support because they are too
- buggy, and
-<p>
-<item>packages which fail to meet some other policy requirements in
- a serious way.
-</list>
-<p>
-
-<sect1>The non-free section
-<p>
-
-`Non-free' contains packages which are not compliant with the DFSG
-or which are encumbered by patents or other legal issues that make
-their distribution problematic.
-<p>
-
-All packages in `non-free' must be electronically distributable across
-international borders.
-<p>
-
-<sect1>The non-us server
-<p>
-
-Some programs with cryptographic program code must be stored on the
-"non-us" server because of export restrictions of the U.S.
-<p>
-
-This applies only to packages which contain cryptographic code. A package
-containing a program with an interface to a cryptographic program or a
-program that's dynamically linked against a cryptographic library can be
-distributed if it is capable of running without the cryptography library
-or program.
-<p>
-
-<sect1>Further copyright considerations
-<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 id="copyrightfile">
-for details).
-<p>
-
-We reserve the right to restrict files from being included anywhere in
-our archives if
-<p>
-<list compact>
-<item>their use or distribution would break a law,
-<p>
-<item>there is an ethical conflict in their distribution or use,
-<p>
-<item>we would have to sign a license for them, or
-<p>
-<item>their distribution would conflict with other project policies.
-</list>
-<p>
-
-Programs whose authors encourage the user to make donations are fine
-for the main distribution, provided that the authors do not claim that
-not donating is immoral, unethical, illegal or something similar;
-otherwise they must go in contrib (or non-free, if even distribution
-is restricted by such statements).
-<p>
-
-Packages whose copyright permission notices (or patent problems) do
-not allow redistribution even of only binaries, and where no special
-permission has been obtained, cannot be placed on the Debian FTP site and
-its mirrors at all.
-<p>
-
-Note, that under international copyright law (this applies in
-the United States, too) <em/no/ distribution or
-modification of a work is allowed without an explicit notice saying
-so. Therefore a program without a copyright notice <em/is/
-copyrighted and you may not do anything to it without risking being
-sued! Likewise if a program has a copyright notice but no statement
-saying what is permitted then nothing is permitted.
-<p>
-
-Many authors are unaware of the problems that restrictive copyrights
-(or lack of copyright notices) can cause for the users of their
-supposedly-free software. It is often worthwhile contacting such
-authors diplomatically to ask them to modify their license
-terms. However, this is a politically difficult thing to do and you
-should ask for advice on <tt/debian-devel/ first.
-<p>
-
-When in doubt, send mail to <email/debian-devel@lists.debian.org/. Be
-prepared to provide us with the copyright statement. Software covered
-by the GPL, public domain software and BSD-like copyrights are safe;
-be wary of the phrases `commercial use prohibited' and `distribution
-restricted'.
-<p>
-
-<sect1>Subsections
-<p>
-
-The packages in the <em/main/, <em/contrib/, and <em/non-free/
-sections are grouped further into <em>subsections</em> to simplify
-handling of them.
-<p>
-
-The section for each package is specified in the package's <em>control
-record</em>. However, the maintainer of the Debian archive may
-override this selection to assure the consistency of the Debian
-distribution.
-<p>
-
-Please check the current Debian distribution to see which sections are
-available.
-<p>
-
-<sect>Priorities
-<p>
-
-Each package is given a certain <em>priority</em> value, which is
-included in the package's <em>control
-record</em>. This information is used in the Debian package management
-tool to separate high-priority packages from less-important packages.
-<p>
-
-The following <em>priority levels</em> are supported by the Debian
-package management system, <prgn/dpkg/.
-<p>
-
-<taglist>
-<tag><tt/required/
-<item>
-<tt/required/ packages are necessary for the proper functioning of the
-system. You must not remove these packages or your system may become
-totally broken and you may not even be able to use
-<prgn/dpkg/ to put things back. Systems with only the <tt/required/
-packages are probably unusable, but they do have enough functionality
-to allow the sysadmin to boot and install more software.
-
-<tag><tt/important/
-<item>
-Important programs, including those which one would expect to find on
-any Unix-like system. If the expectation is that an experienced Unix
-person who found it missing would say `What the F*!@<+ is going on,
-where is <prgn/foo/', it should be in <tt/important/. 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/
-include Emacs or X11 or TeX or any other large applications. The
-<tt/important/ packages are just a bare minimum of commonly-expected
-and necessary tools.
-
-<tag><tt/standard/
-<item>
-These packages provide a reasonably small but not too limited
-character-mode system. This is what will install by default if the
-user doesn't select anything else. It doesn't include many large
-applications, but it does include Emacs (this is more of a piece of
-infrastructure than an application) and a reasonable subset of TeX and
-LaTeX (if this is possible without X).
-
-<tag><tt/optional/
-<item>
-(In a sense everything is optional that isn't 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.
-
-<tag><tt/extra/
-<item>
-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 requirements.
-
-</taglist>
-<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.
-<p>
-
-<sect>Binary packages
-<p>
-
-The Debian GNU/Linux distribution is based on the Debian package
-management system, called <prgn/dpkg/. Thus, all packages in the
-Debian distribution have to be provided in the <tt/.deb/ file format.
-<p>
-
-<sect1>The package name
-<p>
-
-Every package must have a name that's unique within the Debian
-archive.
-<p>
-
-Package names may only consist of lower case letters, digits (0-9),
-plus (+) or minus (-) signs, and periods (.).
-<p>
-
-The package name is part of the file name of the <tt/.deb/ file and is
-included in the control field information.
-<p>
-
-<sect1>The maintainer of a package
-<p>
-
-Every package must have exactly one maintainer at a time. This person
-is responsible that the license of the package's software complies with
-the policy of the distribution this package is included in.
-<p>
-
-The maintainer must be specified in the <tt/Maintainer/ control field
-with the correct name and a working email address for the Debian
-maintainer of the package. If one person maintains several packages
-he/she should try to avoid having different forms of their name and
-email address in different <tt/Maintainer/ fields.
-<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>.
-<p>
-
-<sect1>The description of a package
-<p>
-
-Every Debian package should have an extended description stored in the
-appropriate field of the control record.
-<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>
-
-<sect1>Dependencies
-<p>
-
-Every package has to specify the dependency information about other
-packages, that are required for the first to work correctly.
-<p>
-
-For example, for any shared libraries required by dynamically-linked
-executable binary in a package a dependency entry has to be provided.
-<p>
-
-It is not necessary for other packages to declare any dependencies
-they have on other packages which are marked <tt/Essential/ (see below).
-<p>
-
-Sometimes, a package requires another package to be installed
-<em>and</em> configured before it can be installed. In this case,
-you'll have to specify a <tt/Pre-Depends/ entry for the package.
-<p>
-
-You must not specify a <tt/Pre-Depends/ entry for a package before
-this has been discussed on the <tt/debian-devel/ mailing list and a
-consensus about doing that has been reached.
-<p>
-
-<sect1>Virtual packages
-<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 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 function
-will then <em>provide</em> the virtual package. Thus, any other
-package requiring that function can simply depend on the virtual
-package without having to specify all possible packages individually.
-<p>
-
-All packages must use virtual package names where appropriate, and
-arrange to create new ones if necessary. They must not use virtual
-package names (except privately, amongst a cooperating group of
-packages) unless they have been agreed upon and appear in the list of
-virtual package names.
-<p>
-
-The latest version of the authoritative list of virtual package names
-can be found on <ftpsite>ftp.debian.org</> in
-<ftppath>/debian/doc/package-developer/virtual-package-names-list.text</>
-or your local mirror. In addition, it is included in the
-<tt>debian-policy</tt> package. The procedure for updating the list is
-described at the top of the file.
-<p>
-
-<sect1>Base packages
-<p>
-
-The packages included in the <tt/base/ section have a special
-function. They form a minimum subset of the Debian GNU/Linux system
-that is installed before everything else on a new system. Thus, only
-very few packages are allowed to go into the <tt/base/ section to keep
-the required disk usage very small.
-<p>
-
-Most of these packages should have the priority value <tt/required/ or
-at least <tt/important/, and many of them will be tagged
-<tt/essential/ (see below).
-<p>
-
-You must not place any packages into the <tt/base/ section before this
-has been discussed on the <tt/debian-devel/ mailing list and a
-consensus about doing that has been reached.
-<p>
-
-<sect1>Essential packages
-<p>
-
-Some packages are tagged <tt/essential/. (They have <tt/Essential:
-yes/ in their package control record.) This flag is used for packages
-that are <em>essential</em> for a system.
-<p>
-
-Since these packages can not easily be removed (you'll have to specify
-an extra <em>force option</em> to <prgn/dpkg/) this flag should only
-be used where absolutely necessary.
-
-A shared library package should 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>
-
-You must not tag any packages <tt/essential/ before this has been
-discussed on the <tt/debian-devel/ mailing and a consensus about doing
-that has been reached.
-<p>
-
-<sect1>Maintainer scripts
-<p>
-
-The package installation scripts should avoid producing output which
-it is unnecessary for the user to see and should rely on <prgn/dpkg/
-to stave off boredom on the part of a user installing many packages.
-This means, amongst other things, using the <tt/--quiet/ option on
-<prgn/install-info/.
-<p>
-
-Packages should try to minimise 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</> and
-<tt>/etc/nntpserver</>), rather than each prompting for their own list
-of required pieces of information.
-<p>
-
-It also means that an upgrade should not ask the same questions again,
-unless the user has used <tt/dpkg --purge/ to remove the package's
-configuration. The answers to configuration questions should be
-stored in an appropriate place in <tt>/etc</> so that the user can
-modify them, and how this has been done should be documented.
-<p>
-
-If a package has a vitally important piece of information to pass to
-the user (such as "don't run me as I am, you must edit the following
-configuration files first or you risk your system emitting
-badly-formatted messages"), it should display this in the
-<prgn/postinst/ script 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/copyright</>); neither do
-instructions on how to use a program (these should be in on line
-documentation, where all the users can see them).
-<p>
-
-Any necessary prompting should almost always be confined to the
-post-installation script, and should be protected with a conditional
-so that unnecessary prompting doesn't happen if a package's
-installation fails and the <prgn/postinst/ is called with
-<tt/abort-upgrade/, <tt/abort-remove/ or <tt/abort-deconfigure/.
-<p>
-
-Errors which occur during the execution of an installation script
-<em/must/ be checked and the installation <em/must not/ continue after
-an error.
-<p>
-
-Note, that <ref id="scripts">, in general applies to package
-maintainer scripts, too.
-<p>
-
-Do not use <prgn/dpkg-divert/ on a file belonging to another package
-without consulting the maintainer of that package first.
-<p>
-
-In order for <prgn/update-alternatives/ to work 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/ to force
-the deinstallation of other packages supplying it which do not (yet)
-use <prgn/update-alternatives/. It may in this case be appropriate to
-specify a conflict on earlier versions on something--this is an
-exception to the usual rule that this is not allowed.
-<p>
-
-<sect>Source packages
-<p>
-
-<sect1>Standards conformance
-<p>
-
-You should specify the most recent version of the packaging standards
-with which your package complies in the source package's
-<tt/Standards-Version/ field.
-<p>
-
-This value will be used to file bug reports automatically if your
-package becomes too much out of date.
-<p>
-
-The value corresponds to a version of the Debian manuals, as can be
-found on the title page or page headers and footers (depending on the
-format).
-<p>
-
-The version number has four components--major and minor number and
-major and minor patch level. When the standards change in a way that
-requires every package to change the major number will be changed.
-Significant changes that will require work in many packages will be
-signaled by a change to the minor number. The major patch level will
-be changed for any change to the meaning of the standards, however
-small; the minor patch level will be changed when only cosmetic,
-typographical or other edits which do not change the meaning are made,
-or changes which do not affect the contents of packages.
-<p>
-
-You should regularly, and especially if your package has become out of
-date, check for the newest Policy Manual available and update your
-package, if necessary. When your package complies with the new
-standards you may update the <tt/Standards-Version/ source package
-field and release it.
-<p>
-
-<sect1>Changes to the upstream sources
-<p>
-
-If changes to the source code are made that are generally applicable
-please try to get them included in the upstream version of the package
-by supplying the upstream authors with the changes in whatever form
-they prefer.
-<p>
-
-If you need to configure the package differently for Debian or for
-Linux, and the upstream source doesn't provide a way to configure it
-the way you need to, please add such configuration facilities (for
-example, a new <prgn/autoconf/ test or <tt/#define/) and send the
-patch to the upstream authors, with the default set to the way they
-originally had it. You can then easily override the default in your
-<tt>debian/rules</tt> or wherever is appropriate.
-<p>
-
-Please make sure that the <prgn/configure/ utility detects the correct
-architecture specification string (refer to <ref id="arch-spec"> for
-details).
-<p>
-
-If you need to edit a <prgn/Makefile/ where GNU-style <prgn/configure/
-scripts are used, you should edit the <tt/.in/ files rather than
-editing the <prgn/Makefile/ directly. This allows the user to
-reconfigure the package if necessary. You should <em/not/ configure
-the package and edit the generated <prgn/Makefile/! This makes it
-impossible for someone else to later reconfigure the package.
-<p>
-
-<sect1>Documenting your changes
-<p>
-
-Document your changes and updates to the source package properly in
-the <tt>debian/changelog</tt> file.
-<p>
-
-A copy of the file which will be installed in
-<tt>/usr/doc/<var/package//copyright</tt> should be in
-<tt>debian/copyright</tt>.
-<p>
-
-In non-experimental packages you may only use a format for
-<tt>debian/changelog</> which is supported by the most recent released
-version of <prgn/dpkg/. If your format is not supported and there is
-general support for it you should contact the <prgn/dpkg/ maintainer
-to have the parser script for your format included in the <prgn/dpkg/
-package. (You will need to agree that the parser and its
-manpage may be distributed under the GNU GPL, just as the rest of
-<prgn/dpkg/ is.)
-<p>
-
-<sect1>Error trapping in makefiles
-<p>
-
-When <prgn/make/ invokes a command in a makefile (including your
-package's upstream makefiles and the <tt>debian/rules</>) it does so
-using <tt/sh/. This means that <tt/sh/'s usual bad error handling
-properties apply: if you include a miniature script as one of the
-commands in your makefile you'll find that if you don't do anything
-about it then errors are not detected and <prgn/make/ will blithely
-continue after problems.
-<p>
-
-Every time you put more than one shell command (this includes using a
-loop) in a makefile command you <em/must/ make sure that errors are
-trapped. For simple compound commands, such as changing directory and
-then running a program, using <tt/&&/ rather than semicolon as
-a command separator is sufficient. For more complex commands
-including most loops and conditionals you must include a separate
-<tt/set -e/ command at the start of every makefile command that's
-actually one of these miniature shell scripts.
-<p>
-
-<sect1>Obsolete constructs and libraries
-<p>
-
-The include file <prgn/<varargs.h>/ is provided to support
-end-users compiling very old software; the library <tt/libtermcap/ is
-provided to support the execution of software which has been linked
-against it (either old programs or those such as Netscape which are
-only available in binary form).
-<p>
-
-Debian packages should be ported to include <prgn/<stdarg.h>/ and
-<tt/ncurses/ when they are built.
-<p>
-
-<chapt>The Operating System
-<p>
-
-<sect>Filesystem hierarchy
-<p>
-
-<sect1>Linux Filesystem Structure
-<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/ in
-<ftppath>/pub/linux/docs/linux-standards/fsstnd/</>. Specific
-questions about following the standard may be asked on
-<prgn/debian-devel/, or referred to Daniel Quinlan, the FSSTND
-coordinator, at <email/quinlan@pathname.com/.
-<p>
-
-<sect1>Site-specific programs
-<p>
-
-As mandated by the FSSTND no package should place any files in
-<tt>/usr/local</>, either by putting them in the filesystem archive to
-be unpacked by <prgn/dpkg/ or by manipulating them in their maintainer
-scripts.
-<p>
-
-However, the package should create empty directories below
-<tt>/usr/local</> so that the system administrator knows where to
-place site-specific files. These directories should be removed on
-package removal if they are empty.
-<p>
-
-Note, that this applies only to directories <em/below/
-<tt>/usr/local</>, not <em/in/ <tt>/usr/local</>. The directory
-<tt>/usr/local</> itself may only contain the sub-directories listed
-in FSSTND, section 4.8. 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>
-
-Since <tt>/usr/local</> may be mounted read-only from a remote server,
-these directories have to be created and removed by the <tt/postinst/
-and <tt/prerm/ maintainer scripts. These scripts must not fail if
-either of these operations fail. (In the future, it will be possible to
-tell <prgn/dpkg/ not to unpack files matching certain patterns, so
-that the directories can be included in the <tt/.deb/ packages and
-system administrators who do not wish these directories in /usr/local
-do not need to have them.)
-<p>
-
-For example, the <prgn/emacs/ package will contain
-<example>
- mkdir -p /usr/local/lib/emacs/site-lisp || true
-</example>
-in the <tt/postinst/ script, and
-<example>
- rmdir /usr/local/lib/emacs/site-lisp && \
- rmdir /usr/local/lib/emacs || \
- true
-</example>
-in the <tt/prerm/ script.
-<p>
-
-If you do create a directory in <tt>/usr/local</> for 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>
-
-The <tt>/usr/local</> 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/.
-<p>
-
-<sect>Users and groups
-<p>
-
-The Debian system can be configured to use either plain or shadow
-passwords.
-<p>
-
-Some user ids (UIDs) and group ids (GIDs) are reserved globally for
-use by certain packages. Because some packages need to include files
-which are owned by these users or groups, or need the ids compiled
-into binaries, these ids must be used on any Debian system only for
-the purpose for which they are allocated. This is a serious
-restriction, and we should avoid getting in the way of local
-administration policies. In particular, many sites allocate users
-and/or local system groups starting at 100.
-<p>
-
-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>
-
-No package except <tt>base-passwd</> may modify <tt>/etc/passwd</>,
-<tt>/etc/shadow</>, or <tt>/etc/group</>.
-<p>
-
-The UID and GID ranges are as follows:
-<taglist>
-<tag>0-99:
-<item>
-Globally allocated by the Debian project, must be the same on
-every Debian system. These ids will appear in the <tt>passwd</> and
-<tt>group</>
-files of all Debian systems, new ids in this range being added
-automatically as the <tt>base-passwd</> package is updated.
-<p>
-
-Packages which need a single statically allocated uid or gid should
-use one of these; their maintainers should ask the <tt>base-passwd</>
-maintainer for ids.
-<p>
-
-<tag>100-999:
-<item>
-Dynamically allocated system users and groups. Packages
-which need a user or group, but can have this user or group allocated
-dynamically and differently on each system, should use `<tt>adduser
---system</>' to create the group and/or user. <prgn>adduser</> will
-check for the
-existence of the user or group, and if necessary choose an unused id
-based on the ranged specified in <tt>adduser.conf</>.
-<p>
-
-<tag>1000-29999:
-<item>
-Dynamically allocated user accounts. By default <prgn>adduser</>
-will choose UIDs and GIDs for user accounts in this range, though
-<tt>adduser.conf</> may be used to modify this behaviour.
-<p>
-
-<tag>30000-59999:
-<item>
-Reserved.
-<p>
-
-<tag>60000-64999:
-<item>
-Globally allocated by the Debian project, but only created on
-demand. The ids are allocated centrally and statically, but the actual
-accounts are only created on users' systems on demand.
-<p>
-
-These ids are for packages which are obscure or which require many
-statically-allocated ids. These packages should check for and create
-the accounts in <tt>/etc/passwd</> or <tt>/etc/group</> (using
-<prgn>adduser</> if it has this facility) if necessary. Packages
-which are likely to require further allocations should have a `hole'
-left after them in the allocation, to give them room to grow.
-<p>
-
-<tag>65000-65533:
-<item>
-Reserved.
-<p>
-
-<tag>65534:
-<item>
-User `<tt>nobody</>.'
-<p>
-
-<tag>65535:
-<item>
-<tt>(uid_t)(-1) == (gid_t)(-1)</>. NOT TO BE USED, because it is the
-error return sentinel value.
-<p>
-</taglist>
-
-<sect>Files
-<p>
-
-<sect1>Binaries
-<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</> programs must be renamed.
-<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>
-
-Note that all installed binaries should be
-stripped, either by using the <tt/-s/ flag to <prgn/install/, or by calling
-<prgn/strip/ on the binaries after they have been copied into
-<tt>debian/tmp</> but before the tree is made into a package.
-<p>
-
-The <tt/-g/ 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>
-
-The <tt/-N/ 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>
-
-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 function better with certain
-flags (<tt/-O3/, for example); feel free to use them. Please use good
-judgment here. Don't use flags for the sake of it; only use them if
-there is good reason to do so. Feel free to override the upstream
-author's ideas about which compilation options are best--they are
-often inappropriate for our environment.
-<p>
-
-<sect1>Libraries
-<p>
-
-All libraries must have a shared version in the lib package and a static
-version in the lib-dev package. The shared version must be compiled with
-<tt/-fPIC/, and the static version must not be. In other words, each
-<tt/*.c/ file is compiled twice.
-<p>
-
-You have to specify the gcc option <tt>-D_REENTRANT</tt> when building
-a library (either static or shared) to make the library compatible with
-LinuxThreads.
-<p>
-
-Note that all installed shared libraries should be stripped with
-<example>
- strip --strip-unneeded <your-lib>
-</example>
-(The option `--strip-unneeded' makes <tt>strip</tt> remove only the symbols
-which aren't needed for relocation processing.)
-Shared libraries can function perfectly well when
-stripped, since the symbols for dynamic linking are in a separate part
-of the ELF object file.
-<p>
-
-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>
-
-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>
-
-<sect1>Shared libraries
-<p>
-
-Packages involving shared libraries should be split up into several
-binary packages.
-<p>
-
-For a straightforward library which has a development environment and
-a runtime kit including just shared libraries you need to create two
-packages: <tt/<var/libraryname/<var/soname// (<var/soname/ is
-the shared object name of the shared library--it's the thing that has
-to match exactly between building an executable and running it for the
-dynamic linker to be able run the program; usually the <var/soname/
-is the major number of the library) and
-<tt/<var/libraryname/<var/soname/-dev/.
-<p>
-
-If you prefer only to support one development version at a time you
-may name the development package <tt/<var/libraryname/-dev/; otherwise
-you may wish to use <prgn/dpkg/'s conflicts mechanism to ensure that
-the user only installs one development version at a time (after all,
-different development versions are likely to have the same header
-files in them, causing a filename clash if both are installed).
-Typically the development version will also need an exact version
-dependency on the runtime library, to make sure that compilation and
-linking happens correctly.
-<p>
-
-Packages which use the shared library should have a dependency on the
-name of the shared library package,
-<tt/<var/libraryname/<var/soname//. When the <var/soname/ changes you
-can have both versions of the library installed while moving from the
-old library to the new.
-<p>
-
-If your package has some run-time support programs which use the
-shared library you must <em/not/ put them in the shared library
-package. If you do that then you won't be able to install several
-versions of the shared library without getting filename clashes.
-Instead, either create a third package for the runtime binaries (this
-package might typically be named <tt/<var/libraryname/-runtime/--note
-the absence of the <var/soname/ in the package name) or if the
-development package is small include them in there.
-<p>
-
-If you have several shared libraries built from the same source tree
-you can lump them all together into a single shared library package,
-provided that you change all their <var/soname/s at once (so that you
-don't get filename clashes if you try to install different versions of
-the combined shared libraries package).
-<p>
-
-Follow the directions in the <em>Debian Packaging Manual</em> for
-putting the shared library in its package, and make sure you include a
-<tt/shlibs/ control area file with details of the dependencies for
-packages which use the library.
-<p>
-
-Shared libraries should <em/not/ be installed executable, since
-<prgn/ld.so/ does not require this and trying to execute a shared
-library results in a core dump.
-<p>
-
-<sect1 id=scripts>Scripts
-<p>
-
-All command scripts, including the package maintainer scripts inside
-the package and used by <prgn/dpkg/, should have a <tt/#!/ line naming
-the shell to be used to interpret them.
-<p>
-
-In the case of Perl scripts this should be <tt>#!/usr/bin/perl</tt>.
-<p>
-
-Shell scripts (<prgn/sh/ and <prgn/bash/) should almost certainly
-start with <tt>set -e</> so that errors are detected. Every script
-<em/must/ use <tt/set -e/ or check the exit status of <em/every/
-command.
-<p>
-
-The standard shell interpreter `<tt>/bin/sh</tt>' may be a symbolic
-link to any POSIX compatible shell. Thus, shell scripts specifying
-`<tt>/bin/sh</tt>' as interpreter may only use POSIX features. If a
-script requires non-POSIX features from the shell interpreter, the
-appropriate shell has to be specified in the first line of the script
-(e.g., `<tt>#!/bin/bash</tt>') and the package has to depend on the
-package providing the shell (unless the shell package is marked
-`Essential', e.g., in the case of <prgn/bash/).
-<p>
-
-Restrict your script to POSIX features when possible so that it may
-use <tt>/bin/sh</tt> as its interpreter. If your script works with
-<prgn/ash/, it's probably POSIX compliant, but if you are in doubt,
-use <tt>/bin/bash</tt>.
-<p>
-
-Perl scripts should check for errors when making any system calls,
-including <tt/open/, <tt/print/, <tt/close/, <tt/rename/ and
-<tt/system/.
-<p>
-
-<prgn/csh/ and <prgn/tcsh/ should be avoided as scripting languages.
-See <em>Csh Programming Considered Harmful</>, one of the
-<tt/comp.unix.*/ FAQs. It can be found on <ftpsite>rtfm.mit.edu</> in
-<ftppath>/pub/usenet-by-group/comp.unix.programmer/Csh_Programming_Considered_Harmful</>.
-If an upstream package comes with <prgn/csh/ scripts then you must
-make sure that they start with <tt>#!/bin/csh</tt> and make your
-package depend on the <prgn/c-shell/ virtual package.
-<p>
-
-Any scripts which create files in world-writable directories (e.g., in
-<tt>/tmp</tt>) have to use a mechanism which will fail if a file with
-the same name already exists.
-<p>
-
-The Debian base distribution provides the <prgn/tempfile/ and
-<prgn/mktemp/ utilities for use by scripts for this purpose.
-<p>
-
-<sect1>Symbolic links
-<p>
-
-In general, symbolic links within a toplevel 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 directory `/'.)
-<p>
-
-In addition, symbolic links should be specified as short as possible,
-i.e., link targets like `foo/../bar' are deprecated.
-<p>
-
-Note that when creating a relative link using <prgn/ln/ it is not
-necessary for the target of the link to exist relative to the working
-directory you're running <prgn/ln/ from; nor is it necessary to change
-directory to the directory where the link is to be made. Simply
-include the string that should appear as the target of the link (this
-will be a pathname relative to the directory in which the link
-resides) as the first argument to <prgn/ln/.
-<p>
-
-For example, in your <prgn/Makefile/ or <tt>debian/rules</>, do things
-like:
-<example>
- ln -fs gcc $(prefix)/bin/cc
- ln -fs gcc debian/tmp/usr/bin/cc
- ln -fs ../sbin/sendmail $(prefix)/bin/runq
- ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
-</example>
-<p>
-
-A symbolic link pointing to a compressed file should always have the
-same file extension as the referenced file. (For example, if a file
-`<tt>foo.gz</tt>' is referenced by a symbolic link, the filename of
-the link has to end with `<tt>.gz</tt>' too, as in `bar.gz.')
-<p>
-
-<sect1>Device files
-<p>
-
-No package may include device files in the package file tree.
-<p>
-
-If a package needs any special device files that are not included in
-the base system, it has to call <prgn/makedev/ in the <tt/postinst/
-script, after asking the user for permission to do so.
-<p>
-
-No package should remove any device files in the <tt/postrm/ or any
-other script. This is left to the system administrator.
-<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>
-
-<sect1>Configuration files
-<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>
-
-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/'s
-<tt/conffiles/ control area file. (See the <em>Debian Packaging
-Manual</em>).
-<p>
-
-Only packages that are tagged <em/conflicting/ with each other may
-specify the same file as <tt/conffile/. A package may not modify a
-configuration file of another package.
-<p>
-
-If two or more packages use the same configuration file, one of these
-packages has to be defined as <em/owner/ of the configuration file,
-i.e., it has to list the file as <tt/conffile/ and has to provide
-a program that modifies the configuration file.
-<p>
-
-The other packages have to depend on the <em/owner/ package and use
-that program to update the configuration file.
-<p>
-
-Sometimes it's appropriate to build a new package, which just provides
-the basic <em/infrastructure/ for the other packages and which manages
-the shared configuration files. (Check out the <prgn/sgml-base/
-package as an example.)
-<p>
-
-Files in <tt>/etc/skel</> will automatically be copied into new user
-accounts by <prgn/adduser/. They should not be referenced there by
-any program.
-<p>
-
-Therefore, if a program needs a dotfile to exist in advance in
-<tt/$HOME/ to work sensibly that dotfile should be installed in
-<tt>/etc/skel</> (and listed in conffiles, if it is not generated and
-modified dynamically by the package's installation scripts).
-<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>
-
-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</>. 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</>.
-<p>
-
-<tt>/etc/skel</> 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>
-
-Ideally the sysadmin should not have to do any configuration other
-than that done (semi-)automatically by the <tt/postinst/ script.
-<p>
-
-<sect1>Permissions and owners
-<p>
-
-The rules in this section are guidelines for general use. If
-necessary you may deviate from the details below. However, if you do
-so you must make sure that what is done is secure and you must try to
-be as consistent as possible with the rest of the system. You should
-probably also discuss it on <prgn/debian-devel/ first.
-<p>
-
-Files should be owned by <tt/root.root/, and made writable only by
-the owner and universally readable (and executable, if appropriate).
-<p>
-
-Directories should be mode 755 or (for group-writability) mode 2775.
-The ownership of the directory should be consistent with its mode--if
-a directory is mode 2775, it should be owned by the group that needs
-write access to it.
-<p>
-
-Setuid and setgid executables should be mode 4755 or 2755
-respectively, and owned by the appropriate user or group. They should
-not be made unreadable (modes like 4711 or 2711 or even 4111); doing
-so achieves no extra security, because anyone can find the binary in
-the freely available Debian package--it is merely inconvenient. For
-the same reason you should not restrict read or execute permissions on
-non-set-id executables.
-<p>
-
-Some setuid programs need to be restricted to particular sets of
-users, using file permissions. In this case they should be owned by
-the uid to which they are set-id, and by the group which should be
-allowed to execute them. They should have mode 4754; there is no
-point in making them unreadable to those users who must not be allowed
-to execute them.
-<p>
-
-Do not arrange that the system administrator can only reconfigure the
-package to correspond to their local security policy by changing the
-permissions on a binary. Ordinary files installed by <prgn/dpkg/ (as
-opposed to conffiles and other similar objects) have their permissions
-reset to the distributed permissions when the package is reinstalled.
-Instead you should consider (for example) creating a group for people
-allowed to use the program(s) and making any setuid executables
-executable only by that group.
-<p>
-
-If you need to create a new user or group for your package there are
-two possibilities. Firstly, you may need to make some files in the
-binary package be owned by this user or group, or you may need to
-compile the user or group id (rather than just the name) into the
-binary (though this latter should be avoided if possible). In this
-case you need a statically allocated id.
-<p>
-
-You must ask for a user or group id from the base system maintainer,
-and must not release the package until you have been allocated one.
-Once you have been allocated one you must make the package depend on a
-version of the base system with the id present in <tt>/etc/passwd</tt>
-or <tt>/etc/group</tt>, or alternatively arrange for your package to
-create the user or group itself with the correct id (using
-<tt/adduser/) in its pre- or post-installation script (the latter is
-to be preferred if it is possible).
-<p>
-
-On the other hand, the program may able to determine the uid or gid
-from the group name at runtime, so that a dynamic id can be used. In
-this case you must choose an appropriate user or group name,
-discussing this on <prgn/debian-devel/ and checking with the base
-system maintainer that it is unique and that they do not wish you to
-use a statically allocated id instead. When this has been checked you
-must arrange for your package to create the user or group if necessary
-using <prgn/adduser/ in the pre- or post-installation script (again,
-the latter is to be preferred if it is possible).
-<p>
-
-Note that changing the numeric value of an id associated with a name
-is very difficult, and involves searching the filesystem 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>
-
-<sect id="sysvinit">System run levels
-<p>
-
-<sect1>Introduction
-<p>
-
-The <tt>/etc/init.d</> directory contains the scripts executed by
-<prgn/init/ at boot time and when init state (or `runlevel') is
-changed (see <manref name=init section=8>). <p>
-
-These scripts are being referenced by symbolic links in the
-<tt>/etc/rc<var/n/.d</> directories. When changing runlevels,
-<prgn/init/ looks in the directory <tt>/etc/rc<var/n/.d</> for the
-scripts it should execute, where <var/n/ is the runlevel that is being
-changed to, or `S' for the boot-up scripts. <p>
-
-The names of the links all have the form <tt/S<var/mm/<var/script// or
-<tt/K<var/mm/<var/script// where <var/mm/ is a two-digit number and
-<var/script/ is the name of the script (this should be the same as the
-name of the actual script in <tt>/etc/init.d</>.
-
-When <prgn/init/ changes runlevel first the targets of the links whose
-names starting with a <tt/K/ are executed, each with the single
-argument <tt/stop/, followed by the scripts prefixed with an <tt/S/,
-each with the single argument <tt/start/. The <tt/K/ links are
-responsible for killing services and the <tt/S/ link for starting
-services upon entering the runlevel.
-<p>
-
-For example, if we are changing from runlevel 2 to runlevel 3, init
-will first execute all of the <tt/K/ prefixed scripts it finds in
-<tt>/etc/rc3.d</>, and then all of the <tt/S/ prefixed scripts. The
-links starting with <tt/K/ will cause the referred-to file to be
-executed with an argument of <tt/stop/, and the <tt/S/ links with an
-argument of <tt/start/.
-<p>
-
-The two-digit number <var/mm/ is used to decide which order to start
-and stop things in--low-numbered links have their scripts run first.
-For example, the <tt/K20/ scripts will be executed before the <tt/K30/
-scripts. This is used when a certain service must be started before
-another. For example, the name server <prgn/bind/ might need to be
-started before the news server <prgn/inn/ so that <prgn/inn/ can set
-up its access lists. In this case, the script that starts <prgn/bind/
-should have a lower number than the script that starts <prgn/inn/ so
-that it runs first:
-<example>
- /etc/rc2.d/S17bind
- /etc/rc2.d/S70inn
-</example>
-
-<sect1>Writing the scripts
-<p>
-
-Packages can and should place scripts in <tt>/etc/init.d</> to start
-or stop services at boot time or during a change of runlevel. These
-scripts should be named <tt>/etc/init.d/<var/package/</>, and they
-should accept one argument, saying what to do:
-
-<taglist>
-<tag><tt/start/
-<item>start the service,
-<p>
-<tag><tt/stop/
-<item>stop the service,
-<p>
-<tag><tt/restart/
-<item>stop and restart the service,
-<p>
-<tag><tt/reload/
-<item>cause the configuration of the service to be
-reloaded without actually stopping and restarting the service,
-<p>
-<tag><tt/force-reload/
-<item>cause the configuration to be reloaded if the service supports
-this, otherwise restart the service.
-</taglist>
-
-The <tt/start/, <tt/stop/, <tt/restart/, and <tt/force-reload/ options
-must be supported by all scripts in <tt>/etc/init.d</>, the
-<tt/reload/ option is optional.
-<p>
-
-The <tt/init.d/ scripts should ensure that they will behave sensibly
-if invoked with <tt/start/ when the service is already running, or
-with <tt/stop/ when it isn't, and that they don't kill
-unfortunately-named user processes. The best way to achieve this is
-usually to use <prgn/start-stop-daemon/.
-<p>
-
-If a service reloads its configuration automatically (as in the case
-of <prgn/cron/, for example), the <tt/reload/ option of the
-<tt/init.d/ script should behave as if the configuration has been
-reloaded successfully.
-<p>
-
-These scripts should not fail obscurely when the configuration files
-remain but the package has been removed, as the default in <prgn/dpkg/
-is to leave configuration files on the system after the package has
-been removed. Only when it is executed with the <tt/--purge/ option
-will dpkg remove configuration files. Therefore, you should include a
-<tt/test/ statement at the top of the script, like this:
-<example>
- test -f <var/program-executed-later-in-script/ || exit 0
-</example>
-
-<sect1>Managing the links
-<p>
-
-A program is provided, <prgn/update-rc.d/, to make it easier for
-package maintainers to arrange for the proper creation and removal of
-<tt>/etc/rc<var/n/.d</> symbolic links from their <tt/postinst/ and
-<tt/postrm/ scripts.
-<p>
-
-You should use this script to make changes to <tt>/etc/rc<var/n/.d</>
-and <em/never/ include any <tt>/etc/rc<var/n/.d</> symbolic links in
-the actual archive.
-<p>
-
-By default <prgn/update-rc.d/ will start services in each of the
-multi-user state runlevels (2, 3, 4, and 5) and stop them in the halt
-runlevel (0), the single-user runlevel (1) and the reboot runlevel
-(6). The system administrator will have the opportunity to customize
-runlevels by simply adding, moving, or removing the symbolic links in
-<tt>/etc/rc<var/n/.d</>.
-<p>
-
-To get the default behaviour for your package, put in your
-<tt/postinst/ script
-<example>
- update-rc.d <var/package/ default >/dev/null
-</example>
-and in your <tt/postrm/
-<example>
- if [ purge = "$1" ]; then
- update-rc.d <var/package/ remove >/dev/null
- fi
-</example>
-<p>
-
-This will use a default sequence number of 20. If it does not matter
-when or in which order the script is run, use this default. If it
-does, then you should talk to the maintainer of the <prgn/sysvinit/
-package or post to <tt>debian-devel</>, and they will help you choose
-a number.
-<p>
-
-For more information about using <tt/update-rc.d/, please consult its
-manpage <manref name=update-rc.d section=8>.
-<p>
-
-<sect1>Boot-time initialisation
-<p>
-
-There is another directory, <tt>/etc/rc.boot</>, 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>
-
-For example, the <prgn/kbd/ package provides a script here for
-initialising the keyboard layout and console font and mode.
-<p>
-
-The files in <tt>/etc/rc.boot</> should <em/not/ be links into
-<tt>/etc/init.d</>--they should be the scripts themselves.
-<p>
-
-<tt/rc.boot/ should <em/not/ be used for starting general-purpose
-daemons and similar activities. This should be done using the
-<tt/rc<var/n/.d/ 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>Notes
-<p>
-
-<em/Do not/ include the <tt>/etc/rc<var/n/.d/*</> symbolic links in
-the <tt/.deb/ filesystem archive! <em/This will cause problems!/
-You should create them with <prgn/update-rc.d/, as above.
-<p>
-
-<em/Do not/ include the <tt>/etc/rc<var/n/.d/*</> symbolic links in
-<prgn/dpkg/'s conffiles list! <em/This will cause problems!/ <em/Do/,
-however, include the <tt>/etc/init.d</> 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>Example
-<p>
-
-The <prgn/bind/ DNS (nameserver) package wants to make sure that the
-nameserver is running in multiuser runlevels, and is properly shut
-down with the system. It puts a script in <tt>/etc/init.d</>, naming
-the script appropriately <tt/bind/. As you can see, the script
-interprets the argument <tt/reload/ to send the nameserver a <tt/HUP/
-signal (causing it to reload its configuration); this way the user can
-say <tt>/etc/init.d/bind reload</> to reload the name server.
-<p>
-
-<example>
- #!/bin/sh
- #
- # Original version by Robert Leslie <rob@mars.org>, edited by iwj and cs
-
- test -x /usr/sbin/named || exit 0
-
- case "$1" in
- start)
- echo -n "Starting domain name service: named"
- start-stop-daemon --start --quiet --exec /usr/sbin/named
- echo "."
- ;;
- stop)
- echo -n "Stopping domain name service: named"
- start-stop-daemon --stop --quiet \
- --pidfile /var/run/named.pid --exec /usr/sbin/named
- echo "."
- ;;
- restart)
- echo -n "Restarting domain name service: named"
- start-stop-daemon --stop --quiet \
- --pidfile /var/run/named.pid --exec /usr/sbin/named
- start-stop-daemon --start --verbose --exec /usr/sbin/named
- echo "."
- ;;
- force-reload|reload)
- echo -n "Reloading configuration of domain name service: named"
- start-stop-daemon --stop --signal 1 --quiet \
- --pidfile /var/run/named.pid --exec /usr/sbin/named
- echo "."
- ;;
- *)
- echo "Usage: /etc/init.d/bind {start|stop|restart|reload|force-reload}" >&2
- exit 1
- ;;
- esac
-
- exit 0
-</example>
-<p>
-
-Another example on which to base your <tt>/etc/init.d</> scripts is in
-<tt>/etc/init.d/skeleton</>.
-<p>
-
-If this package is happy with the default setup from
-<prgn/update-rc.d/, namely an ordering number of 20 and having named
-running in all runlevels, it can say in its <tt/postinst/:
-<example>
- update-rc.d bind default >/dev/null
-</example>
-And in its <tt/postrm/, to remove the links when the package is purged:
-<example>
- if [ purge = "$1" ]; then
- update-rc.d acct remove >/dev/null
- fi
-</example>
-<p>
-
-<sect>Cron jobs
-<p>
-
-Packages may not touch the configuration file <tt>/etc/crontab</>, nor
-may they modify the files in <tt>/var/spool/cron/crontabs</>.
-<p>
-
-If a package wants to install a job that has to be executed via
-cron, it should place a file with the name if the package in one
-of the following directories:
-<example>
- /etc/cron.daily
- /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>
-
-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/ automatically. (Note, that scripts in the
-<tt>/etc/cron.d</tt> directory are not handled by
-<prgn/anacron/. Thus, you should only use this directory for jobs
-which may be skipped if the system is not running.)
-<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>
-
-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>Console messages
-<p>
-
-This section describes different formats for messages written to
-standard output by the <tt>/etc/init.d</> scripts. The intent is to
-improve the consistency of Debian's startup and shutdown look and
-feel.
-<p>
-
-Please look very careful at the details. We want to get the messages
-to look exactly the same way concerning spaces, punctuation, and case
-of letters.
-<p>
-
-Here is a list of overall rules that you should use when you create output
-messages. They can be useful if you have a non-standard message that isn't
-covered in the sections below.
-<p>
-
-<list>
-<item>
- Every message should cover one line, start with a capital letter and
- end with a period `.'.
-<p>
-
-<item>
- If you want to express that the computer is working on something
- (performing a specific task, not starting or stopping a program), we
- use an ``ellipsis'', namely three dots `...'. Note that we don't insert
- spaces in front of or behind the dots.
- If the task has been completed we write `done.' and a line feed.
-<p>
-
-<item>
- Design your messages as if the computer is telling you what he is
- doing (let him be polite :-) but don't mention ``him'' directly.
- For example, if you think of saying
-<example>
- I'm starting network daemons: nfsd mountd.
-</example>
- just say
-<example>
- Starting network daemons: nfsd mountd.
-</example>
-</list>
-<p>
-
-The following formats must be used
-<p>
-
-<list>
-<item>
- when daemons get started.
-<p>
-
- Use this format if your script starts one or more daemons.
- The output should look like this (a single line, no leading spaces):
-<example>
- Starting <description>: <daemon-1> <daemon-2> <...> <daemon-n>.
-</example>
- The <description> should describe the subsystem the daemon or set of
- daemons are part of, while <daemon-1> up to <daemon-n>
- denote each daemon's name (typically the file name of the program).
-<p>
-
- For example, the output of /etc/init.d/lpd would look like:
-<example>
- Starting printer spooler: lpd.
-</example>
-<p>
-
- This can be achieved by saying
-<example>
- echo -n "Starting printer spooler: lpd"
- start-stop-daemon --start --quiet lpd
- echo "."
-</example>
- in the script. If you have more than one daemon to start, you should
- do the following:
-<example>
- echo -n "Starting remote filesystem services:"
- echo -n " nfsd"; start-stop-daemon --start --quiet nfsd
- echo -n " mountd"; start-stop-daemon --start --quiet mountd
- echo -n " ugidd"; start-stop-daemon --start --quiet ugidd
- echo "."
-</example>
- This makes it possible for the user to see what takes so long and when
- the final daemon has been started. Please be careful where to put spaces:
- In the example above the system administrator can easily comment out
- a line if he don't wants to start a specific daemon, while the displayed
- message still looks good.
-<p>
-
-<item>
- when something needs to be configured.
-<p>
-
- If you have to set up different parameters of the system upon boot up,
- you can use this format:
-<example>
- Setting <parameter> to `<value>'.
-</example>
-<p>
-
- You can use the following echo statement to get the quotes right:
-<example>
- echo "Setting DNS domainname to \`"value"'."
-</example>
-<p>
-
- Note that the left quotation mark (`) is different from the right (').
-
-<item>
- when a daemon is stopped.
-<p>
-
- When you stop a daemon you should issue a message similar to the startup
- message, except that `Starting' is replaced with `Stopping'.
-<p>
-
- So stopping the printer daemon will like like this:
-<example>
- Stopping printer spooler: lpd.
-</example>
-
-<item>
- when something is executed.
-<p>
-
- There a several examples where you have to run a program at system
- startup or shutdown to perform a specific task. For example, setting
- the system's clock via `netdate' or killing all processes when the
- system comes down. Your message should like this:
-<example>
- Doing something very useful...done.
-</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
-<example>
- echo -n "Doing something very useful..."
- do_something
- echo "done."
-</example>
- in your script.
-
-<item>
- when the configuration is reloaded.
-<p>
-
- When a daemon is forced to reload its configuration files you
-should use the following format:
-<example>
- Reloading <daemon's-name> configuration...done.
-</example>
-
-<item>
- when none of the above rules apply.
-<p>
-
- If you have to print a message that doesn't fit into the styles described
- above, you can use something appropriate, but please have a look at the
- overall rules listed above.
-</list>
-<p>
-
-<sect>Menus
-<p>
-
-The Debian <tt/menu/ packages provides a unique interface between
-packages providing applications and documents, and <em/menu programs/
-(either X window managers or text-based menu programs as
-<prgn/pdmenu/).
-<p>
-
-All packages that provide applications that need not be passed any
-special command line arguments for normal operation should register a
-menu entry for those applications, so that users of the <tt/menu/
-package will automatically get menu entries in their window managers,
-as well in shells like <tt/pdmenu/.
-<p>
-
-Please refer to the <em>Debian Menu System</em> document that comes
-with the <tt/menu/ package for information about how to register your
-applications and web documents.
-<p>
-
-<sect>Keyboard configuration
-<p>
-
-To achieve a consistent keyboard configuration (i.e., all applications
-interpret a keyboard event the same way) all programs in the Debian
-distribution have to be configured to comply with the following
-guidelines.
-<p>
-
-Here is a list that contains certain keys and their interpretation:
-
-<taglist>
-<tag><tt/<--/
-<item>delete the character to the left of the cursor
-<p>
-<tag><tt/Delete/
-<item>delete the character to the right of the cursor
-<p>
-<tag><tt/Control+H/
-<item>emacs: the help prefix
-</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 following list explains how the different programs should be set
-up to achieve this:
-<p>
-
-<list compact>
-<item>`<tt><--</tt>' generates KB_Backspace in X.
-<p>
-<item>`<tt/Delete/' generates KB_Delete in X.
-<p>
-<item>X translations are set up to make KB_Backspace generate ASCII DEL,
- and to make KB_Delete generate <tt>ESC [ 3 ~</tt> (this is the vt220 escape
- code for the `delete character' key). This must be done by loading
- the resources using xrdb on all local X displays, not using the
- application defaults, so that the translation resources used
- correspond to the xmodmap settings.
-<p>
-<item>The Linux console is configured to make `<tt><--</tt>' generate DEL, and
- `Delete' generate <tt>ESC [ 3 ~</tt> (this is the case at the moment).
-<p>
-<item>X applications are configured so that Backspace deletes left, and
- Delete deletes right. Motif applications already work like this.
-<p>
-<item>stty erase <tt>^?</tt> .
-<p>
-<item>The `xterm' terminfo entry should have <tt>ESC [ 3 ~</tt> for kdch1, just
- like TERM=linux and TERM=vt220.
-<p>
-<item>Emacs is programmed to map KB_Backspace or the `stty erase'
- character to delete-backward-char, and KB_Delete or kdch1 to
- delete-forward-char, and <tt>^H</tt> to help as always.
-<p>
-<item>Other applications use the `stty erase' character and kdch1 for the
- two delete keys, with ASCII DEL being `delete previous character'
- and kdch1 being `delete character under cursor'.
-</list>
-<p>
-
-This will solve the problem except for:
-<p>
-
-<list compact>
-<item>Some terminals have a <tt><--</tt> key that cannot be made to produce
- anything except <tt>^H</tt>. On these terminals Emacs help will be
- unavailable on <tt>^H</tt> (assuming that the `stty erase' character takes
- precedence in Emacs, and has been set correctly). M-x help or F1
- (if available) can be used instead.
-<p>
-<item>Some operating systems use <tt>^H</tt> for stty erase. However, modern
- telnet versions and all rlogin versions propagate stty settings,
- and almost all UNIX versions honour stty erase. Where the stty
- settings are not propagated correctly things can be made to work by
- using stty manually.
-<p>
-<item>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 of their X clients via the same X resources
- that we use to do it for our own, or have our clients be configured
- via their resources when things are the other way around. On
- displays configured like this Delete will not work, but <tt><--</tt> will.
-<p>
-<item>Some operating systems have different kdch1 settings in their
- terminfo for xterm and others. On these systems the Delete key
- will not work correctly when you log in from a system conforming to
- our policy, but <tt><--</tt> will.
-</list>
-<p>
-
-<sect>Environment variables
-<p>
-
-No program may depend on environment variables to get reasonable
-defaults. (That's because these environment variables would have to
-be set in a system-wide configuration file like /etc/profile, which is
-not supported by all shells.)
-<p>
-
-If a program should depend on environment variables for its
-configuration, the program has to be changed to fall back to a
-reasonable default configuration if these environment variables are
-not present. If this cannot be done easily (e.g., if the source code
-of a non-free program is not available), the program should be
-replaced by a small `wrapper' shell script which sets the environment
-variables and calls the original program.
-<p>
-
-Here is an example of a wrapper script for this purpose:
-
-<example>
-#!/bin/sh
-BAR=/var/lib/fubar
-export BAR
-exec /usr/lib/foo/foo "$@"
-</example>
-<p>
-
-Furthermore, as <tt>/etc/profile</tt> is a configuration file of the
-<prgn/bash/ package, no other package may put any environment
-variables or other commands into that file.
-<p>
-
-
-
-<chapt>Customized programs
-<p>
-
-<sect id="arch-spec">Architecture specification strings
-<p>
-
-If a program needs to specify an <em>architecture specification
-string</> in some place, the following format has to be used:
-<example>
- <arch>-linux
-</example>
-where `<arch>' is one of the following: i386, alpha, arm, m68k,
-powerpc, sparc.
-<p>
-
-Note, that we don't want to use `<arch>-debian-linux' to apply
-to the rule `architecture-vendor-os' since this would make our
-programs incompatible to other Linux distributions. Also note, that we
-don't use `<arch>-unknown-linux', since the `unknown' does not
-look very good.
-<p>
-
-<sect>Daemons
-<p>
-
-The configuration files <tt>/etc/services</tt>,
-<tt>/etc/protocols</tt>, and <tt>/etc/rpc</tt> are managed by the
-<prgn/netbase/ package and may not be modified by other packages.
-<p>
-
-If a package requires a new entry in one of these files, the
-maintainer has to get in contact with the <prgn/netbase/ maintainer,
-who will add the entries and release a new version of the
-<prgn/netbase/ package.
-<p>
-
-The configuration file <tt>/etc/inetd.conf</tt> may be modified by the
-package's scripts only via the <prgn/update-inetd/ script or the
-<prgn/DebianNet.pm/ Perl module.
-<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/ script and are not changed or
-activated during a package updates.
-<p>
-
-<sect>Editors and pagers
-<p>
-
-Some programs have the ability to launch an editor or pager
-program to edit or display a text document. Since there are
-lots of different editors and pagers available in the Debian
-distribution, the system administrator and each user should have
-the possibility to choose his/her preferred editor and pager.
-<p>
-
-In addition, every program should choose a good default
-editor/pager if none is selected by the user or system
-administrator.
-<p>
-
-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>
-
-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>
-
-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, 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>
-
-Since the Debian base system already provides an editor and
-a pager program, there is no need for a package to depend on
-`editor' and `pager', nor is it necessary for a package to
-provide such virtual packages.
-<p>
-
-<sect id="web-appl">Web servers and applications
-<p>
-
-This section describes the locations and URLs that have to be used by
-all web servers and web application in the Debian system.
-<p>
-
-<enumlist>
-<item>Cgi-bin executable files are installed in the directory
-<example>
- /usr/lib/cgi-bin/<cgi-bin-name>
-</example>
-and can be referred to as
-<example>
- http://localhost/cgi-bin/<cgi-bin-name>
-</example>
-<p>
-
-<item>Access to html documents
-<p>
-
-Html documents for a package are stored in /usr/doc/<package> and can be
-referred to as
-<example>
- http://localhost/doc/<package>/<filename>
-</example>
-<p>
-
-<item>Web Document Root
-<p>
-
-Web Applications should try to avoid storing files in the Web Document Root.
-Instead use the /usr/doc/<package> directory for documents and
-register the Web Application via the menu package. If access to the
-web-root is unavoidable then use
-<example>
- /var/www
-</example>
-as the Document Root. This might be just a symbolic link to the location where the
-sysadmin has put the real document root.
-<p>
-
-</enumlist>
-<p>
-
-<sect>Mail transport agents
-<p>
-
-Debian packages which process electronic mail, whether
-mail-user-agents (MUAs) or mail-transport-agents (MTAs), <em/must/
-make sure that they are compatible with the configuration decisions
-below. Failure to do this may result in lost mail, broken <tt/From:/
-lines, and other serious brain damage!
-<p>
-
-The mail spool is <tt>/var/spool/mail</> and the interface to send a
-mail message is <tt>/usr/sbin/sendmail</> (as per the FSSTND). The
-mail spool is part of the base system and not part of the MTA package.
-<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/ mechanism. Please
-compare the mechanisms very carefully!)
-<p>
-
-Mailboxes are generally 660 <tt/<var/user/.mail/ unless the user has
-chosen otherwise. A MUA may remove a mailbox (unless it has
-nonstandard permissions) in which case the MTA or another MUA must
-recreate it if needed. Mailboxes must be writable by group mail.
-<p>
-
-The mail spool is 2775 <tt/mail.mail/, and MUAs need to be setgid
-mail to do the locking mentioned above (and obviously need to avoid
-accessing other users' mailboxes using this privilege).
-<p>
-
-<tt>/etc/aliases</> is the source file for the system mail aliases
-(e.g., postmaster, usenet, etc.)--it is the one which the sysadmin
-and <tt/postinst/ scripts may edit. After <tt>/etc/aliases</> is edited
-the program or human editing it must call <prgn/newaliases/. All MTA
-packages should come with a <prgn/newaliases/ program, even if it does
-nothing, but older MTA packages do not do this so programs should not
-fail if <prgn/newaliases/ cannot be found.
-<p>
-
-The convention of writing <tt/forward to <var/address// in the mailbox
-itself is not supported. Use a <tt/.forward/ file instead.
-<p>
-
-The location for the <prgn/rmail/ program used by UUCP for incoming
-mail is <tt>/usr/sbin/rmail</>, as per the FSSTND. Likewise,
-<prgn/rsmtp/, for receiving batch-SMTP-over-UUCP, is in
-<tt>/usr/sbin/rsmtp</> if it is supported.
-<p>
-
-If you need to know what name to use (for example) on outgoing news
-and mail messages which are generated locally, you should use the file
-<tt>/etc/mailname</>. It will contain the portion after the username
-and <tt/@/ (at) sign for email addresses of users on the machine
-(followed by a newline).
-<p>
-
-A package should check for the existence of this file. If it exists
-it should use it without comment. (An MTA's prompting
-configuration script may wish to prompt the user even if it finds this
-file exists.) If it does not exist it should prompt the user
-for the value and store it in <tt>/etc/mailname</> as well as using it
-in the package's configuration. The prompt should make it clear that
-the name will not just be used by that package. For example, in this
-situation the INN package says:
-<example>
- Please enter the `mail name' of your system. This is the hostname
- portion of the address to be shown on outgoing news and mail messages.
- The default is <var/syshostname/, your system's host name.
- Mail name [`<var/syshostname/']:
-</example>
-where <var/syshostname/ is the output of <tt/hostname --fqdn/.
-<p>
-
-<sect>News system configuration
-<p>
-
-All the configuration files related to the NNTP (news) servers and
-clients should be located under <tt>/etc/news</tt>.
-<p>
-
-There are some configuration issues that apply to a number of
-news clients and server packages on the machine. These are:
-
-<taglist>
-<tag>/etc/news/organization
-<item>A string which shall appear as the
- organization header for all messages posted
- by NNTP clients on the machine
-<p>
-<tag>/etc/news/server
-<item>Contains the FQDN of the upstream NNTP
- server, or localhost if the local machine is
- an NNTP server.
-</taglist>
-
-Other global files may be added as required for cross-package news
-configuration.
-<p>
-
-<sect>Programs for the X Windows system
-<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>
-
-Such programs should be configured <em/with/ X support, and should
-declare a dependency on <tt/xlib6g/ (for the X11R6 libraries).
-Users who wish to use the program can install just the relatively
-small <tt/xlib6g/ package, and do not need to install the whole of X.
-<p>
-
-Do not create two versions (one with X support and one without) of
-your package.
-<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>
-
-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>
-
-However, if your package works reliably with lesstif, you should
-package it with lesstif, and not with Motif at all.
-<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>Emacs lisp programs
-<p>
-
-Please refer to the `Debian Emacs Policy' (documented in
-<tt>debian-emacs-policy.gz</tt> of the <prgn/emacsen-common/ package)
-for details of how to package emacs lisp programs.
-<p>
-
-<sect>Games
-<p>
-
-The permissions on /var/lib/games are 755 <tt/root.root/.
-<p>
-
-Each game decides on its own security policy.
-<p>
-
-Games which require protected, privileged access to high-score files,
-savegames, etc., must be made set-<em/group/-id (mode 2755) and
-owned by <tt/root.games/, and use files and directories with
-appropriate permissions (770 <tt/root.games/, for example). They must
-<em/not/ be made set-<em/user/-id, as this causes security
-problems. (If an attacker can subvert any set-user-id game
-they can overwrite the executable of any other, causing other players
-of these games to run a Trojan horse program. With a set-group-id
-game the attacker only gets access to less important game data, and if
-they can get at the other players' accounts at all it will take
-considerably more effort.)
-<p>
-
-Some packages, for example some fortune cookie programs, are
-configured by the upstream authors to install with their data files or
-other static information made unreadable so that they can only be
-accessed through set-id programs provided. Do not do this in a Debian
-package: anyone can download the <tt/.deb/ file and read the data from
-it, so there is no point making the files unreadable. Not making the
-files unreadable also means that you don't have to make so many
-programs set-id, which reduces the risk of a security hole.
-<p>
-
-As described in the FSSTND, 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 for games (X and non-X games) should
-be installed in <tt>/usr/man/man6</tt>.
-<p>
-
-<chapt>Documentation
-<p>
-
-<sect>Manual pages
-<p>
-
-You must install manual pages in <prgn/nroff/ source form, in appropriate
-places under <tt>/usr/man</tt>. You should only use sections 1 to 9
-(see the FSSTND for more details). You must <em/not/ install a
-preformatted `cat page'.
-<p>
-
-If no manual page is available for a particular program, utility or
-function and this is reported as a bug on debian-bugs, a symbolic link
-from the requested manual page to the <manref name=undocumented
-section=7> manual page should be provided. This symbolic link can be
-created from <tt>debian/rules</> like this:
-<example>
- ln -s ../man7/undocumented.7.gz \
- debian/tmp/usr/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 (you can report it
-yourself, if you like). Do not close the bug report until a proper
-manpage is available.
-<p>
-
-You may forward a complaint about a missing manpage to the upstream
-authors, and mark the bug as forwarded in the Debian bug tracking
-system. Even though the GNU Project do not in general consider the
-lack of a manpage to be a bug, we do--if they tell you that they
-don't consider it a bug you should leave the bug in our bug tracking
-system open anyway.
-<p>
-
-Manual pages should be installed compressed using <tt/gzip -9/.
-<p>
-
-If one manpage needs to be accessible via several names it is better
-to use a symbolic link than the <tt/.so/ feature, but there is no need
-to fiddle with the relevant parts of the upstream source to change
-from <tt/.so/ to symlinks--don't do it unless it's easy. Do not
-create hard links in the manual page directories, and do not put
-absolute filenames in <tt/.so/ directives. The filename in a <tt/.so/
-in a manpage should be relative to the base of the manpage tree
-(usually <tt>/usr/man</tt>).
-<p>
-
-<sect>Info documents
-<p>
-
-Info documents should be installed in <tt>/usr/info</tt>. They should
-be compressed with <tt/gzip -9/.
-<p>
-
-Your package must call <prgn/install-info/ to update the Info <tt/dir/
-file, in its post-installation script:
-<example>
- install-info --quiet --section Development Development \
- /usr/info/foobar.info
-</example>
-<p>
-
-It is a good idea to specify a section for the location of your
-program; this is done with the <tt/--section/ switch. To determine
-which section to use, you should look at <tt>/usr/info/dir</> 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/
-flag takes two arguments; the first is a regular expression to match
-(case-insensitively) against an existing section, the second is used
-when creating a new one.
-<p>
-
-You must remove the entries in the pre-removal script:
-<example>
- install-info --quiet --remove /usr/info/foobar.info
-</example>
-<p>
-
-If <prgn/install-info/ cannot find a description entry in the Info
-file you will have to supply one. See <manref name=install-info
-section=8> for details.
-<p>
-
-<sect>Additional documentation
-<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/</tt>, where <var/package/ is the
-name of the package, and compressed with <tt/gzip -9/
-unless it is small.
-<p>
-
-If a package comes with large amounts of documentation which many
-users of the package will not require you should create a separate
-binary package to contain it, so that it does not take up disk space
-on the machines of users who do not need or want it installed.
-<p>
-
-It is often a good idea to put text information files (<tt/README/s,
-changelogs, and so forth) that come with the source package in
-<tt>/usr/doc/<var/package/</> in the binary package. However, you don't
-need to install the instructions for building and installing the package, of
-course!
-<p>
-
-<sect>Preferred documentation formats
-<p>
-
-The unification of Debian documentation is being carried out via HTML.
-<p>
-
-If your package comes with extensive documentation in a markup format
-that can be converted to various other formats you should if possible
-ship HTML versions in the binary package, in the directory
-<tt>/usr/doc/<var/package/</> or its subdirectories.
-<p>
-
-Other formats such as PostScript may be provided at your option.
-<p>
-
-<sect>Log files
-<p>
-
-Log files should usually be named <tt>/var/log/<var/package/.log</tt>.
-If you have many log files, or need a separate directory for
-permissions reasons (<tt>/var/log</tt> is writable only by
-<tt/root/), you should usually create a directory named
-<tt>/var/log/<var/package/</tt>.
-<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/ program in an <tt>/etc/cron.daily</>,
-<tt>/etc/cron.weekly</> or <tt>/etc/cron.monthly</> script. Here is a good
-example:
-<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>
-
-Make sure that any log files are removed when the package is purged
-(but not when it is only removed), by checking the argument to the
-<tt/postrm/ script (see the <em>Debian Packaging Manual</em> for
-details).
-<p>
-
-<sect id="copyrightfile">Copyright information
-<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 neither be
-compressed nor be a symbolic link.
-<p>
-
-In addition, the copyright file must say where the upstream sources
-(if any) were obtained, and explain briefly what modifications were
-made in the Debian version of the package compared to the upstream
-one. It must name the original authors of the package and the Debian
-maintainer(s) who were involved with its creation.
-<p>
-
-/usr/doc/<package-name> may be a symbolic link to a directory in
-/usr/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
-means.
-<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>
-
-Do not use the copyright file as a general <tt/README/ file. If your
-package has such a file it should be installed in
-<tt>/usr/doc/<var/package//README</> or <tt/README.Debian/ or some
-other appropriate place.
-<p>
-
-<sect>Examples
-<p>
-
-Any examples (configurations, source files, whatever), should be
-installed in a directory <tt>/usr/doc/<var/package//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>
-
-<sect id="instchangelog">Changelog files
-<p>
-
-This installed file must contain a copy of the <tt>debian/changelog</>
-file from your Debian source tree, and a copy of the upstream
-changelog file if there is one. They should usually be installed in
-<tt>/usr/doc/<var/package/</> as <tt/changelog.Debian.gz/ and
-<tt/changelog.gz/ respectively.
-<p>
-
-Both should be installed compressed using <tt/gzip -9/, as they will
-become large with time even if they start out small.
-<p>
-
-If the package has only one changelog which is used both as the Debian
-changelog and the upstream one because there is no separate upstream
-maintainer then that changelog should usually be installed as
-<tt>/usr/doc/<var/package//changelog.gz</>; if there is a separate
-upstream maintainer, but no upstream changelog, then the Debian
-changelog should still be called <tt/changelog.Debian.gz/.
-<p>
-
-</book>
+ <!--
+ Debian GNU/Linux Policy Manual.
+ Copyright (C)1996,1997,1998 Ian Jackson and Christian Schwarz;
+ released under the terms of the GNU
+ General Public License, version 2 or (at your option) any later.
+ Initial version 1996, Ian Jackson, ijackson@gnu.ai.mit.edu
+ Revised November 27, 1996, David A. Morris, bweaver@debian.org
+ New sections March 15, 1997, Christian Schwarz, schwarz@debian.org
+ Reworked/Restructured April-July 1997, Christian Schwarz, schwarz@debian.org
+ Maintainer since 1997, Christian Schwarz, schwarz@debian.org
+ 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 packaging administrivia only.
+ -->
+
+ <book>
+ <titlepag>
+ <title>Debian Policy Manual</title>
+ <author>
+ <name>Ian Jackson </name>
+ <email>ijackson@gnu.ai.mit.edu</email>
+ </author>
+ <author>
+ <name>Christian Schwarz</name>
+ <email>schwarz@debian.org</email>
+ </author>
+ <author>
+ <name>revised: David A. Morris</name>
+ <email>bweaver@debian.org</email>
+ </author>
+ <author>
+ <name>The Debian Policy mailing List</name>
+ <email>debian-policy@lists.debian.org</email>
+ </author>
+ <version>version &version;, &date;</version>
+
+ <abstract>
+ This manual describes the policy requirements for the Debian
+ GNU/Linux distribution. This includes the structure and
+ contents of the Debian archive and several design issues of the
+ operating system, as well as technical requirements that each
+ 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>Philip Hands <email>phil@hands.com</email></p>
+ </item>
+ <item>
+ <p>Julian Gilbey <email>jdg@debian.org</email></p>
+ </item>
+ <item>
+ <p>Manoj Srivastava <email>srivasta@debian.org</email></p>
+ </item>
+ </enumlist>
+ </abstract>
+
+
+ <copyright>
+ <copyrightsummary>
+ Copyright ©1996,1997,1998 Ian Jackson
+ and Christian Schwarz.
+ </copyrightsummary>
+ <p>
+ This manual is free software; you may redistribute it and/or
+ modify it under the terms of the GNU General Public License
+ as published by the Free Software Foundation; either version
+ 2, or (at your option) any later version.
+ </p>
+
+ <p>
+ This is distributed in the hope that it will be useful, but
+ <em>without any warranty</em>; without even the implied
+ warranty of merchantability or fitness for a particular
+ purpose. See the GNU General Public License for more
+ details.
+ </p>
+
+ <p>
+ A copy of the GNU General Public License is available as
+ <tt>/usr/share/common-licenses/GPL</tt> in the Debian GNU/Linux
+ distribution or on the World Wide Web at
+ <url id="http://www.gnu.org/copyleft/gpl.html"
+ name="The GNU General Public Licence">. You can also obtain it by writing to the
+ Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ Boston, MA 02111-1307, USA.
+ </p>
+ </copyright>
+ </titlepag>
+
+ <toc detail="sect">
+
+ <chapt id="scope">
+ <heading>About this manual</heading>
+ <sect>
+ <heading>Scope</heading>
+ <p>
+ This manual describes the policy requirements for the Debian
+ GNU/Linux distribution. This includes the structure and
+ contents of the Debian archive and several design issues of the
+ operating system, as well as technical requirements that
+ each package must satisfy to be included in the
+ distribution.
+ </p>
+
+
+ <p>
+ This manual also describes Debian policy as it relates to
+ creating Debian packages. It is not a tutorial on how to build
+ packages, nor is it exhaustive where it comes to describing
+ the behavior of the packaging system. Instead, this manual
+ attempts to define the interface to the package management
+ system that the developers have to be conversant with.
+ <footnote>
+ <p>
+ Informally, the criteria used for inclusion is that the
+ material meet one of the following requirements:
+ <taglist>
+ <tag>Standard interfaces</tag>
+ <item>
+ <p>
+ The material presented represents an interface to
+ the packaging system that is mandated for use, and
+ is used by, a significant number of packages, and
+ therefore should not be changed without peer
+ review. Package maintainers can then rely on this
+ interfaces not changing, and the package
+ management software authors need to ensure
+ compatibility with these interface
+ definitions. (Control file and and changelog file
+ formats are examples.)
+ </p>
+ </item>
+ <tag>Chosen Convention</tag>
+ <item>
+ <p>
+ If there are a number of technically viable choices
+ that can be made, but one needs to select one of
+ these options for inter-operability. The version
+ number format is one example.
+ </p>
+ </item>
+ </taglist>
+ Please note that these are not mutually exclusive;
+ selected conventions often become parts of standard
+ interfaces.
+ </p>
+ </footnote>
+ </p>
+
+ <p>
+ The footnotes present in this manual are
+ merely informative, and are not part of Debian policy itself.
+ </p>
+
+
+ <p>
+ In this manual, the words <em>must</em>, <em>should</em> and
+ <em>may</em>, and the adjectives <em>required</em>,
+ <em>recommended</em> and <em>optional</em>, are used to
+ distinguish the significance of the various guidelines in
+ this policy document. Packages that do not conform the the
+ guidelines denoted by <em>must</em> (or <em>required</em>)
+ will generally not be considered acceptable for the Debian
+ distribution. Non-conformance with guidelines denoted by
+ <em>should</em> (or <em>recommended</em>) will generally be
+ considered a bug, but will not necessarily render a package
+ unsuitable for distribution. Guidelines denoted by
+ <em>may</em> (or <em>optional</em>) are truly optional and
+ adherence is left to the maintainer's discretion.
+ </p>
+ <p>
+ These classifications are roughly equivalent to the bug
+ severities <em>serious</em> (for <em>must</em> or
+ <em>required</em> directive violations), <em>minor</em>,
+ <em>normal</em> or <em>important</em>
+ (for <em>should</em> or <em>recommended</em> directive
+ violations) and <em>wishlist</em> (for <em>optional</em>
+ items). <footnote>
+ <p>Compare RFC 2119. Note, however, that these words are
+ used in a different way in this document.</p>
+ </footnote>
+ </p>
+ <p>
+ Much of the information presented in this manual will be
+ useful even when building a package which is to be
+ distributed in some other way or is intended for local use
+ only.
+ </p>
+ </sect>
+ <sect>
+ <heading>New versions of this document</heading>
+ <p>
+ The current version of this document is always accessible
+ from the Debian FTP server <ftpsite>ftp.debian.org</ftpsite>
+ as
+ <ftppath>/debian/doc/package-developer/policy.txt.gz</ftppath>
+ (also available from the same directory are several other
+ formats: <tt>policy.html.tar.gz</tt>, <tt>policy.pdf.gz</tt>
+ and <tt>policy.ps.gz</tt>) or from the <url
+ id="http://www.debian.org/doc/debian-policy/" name="Debian
+ Policy Manual"> webpage.</p>
+
+ <p>
+ In addition, this manual is distributed via the Debian package
+ <tt>debian-policy</tt>.
+ </p>
+
+ <p>
+ The <tt>debian-policy</tt> package also includes the file
+ <tt>upgrading-checklist.txt</tt> which indicates policy
+ changes between versions of this document.
+ </p>
+ </sect>
+ <sect>
+ <heading>Feedback</heading>
+
+ <p>
+ As the Debian GNU/Linux system is continuously evolving this
+ manual does so too.
+ </p>
+ <p>
+ While the authors of this document have tried hard to avoid
+ typos and other errors, these do still occur. If you discover
+ an error in this manual or if you want to give any
+ comments, suggestions, or criticisms please send an email to
+ the Debian Policy List,
+ <email>debian-policy@lists.debian.org</email>, or submit a
+ bug report against the <tt>debian-policy</tt> package.
+ </p>
+ </sect>
+ </chapt>
+ <chapt>
+ <heading>The Debian Archive</heading>
+ <p>
+ The Debian GNU/Linux system is maintained and distributed as a
+ collection of <em>packages</em>. Since there are so many of
+ them (currently well over 6000), they are split into
+ <em>sections</em> and given <em>priorities</em> to simplify
+ the handling of them.
+ </p>
+ <p>
+ The effort of the Debian project is to build a free operating
+ system, but not every package we want to make accessible is
+ <em>free</em> in our sense (see the Debian Free Software
+ Guidelines, below), or may be imported/exported without
+ restrictions. Thus, the archive is split into the sections
+ <em>main</em>, <em>non-free</em>, <em>contrib</em>,
+ <em>non-US/main</em>, <em>non-US/non-free</em>, and
+ <em>non-US/contrib</em>. The sections are explained in detail
+ below.
+ </p>
+
+ <p>
+ The <em>main</em> and the <em>non-US/main</em> sections
+ together form the <em>Debian GNU/Linux distribution</em>.
+ </p>
+
+ <p>
+ Packages in the other sections are not considered to be part
+ of the Debian distribution, although we support their use and
+ provide infrastructure for them (such as our bug-tracking
+ system and mailing lists). This Debian Policy Manual applies
+ to these packages as well.</p>
+
+ <sect id="pkgcopyright">
+ <heading>Package copyright and sections</heading>
+ <p>
+ The aims of this section are:
+
+ <list compact="compact">
+ <item>
+ <p>to allow us to make as much software available as we
+ can,</p>
+ </item>
+ <item>
+ <p>to allow us to encourage everyone to write free
+ software, and</p>
+ </item>
+ <item>
+ <p>to allow us to make it easy for people to produce
+ CD-ROMs of our system without violating any licenses,
+ import/export restrictions, or any other laws.</p>
+ </item>
+ </list>
+ </p>
+ <sect1>
+ <heading>The Debian Free Software Guidelines</heading>
+ <p>
+ The Debian Free Software Guidelines (DFSG) form our
+ definition of `free software'. These are:
+ <taglist>
+ <tag>Free Redistribution
+ </tag>
+ <item>
+ <p>
+ The license of a Debian component may not restrict any
+ party from selling or giving away the software as a
+ component of an aggregate software distribution
+ containing programs from several different
+ sources. The license may not require a royalty or
+ other fee for such sale.
+ </p>
+ </item>
+ <tag>Source Code
+ </tag>
+ <item>
+ <p>
+ The program must include source code, and must allow
+ distribution in source code as well as compiled form.
+ </p>
+ </item>
+ <tag>Derived Works
+ </tag>
+ <item>
+ <p>
+ The license must allow modifications and derived
+ works, and must allow them to be distributed under the
+ same terms as the license of the original software.
+ </p>
+ </item>
+ <tag>Integrity of The Author's Source Code
+ </tag>
+ <item>
+ <p>
+ The license may restrict source-code from being
+ distributed in modified form <em>only</em> if the
+ license allows the distribution of ``patch files''
+ with the source code for the purpose of modifying the
+ program at build time. The license must explicitly
+ permit distribution of software built from modified
+ source code. The license may require derived works to
+ carry a different name or version number from the
+ original software. (This is a compromise. The Debian
+ Project encourages all authors to not restrict any
+ files, source or binary, from being modified.)
+ </p>
+ </item>
+ <tag>No Discrimination Against Persons or Groups
+ </tag>
+ <item>
+ <p>
+ The license must not discriminate against any person
+ or group of persons.
+ </p>
+ </item>
+ <tag>No Discrimination Against Fields of Endeavor
+ </tag>
+ <item>
+ <p>
+ The license must not restrict anyone from making use
+ of the program in a specific field of endeavor. For
+ example, it may not restrict the program from being
+ used in a business, or from being used for genetic
+ research.
+ </p>
+ </item>
+ <tag>Distribution of License
+ </tag>
+ <item>
+ <p>
+ The rights attached to the program must apply to all
+ to whom the program is redistributed without the need
+ for execution of an additional license by those
+ parties.
+ </p>
+ </item>
+ <tag>License Must Not Be Specific to Debian
+ </tag>
+ <item>
+ <p>
+ The rights attached to the program must not depend on
+ the program's being part of a Debian system. If the
+ program is extracted from Debian and used or
+ distributed without Debian but otherwise within the
+ terms of the program's license, all parties to whom
+ the program is redistributed must have the same
+ rights as those that are granted in conjunction with
+ the Debian system.
+ </p>
+ </item>
+ <tag>License Must Not Contaminate Other Software
+ </tag>
+ <item>
+ <p>
+ The license must not place restrictions on other
+ software that is distributed along with the licensed
+ software. For example, the license must not insist
+ that all other programs distributed on the same medium
+ must be free software.
+ </p>
+ </item>
+ <tag>Example Licenses
+ </tag>
+ <item>
+ <p>
+ The ``GPL,'' ``BSD,'' and ``Artistic'' licenses are
+ examples of licenses that we consider <em>free</em>.
+ </p>
+ </item>
+ </taglist>
+ </p>
+ </sect1>
+ <sect1>
+ <heading>The main section</heading>
+ <p>
+ Every package in <em>main</em> and <em>non-US/main</em>
+ must comply with the DFSG (Debian Free Software
+ Guidelines).</p>
+
+ <p>
+ In addition, the packages in <em>main</em>
+ <list compact="compact">
+ <item>
+ <p>
+ must not require a package outside of <em>main</em>
+ for compilation or execution (thus, the package must
+ not declare a "Depends", "Recommends", or
+ "Build-Depends" relationship on a non-<em>main</em>
+ package),
+ </p>
+ </item>
+ <item>
+ <p>
+ must not be so buggy that we refuse to support them,
+ and
+ </p>
+ </item>
+ <item>
+ <p>
+ must meet all policy requirements presented in this
+ manual.
+ </p>
+ </item>
+ </list>
+ </p>
+ <p>
+ Similarly, the packages in <em>non-US/main</em>
+ <list compact="compact">
+ <item>
+ <p>
+ must not require a package outside of <em>main</em>
+ or <em>non-US/main</em> for compilation or
+ execution,
+ </p>
+ </item>
+ <item>
+ <p>
+ must not be so buggy that we refuse to support them,
+ </p>
+ </item>
+ <item>
+ <p>
+ must meet all policy requirements presented in this
+ manual.
+ </p>
+ </item>
+ </list>
+ </p>
+ </sect1>
+ <sect1>
+ <heading>The contrib section</heading>
+ <p>
+ Every package in <em>contrib</em> and
+ <em>non-US/contrib</em> must comply with the DFSG.
+ </p>
+
+ <p>
+ In addition, the packages in <em>contrib</em> and
+ <em>non-US/contrib</em>
+ <list compact="compact">
+ <item>
+ <p>
+ must not be so buggy that we refuse to support them,
+ and
+ </p>
+ </item>
+ <item>
+ <p>
+ must meet all policy requirements presented in this
+ manual.
+ </p>
+ </item>
+ </list>
+ </p>
+
+ <p>
+ Furthermore, packages in <em>contrib</em> must not require
+ a package in a <em>non-US</em> section for compilation or
+ execution.
+ </p>
+
+ <p>
+ Examples of packages which would be included in
+ <em>contrib</em> or <em>non-US/contrib</em> are:
+ <list compact="compact">
+ <item>
+ <p>
+ free packages which require <em>contrib</em>,
+ <em>non-free</em> packages or packages which are not
+ in our archive at all for compilation or execution,
+ and
+ </p>
+ </item>
+ <item>
+ <p>
+ wrapper packages or other sorts of free accessories for
+ non-free programs.
+ </p>
+ </item>
+ </list>
+ </p>
+ </sect1>
+ <sect1>
+ <heading>The non-free section</heading>
+ <p>
+ Packages must be placed in <em>non-free</em> or
+ <em>non-US/non-free</em> if they are not compliant with
+ the DFSG or are encumbered by patents or other legal
+ issues that make their distribution problematic.
+ </p>
+ <p>
+ In addition, the packages in <em>non-free</em> and
+ <em>non-US/non-free</em>
+ <list compact="compact">
+ <item>
+ <p>
+ must not be so buggy that we refuse to support them,
+ and
+ </p>
+ </item>
+ <item>
+ <p>
+ must meet all policy requirements presented in this
+ manual that it is possible for them to meet.
+ <footnote>
+ <p>
+ It is possible that there are policy
+ requirements which the package is unable to
+ meet, for example, if the source is
+ unavailable. These situations will need to be
+ handled on a case-by-case basis.
+ </p>
+ </footnote>
+ </p>
+ </item>
+ </list>
+ </p>
+ </sect1>
+
+ <sect1>
+ <heading>The non-US sections</heading>
+ <p>
+ Some programs with cryptographic program code need to be
+ stored on the <em>non-US</em> server because of United
+ States export restrictions. Such programs must be
+ distributed in the appropriate <em>non-US</em> section,
+ either <em>non-US/main</em>, <em>non-US/contrib</em> or
+ <em>non-US/non-free</em>.
+ </p>
+ <p>
+ This applies only to packages which contain cryptographic
+ code. A package containing a program with an interface to
+ a cryptographic program or a program that's dynamically
+ linked against a cryptographic library should not be
+ distributed via the <em>non-US</em> server if it is
+ capable of running without the cryptographic library or
+ program.
+ </p>
+ </sect1>
+ <sect1>
+ <heading>Further copyright considerations</heading>
+ <p>
+ Every package must be accompanied by a verbatim copy of
+ its copyright and distribution license in the file
+ <tt>/usr/share/doc/<ital><package-name></ital>/copyright</tt>
+ (see <ref id="copyrightfile"> for further details).
+ </p>
+ <p>
+ We reserve the right to restrict files from being included
+ anywhere in our archives if
+ <list compact="compact">
+ <item>
+ <p>
+ their use or distribution would break a law,
+ </p>
+ </item>
+ <item>
+ <p>
+ there is an ethical conflict in their distribution or
+ use,
+ </p>
+ </item>
+ <item>
+ <p>
+ we would have to sign a license for them, or
+ </p>
+ </item>
+ <item>
+ <p>
+ their distribution would conflict with other project
+ policies.
+ </p>
+ </item>
+ </list>
+ </p>
+
+ <p>
+ Programs whose authors encourage the user to make
+ donations are fine for the main distribution, provided
+ that the authors do not claim that not donating is
+ immoral, unethical, illegal or something similar; in such
+ a case they must go in <em>non-free</em>.</p>
+
+ <p>
+ Packages whose copyright permission notices (or patent
+ problems) do not even allow redistribution of binaries
+ only, and where no special permission has been obtained,
+ must not be placed on the Debian FTP site and its mirrors
+ at all.</p>
+
+ <p>
+ Note that under international copyright law (this applies
+ in the United States, too), <em>no</em> distribution or
+ modification of a work is allowed without an explicit
+ notice saying so. Therefore a program without a copyright
+ notice <em>is</em> copyrighted and you may not do anything
+ to it without risking being sued! Likewise if a program
+ has a copyright notice but no statement saying what is
+ permitted then nothing is permitted.</p>
+
+ <p>
+ Many authors are unaware of the problems that restrictive
+ copyrights (or lack of copyright notices) can cause for
+ the users of their supposedly-free software. It is often
+ worthwhile contacting such authors diplomatically to ask
+ them to modify their license terms. However, this can be a
+ politically difficult thing to do and you should ask for
+ advice on the <tt>debian-legal</tt> mailing list first, as
+ explained below.
+ </p>
+
+ <p>
+ When in doubt about a copyright, send mail to
+ <email>debian-legal@lists.debian.org</email>. Be prepared
+ to provide us with the copyright statement. Software
+ covered by the GPL, public domain software and BSD-like
+ copyrights are safe; be wary of the phrases `commercial
+ use prohibited' and `distribution restricted'.
+ </p>
+ </sect1>
+ <sect1>
+ <heading>Subsections</heading>
+
+ <p>
+ The packages in the sections <em>main</em>,
+ <em>contrib</em> and <em>non-free</em> are grouped further
+ into <em>subsections</em> to simplify handling.
+ </p>
+
+ <p>
+ The section and subsection for each package should be
+ specified in the package's <tt>Section</tt> control
+ record. However, the maintainer of the Debian archive
+ may override this selection to ensure the consistency of
+ the Debian distribution. The <tt>Section</tt> field
+ should be of the form:
+ <list compact="compact">
+ <item>
+ <p>
+ <ital>subsection</ital> if the package is in the
+ <em>main</em> section,
+ </p>
+ </item>
+ <item>
+ <p>
+ <ital>section/subsection</ital> if the package is in
+ the <em>contrib</em> or <em>non-free</em> section,
+ and
+ </p>
+ </item>
+ <item>
+ <p>
+ <tt>non-US</tt>, <tt>non-US/contrib</tt> or
+ <tt>non-US/non-free</tt> if the package is in
+ <em>non-US/main</em>, <em>non-US/contrib</em> or
+ <em>non-US/non-free</em> respectively.
+ </p>
+ </item>
+ </list>
+ </p>
+
+ <p>
+ The Debian archive maintainers provide the authoritative
+ list of subsections. At present, they are:
+ <em>admin</em>, <em>base</em>, <em>comm</em>,
+ <em>contrib</em>, <em>devel</em>, <em>doc</em>,
+ <em>editors</em>, <em>electronics</em>, <em>games</em>,
+ <em>graphics</em>, <em>hamradio</em>,
+ <em>interpreters</em>, <em>libs</em>, <em>mail</em>,
+ <em>math</em>, <em>misc</em>, <em>net</em>, <em>news</em>,
+ <em>non-US</em>, <em>non-free</em>, <em>oldlibs</em>,
+ <em>otherosfs</em>, <em>science</em>, <em>shells</em>,
+ <em>sound</em>, <em>tex</em>, <em>text</em>,
+ <em>utils</em>, <em>web</em>, <em>x11</em>.
+ </p>
+ </sect1>
+ <sect>
+ <heading>Priorities</heading>
+
+ <p>
+ Each package should have a <em>priority</em> value, which is
+ included in the package's <em>control record</em>. This
+ information is used by the Debian package management tools
+ to separate high-priority packages from less-important
+ packages.</p>
+
+ <p>
+ The following <em>priority levels</em> are recognised by the
+ Debian package management tools.
+ <taglist>
+ <tag><tt>required</tt></tag>
+ <item>
+ <p>
+ Packages which are necessary for the proper
+ functioning of the system. You must not remove these
+ packages or your system may become totally broken and
+ you may not even be able to use <prgn>dpkg</prgn> to
+ put things back. Systems with only the
+ <tt>required</tt> packages are probably unusable, but
+ they do have enough functionality to allow the
+ sysadmin to boot and install more software.</p>
+ </item>
+ <tag><tt>important</tt></tag>
+ <item>
+ <p>
+ Important programs, including those which one would
+ expect to find on any Unix-like system. If the
+ expectation is that an experienced Unix person who
+ found it missing would say `What on earth is going on,
+ where is <prgn>foo</prgn>?', it must be an
+ <tt>important</tt> package.
+ <footnote>
+ <p>
+ This is an important criterion because we are
+ trying to produce, amongst other things, a free
+ Unix.
+ </p>
+ </footnote>
+ Other packages without which the system will not run
+ well or be usable must also have priority
+ <tt>important</tt>. 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>
+ <p>
+ These packages provide a reasonably small but not too
+ limited character-mode system. This is what will
+ install by default if the user doesn't select anything
+ else. It doesn't include many large applications, but
+ it does include Emacs (this is more of a piece of
+ infrastructure than an application) and a reasonable
+ subset of TeX and LaTeX.</p>
+ </item>
+ <tag><tt>optional</tt></tag>
+ <item>
+ <p>
+ (In a sense everything that isn't required is
+ optional, but that's not what is meant here.) This is
+ all the software that you might reasonably want to
+ install if you didn't know what it was and don't have
+ specialized requirements. This is a much larger system
+ and includes the X Window System, a full TeX
+ distribution, and many applications. Note that
+ optional packages should not conflict with each other.
+ </p>
+ </item>
+ <tag><tt>extra</tt></tag>
+ <item>
+ <p>
+ This contains all packages that conflict with others
+ with required, important, standard or optional
+ priorities, or are only likely to be useful if you
+ already know what they are or have specialised
+ requirements.
+ </p>
+ </item>
+ </taglist></p>
+
+ <p>
+ Packages must not depend on packages with lower priority
+ values (excluding build-time dependencies). In order to
+ ensure this, the priorities of one or more packages may need
+ to be adjusted.
+ </p>
+ </sect>
+
+ <sect>
+ <heading>Binary packages</heading>
+
+ <p>
+ The Debian GNU/Linux distribution is based on the Debian
+ package management system, called <prgn>dpkg</prgn>. Thus,
+ all packages in the Debian distribution must be provided
+ in the <tt>.deb</tt> file format.</p>
+
+
+ <sect1>
+ <heading>The package name</heading>
+
+ <p>
+ Every package must have a name that's unique within the Debian
+ archive.</p>
+
+ <p>
+ Package names must consist of lower case letters (a-z),
+ digits (0-9), plus (+) and minus (-) signs, and periods
+ (.). They must be at least two characters long and must
+ contain at least one letter.
+ </p>
+
+ <p>
+ The package name is part of the file name of the
+ <tt>.deb</tt> file and is included in the control field
+ information.
+ </p>
+ </sect1>
+
+ <sect1>
+ <heading>The maintainer of a package</heading>
+ <p>
+ Every package must have a Debian maintainer (the
+ maintainer may be one person or a group of people
+ reachable from a common email address, such as a mailing
+ list). The maintainer is responsible for ensuring that
+ the package is placed in the appropriate distributions.
+ </p>
+
+ <p>
+ The maintainer must be specified in the
+ <tt>Maintainer</tt> control field with their correct name
+ and a working email address. If one person maintains
+ several packages, he/she should try to avoid having
+ different forms of their name and email address in
+ the <tt>Maintainer</tt> fields of those packages.
+ </p>
+
+ <p>
+ If the maintainer of a package quits from the Debian
+ project, "Debian QA Group"
+ <email>packages@qa.debian.org</email> takes over the
+ maintainership of the package until someone else
+ volunteers for that task. These packages are called
+ <em>orphaned packages</em>.
+ <footnote>
+ <p>
+ The detailed procedure for doing this gracefully can
+ be found in the Debian Developer's Reference, either
+ in the <tt>developers-reference</tt> package, or on
+ the Debian FTP server
+ <ftpsite>ftp.debian.org</ftpsite> as
+ <ftppath>/debian/doc/package-developer/developers-reference.txt.gz</ftppath>
+ or from the <url
+ id="http://www.debian.org/doc/packaging-manuals/developers-reference/"
+ name="Debian Developer's Reference"> webpage.
+ </p>
+ </footnote>
+ </p>
+ </sect1>
+
+
+ <sect1>
+ <heading>The description of a package</heading>
+
+ <p>
+ Every Debian package must have an extended description
+ stored in the appropriate field of the control record.</p>
+
+ <p>
+ The description should be written so that it gives the
+ system administrator enough information to decide whether
+ to install the package. This description should not just
+ be copied verbatim from the program's documentation.
+ Instructions for configuring or using the package should
+ not be included -- that is what installation scripts,
+ manual pages, info files, etc., are for. Copyright
+ statements and other administrivia should not be included
+ either -- that is what the copyright file is for.</p>
+ </sect1>
+
+
+ <sect1>
+ <heading>Dependencies</heading>
+
+ <p>
+ Every package must specify the dependency information
+ about other packages that are required for the first to
+ work correctly.</p>
+
+ <p>
+ For example, a dependency entry must be provided for any
+ shared libraries required by a dynamically-linked executable
+ binary in a package.</p>
+
+ <p>
+ Packages are not required to declare any dependencies they
+ have on other packages which are marked <tt>Essential</tt>
+ (see below), and should not do so unless they depend on a
+ particular version of that package.</p>
+
+ <p>
+ Sometimes, a package requires another package to be installed
+ <em>and</em> configured before it can be installed. In this
+ case, you must specify a <tt>Pre-Depends</tt> entry for
+ the package.</p>
+
+ <p>
+ You should not specify a <tt>Pre-Depends</tt> entry for a
+ package before this has been discussed on the
+ <tt>debian-devel</tt> mailing list and a consensus about
+ doing that has been reached.</p></sect1>
+
+
+ <sect1>
+ <heading>Virtual packages</heading>
+
+ <p>
+ Sometimes, there are several packages which offer
+ more-or-less the same functionality. In this case, it's
+ useful to define a <em>virtual package</em> whose name
+ describes that common functionality. (The virtual
+ packages only exist logically, not physically--that's why
+ they are called <em>virtual</em>.) The packages with this
+ particular function will then <em>provide</em> the virtual
+ package. Thus, any other package requiring that function
+ can simply depend on the virtual package without having to
+ specify all possible packages individually.</p>
+
+ <p>
+ All packages should use virtual package names where
+ appropriate, and arrange to create new ones if necessary.
+ They should not use virtual package names (except privately,
+ amongst a cooperating group of packages) unless they have
+ been agreed upon and appear in the list of virtual package
+ names.</p>
+
+ <p>
+ The latest version of the authoritative list of virtual
+ package names can be found on
+ <ftpsite>ftp.debian.org</ftpsite> in
+ <ftppath>/debian/doc/package-developer/virtual-package-names-list.txt</ftppath>
+ or your local mirror. In addition, it is included in the
+ <tt>debian-policy</tt> package. The procedure for updating
+ the list is described at the top of the file.</p></sect1>
+
+
+ <sect1>
+ <heading>Base packages</heading>
+
+ <p>
+ The packages included in the <tt>base</tt> section have a
+ special function. They form a minimum subset of the Debian
+ GNU/Linux system that is installed before everything else
+ on a new system. Thus, only very few packages are allowed
+ to go into the <tt>base</tt> section to keep the required
+ disk usage very small.</p>
+
+ <p>
+ Most of these packages will have the priority value
+ <tt>required</tt> or at least <tt>important</tt>, and many
+ of them will be tagged <tt>essential</tt> (see below).</p>
+
+ <p>
+ You must not place any packages into the <tt>base</tt>
+ section before this has been discussed on the
+ <tt>debian-devel</tt> mailing list and a consensus about
+ doing that has been reached.</p></sect1>
+
+
+ <sect1>
+ <heading>Essential packages</heading>
+
+ <p>
+ Some packages are tagged <tt>essential</tt>. (They have
+ <tt>Essential: yes</tt> in their package control record.)
+ This flag is used for packages that are <em>essential</em>
+ for a system.</p>
+
+ <p>
+ Since these packages cannot be easily removed (one has to
+ specify an extra <em>force option</em> to
+ <prgn>dpkg</prgn> to do so), this flag must not be used
+ unless absolutely necessary. A shared library package
+ must not be tagged <tt>essential</tt>--dependencies will
+ prevent its premature removal, and we need to be able to
+ remove it when it has been superseded.
+ </p>
+
+ <p>
+ Since dpkg will not prevent upgrading of other packages
+ while an <tt>essential</tt> package is in an unconfigured
+ state, all <tt>essential</tt> packages must supply all of
+ their core functionality even when unconfigured. If the
+ package cannot satisfy this requirement it must not be
+ tagged as essential, and any packages depending on this
+ package must instead have explicit dependency fields as
+ appropriate.
+ </p>
+
+ <p>
+ You must not tag any packages <tt>essential</tt> before
+ this has been discussed on the <tt>debian-devel</tt>
+ mailing list and a consensus about doing that has been
+ reached.
+ </p>
+ </sect1>
+
+ <sect1>
+ <heading>Maintainer scripts</heading>
+
+ <p>
+ The package installation scripts should avoid producing
+ output which it is unnecessary for the user to see and
+ should rely on <prgn>dpkg</prgn> to stave off boredom on
+ the part of a user installing many packages. This means,
+ amongst other things, using the <tt>--quiet</tt> option on
+ <prgn>install-info</prgn>.</p>
+
+ <p>
+ Errors which occur during the execution of an installation
+ script must be checked and the installation must not
+ continue after an error.
+ </p>
+
+ <p>
+ Note that in general <ref id="scripts"> applies to package
+ maintainer scripts, too.
+ </p>
+
+ <p>
+ You should not use <tt>dpkg-divert</tt> on a file
+ belonging to another package without consulting the
+ maintainer of that package first.
+ </p>
+ <p>
+ All packages which supply an instance of a common command
+ name (or, in general, filename) should generally use
+ <prgn>update-alternatives</prgn>, so that they may be
+ installed together. If <prgn>update-alternatives</prgn>
+ is not used, then each package must use
+ <var>Conflicts</var> to ensure that other packages are
+ de-installed. (In this case, it may be appropriate to
+ specify a conflict against earlier versions of something
+ that previously did not use
+ <prgn>update-alternatives</prgn> - this is an exception to
+ the usual rule that versioned conflicts should be
+ avoided).
+ </p>
+
+
+ <sect2>
+ <heading>Prompting in maintainer scripts</heading>
+ <p>
+ Package maintainer scripts may prompt the user if
+ necessary. Prompting may be accomplished by hand, or by
+ communicating with a program, such as
+ <prgn>debconf</prgn>, which conforms to the Debian
+ Configuration management specification, version 2 or
+ higher. These are included in the
+ <file>debconf_specification</file> files in the
+ <package>debian-policy</package> package.
+ You may also find this file on the FTP site
+ <ftpsite>ftp.debian.org</ftpsite> in
+ <ftppath>/debian/doc/package-developer/debconf_specification.txt.gz</ftppath>
+ or on your local mirror.
+ <footnote>
+ <p>
+ 2.5% of Debian packages [see <url
+ id="http://kitenet.net/programs/debconf/stats/">]
+ currently use <package>debconf</package> to prompt
+ the user at install time, and this number is growing
+ daily. The benefits of using debconf are briefly
+ explained at <url
+ id="http://kitenet.net/doc/debconf-doc/introduction.html">;
+ they include preconfiguration, (mostly)
+ noninteractive installation, elimination of
+ redundant prompting, consistency of user interface,
+ etc.
+ </p>
+ <p>
+ With this increasing number of packages using
+ <package>debconf</package>, plus the existance of a
+ nascent second implementation of the Debian
+ configuration management system
+ (<package>cdebconf</package>), and the stabalization
+ of the protocol these things use, the time has
+ finally come to reflect the use of these things in
+ policy.
+
+ </p>
+ </footnote>
+ </p>
+ <p>
+ Packages which use the Debian Configuration management
+ specification may contain an additional
+ <file>config</file> script and a <file>templates</file>
+ file in their control archive. The <prgn>config</prgn>
+ script might be run before the <prgn>preinst</prgn>
+ script, and before the package is unpacked or any of its
+ dependancies or pre-dependancies are satisfied.
+ Therefore it must work using only the tools present in
+ <em>essential</em> packages.
+ <footnote>
+ <p>
+ <package>Debconf</package> or another tool that
+ implements the Debian Configuration management
+ specification will also be installed, and any
+ versioned dependencies on it will be satisfied
+ before preconfiguration begins.
+ </p>
+ </footnote>
+ </p>
+
+ <p>
+ Packages should try to minimize the amount of prompting
+ they need to do, and they should ensure that the user
+ will only ever be asked each question once. This means
+ that packages should try to use appropriate shared
+ configuration files (such as <tt>/etc/papersize</tt> and
+ <tt>/etc/news/server</tt>), and shared
+ <package>debconf</package> variables rather than each
+ prompting for their own list of required pieces of
+ information.
+ </p>
+
+ <p>
+ It also means that an upgrade should not ask the same
+ questions again, unless the user has used <tt>dpkg
+ --purge</tt> to remove the package's configuration. The
+ answers to configuration questions should be stored in an
+ appropriate place in <tt>/etc</tt> so that the user can
+ modify them, and how this has been done should be
+ documented.</p>
+
+ <p>
+ If a package has a vitally important piece of
+ information to pass to the user (such as "don't run me
+ as I am, you must edit the following configuration files
+ first or you risk your system emitting badly-formatted
+ messages"), it should display this in the
+ <prgn>config</prgn> or <prgn>postinst</prgn> script and
+ prompt the user to hit return to acknowledge the
+ message. Copyright messages do not count as vitally
+ important (they belong in
+ <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>
+
+ <p>
+ Any necessary prompting should almost always be confined
+ to the <prgn>config</prgn> or <prgn>postinst</prgn>
+ script. If it is done in the <prgn>postinst</prgn>, it
+ should be protected with a conditional so that unnecessary
+ prompting doesn't happen if a package's installation fails
+ and the <prgn>postinst</prgn> is called with
+ <tt>abort-upgrade</tt>, <tt>abort-remove</tt> or
+ <tt>abort-deconfigure</tt>.</p>
+
+ </sect1>
+ </sect>
+ <sect>
+ <heading>Source packages</heading>
+
+ <sect1>
+ <heading>Standards conformance</heading>
+
+ <p>
+ In the source package's <tt>Standards-Version</tt> control
+ field, you must specify the most recent version number of
+ this policy document with which your package complies.
+ The current version number is &version;.
+ </p>
+
+ <p>
+ This information may be used to file bug reports
+ automatically if your package becomes too much out of
+ date.
+ </p>
+
+ <p>
+ The version number has four components--major and minor
+ version number and major and minor patch level. When the
+ standards change in a way that requires every package to
+ change the major number will be changed. Significant
+ changes that will require work in many packages will be
+ signaled by a change to the minor number. The major patch
+ level will be changed for any change to the meaning of the
+ standards, however small; the minor patch level will be
+ changed when only cosmetic, typographical or other edits
+ are made which neither change the meaning of the document
+ nor affect the contents of packages.</p>
+
+ <p>
+ Thus only the first three components of the policy version
+ are significant in the <em>Standards-Version</em> control
+ field, and so either these three components or the all
+ four components may be specified.
+ <footnote>
+ <p>
+ In the past, people specified the full version number
+ in the Standards-Version field, for example `2.3.0.0'.
+ Since minor patch-level changes don't introduce new
+ policy, it was thought it would be better to relax
+ policy and only require the first 3 components to be
+ specified, in this example `2.3.0'. All four
+ components may still be used if someone wishes to do
+ so.
+ </p>
+ </footnote>
+ </p>
+
+ <p>
+ You should regularly, and especially if your package has
+ become out of date, check for the newest Policy Manual
+ available and update your package, if necessary. When your
+ package complies with the new standards you should update the
+ <tt>Standards-Version</tt> source package field and
+ release it.
+ <footnote>
+ <p>
+ See the file <tt>upgrading-checklist</tt> for
+ information about policy which has changed between
+ different versions of this document.
+ </p>
+ </footnote>
+ </p>
+ </sect1>
+
+
+ <sect1>
+ <heading>Package relationships</heading>
+
+ <p>
+ Source packages should specify which binary packages they
+ require to be installed or not to be installed in order to
+ build correctly. For example, if building a package
+ requires a certain compiler, then the compiler should be
+ specified as a build-time dependency.
+ </p>
+
+ <p>
+ It is not necessary to explicitly specify build-time
+ relationships on a minimal set of packages that are always
+ needed to compile, link and put in a Debian package a
+ standard "Hello World!" program written in C or C++. The
+ required packages are called <em>build-essential</em>, and
+ an informational list can be found in
+ <tt>/usr/share/doc/build-essential/list</tt> (which is
+ contained in the <tt>build-essential</tt>
+ package).
+ <footnote>
+ <p>Rationale:
+ <list>
+ <item>
+ <p>This allows maintaining the list separately
+ from the policy documents (the list does not
+ need the kind of control that the policy
+ documents do).
+ </p>
+ </item>
+ <item>
+ <p>
+ Having a separate package allows one to install
+ the build-essential packages on a machine, as
+ well as allowing other packages such as task
+ packages to require installation of the
+ build-essential packages using the depends
+ relation.
+ </p>
+ </item>
+ <item>
+ <p>
+ The separate package allows bug reports against
+ the list to be categorized separately from
+ the policy management process in the BTS.
+ </p>
+ </item>
+ </list>
+ </p>
+
+ </footnote>
+ </p>
+
+ <p>
+ When specifying the set of build-time dependencies, one
+ should list only those packages explicitly required by the
+ build. It is not necessary to list packages which are
+ required merely because some other package in the list of
+ build-time dependencies depends on them.
+ <footnote>
+ <p>
+ The reason for this is that dependencies change, and
+ you should list all those packages, and <em>only</em>
+ those packages that <em>you</em> need directly. What
+ others need is their business. For example, if you
+ only link against <tt>libimlib</tt>, you will need to
+ build-depend on <package>libimlib2-dev</package> but
+ not against any <tt>libjpeg*</tt> packages, even
+ though <tt>libimlib2-dev</tt> currently depends on
+ them: installation of <package>libimlib2-dev</package>
+ will automatically ensure that all of its run-time
+ dependencies are satisfied.
+ </p>
+ </footnote>
+ </p>
+
+ <p>
+ If build-time dependencies are specified, it must be
+ possible to build the package and produce working binaries
+ on a system with only essential and build-essential
+ packages installed and also those required to satisfy the
+ build-time relationships (including any implied
+ relationships). In particular, this means that version
+ clauses should be used rigorously in build-time
+ relationships so that one cannot produce bad or
+ inconsistently configured packages when the relationships
+ are properly satisfied.
+ </p>
+
+ <sect1>
+ <heading>Changes to the upstream sources</heading>
+
+ <p>
+ If changes to the source code are made that are not
+ specific to the needs of the Debian system, they should be
+ sent to the upstream authors in whatever form they prefer
+ so as to be included in the upstream version of the
+ package.</p>
+
+ <p>
+ If you need to configure the package differently for
+ Debian or for Linux, and the upstream source doesn't
+ provide a way to do so, you should add such configuration
+ facilities (for example, a new <prgn>autoconf</prgn> test
+ or <tt>#define</tt>) and send the patch to the upstream
+ authors, with the default set to the way they originally
+ had it. You can then easily override the default in your
+ <tt>debian/rules</tt> or wherever is appropriate.</p>
+
+ <p>
+ You should make sure that the <prgn>configure</prgn> utility
+ detects the correct architecture specification string
+ (refer to <ref id="arch-spec"> for details).</p>
+
+ <p>
+ If you need to edit a <prgn>Makefile</prgn> where
+ GNU-style <prgn>configure</prgn> scripts are used, you
+ should edit the <tt>.in</tt> files rather than editing the
+ <prgn>Makefile</prgn> directly. This allows the user to
+ reconfigure the package if necessary. You should
+ <em>not</em> configure the package and edit the generated
+ <prgn>Makefile</prgn>! This makes it impossible for
+ someone else to later reconfigure the package.</p></sect1>
+
+
+ <sect1>
+ <heading>Documenting your changes</heading>
+
+ <p>
+ You should document your changes and updates to the source
+ package properly in the <tt>debian/changelog</tt> file. (Note
+ that mistakes in changelogs are usually best rectified by
+ making a new changelog entry rather than "rewriting history"
+ by editing old changelog entries.)</p>
+
+ <p>
+ In non-experimental packages you must use a format for
+ <tt>debian/changelog</tt> which is supported by the most
+ recent released version of <prgn>dpkg</prgn>.
+ <footnote>
+ <p>
+ If you wish to use an alternative format, you may do
+ so as long as you include a parser for it in your
+ source package. The parser must have an API
+ compatible with that expected by
+ <prgn>dpkg-genchanges</prgn> and
+ <prgn>dpkg-gencontrol</prgn>. If there is general
+ interest in the new format, you should contact the
+ <package>dpkg</package> maintainer to have the parser
+ script for it included in the <prgn>dpkg</prgn>
+ package. (You will need to agree that the parser and
+ its manpage may be distributed under the GNU GPL, just
+ as the rest of `dpkg' is.)
+ </p>
+ </footnote>
+ </p>
+ </sect1>
+
+
+ <sect1>
+ <heading>Error trapping in makefiles</heading>
+
+ <p>
+ When <prgn>make</prgn> invokes a command in a makefile
+ (including your package's upstream makefiles and
+ <tt>debian/rules</tt>), it does so using <tt>sh</tt>. This
+ means that <tt>sh</tt>'s usual bad error handling
+ properties apply: if you include a miniature script as one
+ of the commands in your makefile you'll find that if you
+ don't do anything about it then errors are not detected
+ and <prgn>make</prgn> will blithely continue after
+ problems.</p>
+
+ <p>
+ Every time you put more than one shell command (this
+ includes using a loop) in a makefile command you
+ must make sure that errors are trapped. For
+ simple compound commands, such as changing directory and
+ then running a program, using <tt>&&</tt> rather
+ than semicolon as a command separator is sufficient. For
+ more complex commands including most loops and
+ conditionals you should include a separate <tt>set -e</tt>
+ command at the start of every makefile command that's
+ actually one of these miniature shell scripts.</p></sect1>
+
+
+ <sect1>
+ <heading>Obsolete constructs and libraries</heading>
+
+ <p>
+ The include file <prgn><varargs.h></prgn> is
+ provided to support end-users compiling very old software;
+ the library <tt>libtermcap</tt> is provided to support the
+ execution of software which has been linked against it
+ (either old programs or those such as Netscape which are
+ only available in binary form).</p>
+
+ <p>
+ Debian packages should be patched to use
+ <prgn><stdarg.h></prgn> and <tt>ncurses</tt>
+ instead.
+ </p>
+ </sect1>
+ </sect>
+ </chapt>
+
+ <chapt id="controlfields"><heading>Control files and their fields</heading>
+
+ <p>
+ Many of the tools in the package management suite manipulate
+ data in a common format, known as control files. Binary and
+ source packages have control data as do the <tt>.changes</tt>
+ files which control the installation of uploaded files, and
+ <prgn>dpkg</prgn>'s internal databases are in a similar
+ format.
+ </p>
+
+ <sect><heading>Syntax of control files</heading>
+
+ <p>
+ A file consists of one or more paragraphs of fields. The
+ paragraphs are separated by blank lines. Some control files
+ only allow one paragraph; others allow several, in which
+ case each paragraph often refers to a different package.
+ </p>
+
+ <p>
+ Each paragraph is a series of fields and values; each field
+ consists of a name, followed by a colon and the value. It
+ ends at the end of the line. Horizontal whitespace (spaces
+ and tabs) may occur immediately before or after the value
+ and is ignored there; it is conventional to put a single
+ space after the colon.
+ </p>
+
+ <p>
+ Some fields' values may span several lines; in this case
+ each continuation line <em>must</em> start with a space or
+ tab. Any trailing spaces or tabs at the end of individual
+ lines of a field value are ignored.
+ </p>
+
+ <p>
+ Except where otherwise stated only a single line of data is
+ allowed and whitespace is not significant in a field body.
+ Whitespace may never appear inside names (of packages,
+ architectures, files or anything else), version numbers or
+ in between the characters of multi-character version
+ relationships.
+ </p>
+
+ <p>
+ Field names are not case-sensitive, but it is usual to
+ capitalize the field names using mixed case as shown below.
+ </p>
+
+ <p>
+ Blank lines, or lines consisting only of spaces and tabs,
+ are not allowed within field values or between fields - that
+ would mean a new paragraph.
+ </p>
+
+ <p>
+ It is important to note that there are several fields which
+ are optional as far as <prgn>dpkg</prgn> and the related
+ tools are concerned, but which must appear in every Debian
+ package, or whose omission may cause problems. When writing
+ the control files for Debian packages you <em>must</em> read
+ the Debian policy manual in conjunction with the details
+ below and the list of fields for the particular file.</p>
+ </sect>
+
+ <sect><heading>List of fields</heading>
+ <p>
+ This list here is not supposed to be exhaustive. Most fields
+ are dealt with elsewhere in this document and in the
+ packaging manual.
+ </p>
+ <sect1 id="f-Package"><heading><tt>Package</tt>
+ </heading>
+
+ <p>
+ The name of the binary package. Package names consist of
+ the alphanumerics and <tt>+</tt> <tt>-</tt> <tt>.</tt>
+ (plus, minus and full stop).
+ </p>
+
+ <p>
+ They must be at least two characters long and must start
+ with an alphanumeric character. The use of lowercase
+ package names is strongly recommended unless the package
+ you're building (or referring to, in other fields) is
+ already using uppercase.</p>
+ </sect1>
+
+ <sect1 id="f-Version"><heading><tt>Version</tt>
+ </heading>
+
+ <p>
+ This lists the source or binary package's version number -
+ see <ref id="versions">.
+ </p>
+
+ </sect1>
+
+ <sect1
+ id="f-Standards-Version"><heading><tt>Standards-Version</tt>
+ </heading>
+
+ <p>
+ The most recent version of the standards (the policy
+ manual and associated texts) with which the package
+ complies. This is updated manually when editing the
+ source package to conform to newer standards; it can
+ sometimes be used to tell when a package needs attention.
+ </p>
+
+ <p>
+ Its format is the same as that of a version number except
+ that no epoch or Debian revision is allowed - see <ref
+ id="versions">.</p>
+ </sect1>
+
+
+ <sect1 id="f-Distribution"><heading><tt>Distribution</tt>
+ </heading>
+
+ <p>
+ In a <tt>.changes</tt> file or parsed changelog output
+ this contains the (space-separated) name(s) of the
+ distribution(s) where this version of the package should
+ be or was installed. Distribution names follow the rules
+ for package names. (See <ref id="f-Package">).
+ </p>
+
+ <p>
+ <footnote>
+ Current distribution values are:
+ <taglist>
+ <tag><em>stable</em></tag>
+ <item>
+ <p>
+ This is the current `released' version of Debian
+ GNU/Linux. Once the
+ distribution is <em>stable</em> only major bug fixes
+ are allowed. When changes are made to this
+ distribution, the release number is increased
+ (for example: 1.2r1 becomes 1.2r2 then 1.2r3, etc).
+ </p>
+ </item>
+
+ <tag><em>unstable</em></tag>
+ <item>
+ <p>
+ This distribution value refers to the
+ <em>developmental</em> part of the Debian
+ distribution tree. New packages, new upstream
+ versions of packages and bug fixes go into the
+ <em>unstable</em> directory tree. Download from
+ this distribution at your own risk.
+ </p>
+ </item>
+
+ <tag><em>frozen</em></tag>
+ <item>
+ <p>
+ From time to time, the <em>unstable</em>
+ distribution enters a state of `code-freeze' in
+ anticipation of release as a <em>stable</em>
+ version. During this period of testing only
+ fixes for existing or newly-discovered bugs will
+ be allowed.
+ </p>
+ </item>
+
+ <tag><em>experimental</em></tag>
+ <item>
+ <p>
+ The packages with this distribution value are deemed
+ by their maintainers to be high risk. Oftentimes they
+ represent early beta or developmental packages from
+ various sources that the maintainers want people to
+ try, but are not ready to be a part of the other parts
+ of the Debian distribution tree. Download at your own
+ risk.
+ </p>
+ </item>
+ </taglist>
+ There are several sections in each
+ distribution. Currently, these sections are:
+
+ <taglist>
+ <tag><em>main</em></tag>
+ <item>
+ <p>
+ The packages in this section are those in the
+ main Debian distribution. They are all free
+ (according to the Debian free software
+ guidelines) and meet any other criteria for
+ inclusion described in this manual.</p>
+ </item>
+
+ <tag><em>contrib</em></tag>
+ <item>
+ <p>
+ The packages in this section do not meet the
+ criteria for inclusion in the main Debian
+ distribution as defined by this manual, but are
+ otherwise free, as defined by the Debian free
+ software guidelines.</p>
+ </item>
+
+ <tag><em>non-free</em></tag>
+ <item>
+ <p>
+ Packages in <em>non-free</em> do not meet the
+ criteria of free software, as defined by the
+ Debian free software guidelines. Again, use your
+ best judgment in downloading from this
+ Distribution.</p>
+ </item>
+
+ </taglist> You should list <em>all</em> distributions that
+ the package should be installed into. Except in unusual
+ circumstances, installations to <em>stable</em> should also
+ go into <em>frozen</em> (if it exists) and
+ <em>unstable</em>. Likewise, installations into
+ <em>frozen</em> should also go into <em>unstable</em>.
+ </footnote>
+ </p>
+ </sect1>
+
+
+ </sect>
+ </chapt>
+
+ <chapt id="versions"><heading>Version numbering </heading>
+
+ <p>
+ Every package has a version number, in its <tt>Version</tt>
+ control file field.
+ </p>
+
+ <p>
+ The package management system imposes an ordering on version
+ numbers, so that it can tell whether packages are being up- or
+ downgraded and so that package system front end applications
+ can tell whether a package it finds available is newer than
+ the one installed on the system. The version number format
+ has the most significant parts (as far as comparison is
+ concerned) at the beginning.
+ </p>
+
+ <p>
+ The version number format is:
+ &lsqb<var>epoch</var><tt>:</tt>]<var>upstream-version</var>[<tt>-</tt><var>debian-revision</var>]
+ </p>
+
+ <p>
+ The three components here are:
+ <taglist>
+ <tag><var>epoch</var></tag>
+ <item>
+
+ <p>
+ This is a single (generally small) unsigned integer. It
+ may be omitted, in which case zero is assumed. If it is
+ omitted then the <var>upstream-version</var> may not
+ contain any colons.
+ </p>
+
+ <p>
+ It is provided to allow mistakes in the version numbers
+ of older versions of a package, and also a package's
+ previous version numbering schemes, to be left behind.
+ </p>
+
+ </item>
+
+ <tag><var>upstream-version</var></tag>
+ <item>
+
+ <p>
+ This is the main part of the version. It is usually the
+ version number of the original (`upstream') package from
+ which the <tt>.deb</tt> file has been made, if this is
+ applicable. Usually this will be in the same format as
+ that specified by the upstream author(s); however, it
+ may need to be reformatted to fit into the package
+ management system's format and comparison scheme.
+ </p>
+
+ <p>
+ The comparison behavior of the package management system
+ with respect to the <var>upstream-version</var> is
+ described below. The <var>upstream-version</var>
+ portion of the version number is mandatory.
+ </p>
+
+ <p>
+ The <var>upstream-version</var> may contain only
+ alphanumerics and the characters <tt>.</tt> <tt>+</tt>
+ <tt>-</tt> <tt>:</tt> (full stop, plus, hyphen, colon)
+ and should start with a digit. If there is no
+ <var>debian-revision</var> then hyphens are not allowed;
+ if there is no <var>epoch</var> then colons are not
+ allowed.</p>
+ </item>
+
+ <tag><var>debian-revision</var></tag>
+ <item>
+
+ <p>
+ This part of the version represents the version of the
+ modifications that were made to the package to make it a
+ Debian binary package. It is in the same format as the
+ <var>upstream-version</var> and is compared in the same
+ way.
+ </p>
+
+ <p>
+ It is optional; if it isn't present then the
+ <var>upstream-version</var> may not contain a hyphen.
+ This format represents the case where a piece of
+ software was written specifically to be turned into a
+ Debian binary package, and so there is only one
+ `debianization' of it and therefore no revision
+ indication is required.
+ </p>
+
+ <p>
+ It is conventional to restart the
+ <var>debian-revision</var> at <tt>1</tt> each time the
+ <var>upstream-version</var> is increased.
+ </p>
+
+ <p>
+ The package management system will break the
+ <var>upstream-version</var> and
+ <var>debian-revision</var> apart at the last hyphen in
+ the string. The absence of a <var>debian-revision</var>
+ compares earlier than the presence of one (but note that
+ the <var>debian-revision</var> is the least significant
+ part of the version number).
+ </p>
+
+ <p>
+ The <var>debian-revision</var> may contain only
+ alphanumerics and the characters <tt>+</tt> and
+ <tt>.</tt> (plus and full stop).
+ </p>
+ </item>
+ </taglist>
+ The <var>upstream-version</var> and <var>debian-revision</var>
+ parts are compared by the package management system using the
+ same algorithm:
+ </p>
+
+ <p>
+ The strings are compared from left to right.
+ </p>
+
+ <p>
+ First the initial part of each string consisting entirely of
+ non-digit characters is determined. These two parts (one of
+ which may be empty) are compared lexically. If a difference
+ is found it is returned. The lexical comparison is a
+ comparison of ASCII values modified so that all the letters
+ sort earlier than all the non-letters.
+ </p>
+
+ <p>
+ Then the initial part of the remainder of each string which
+ consists entirely of digit characters is determined. The
+ numerical values of these two parts are compared, and any
+ difference found is returned as the result of the comparison.
+ For these purposes an empty string (which can only occur at
+ the end of one or both version strings being compared) counts
+ as zero.
+ </p>
+
+ <p>
+ These two steps are repeated (chopping initial non-digit
+ strings and initial digit strings off from the start) until a
+ difference is found or both strings are exhausted.
+ </p>
+
+ <p>
+ Note that the purpose of epochs is to allow us to leave behind
+ mistakes in version numbering, and to cope with situations
+ where the version numbering changes. It is <em>not</em> there
+ to cope with version numbers containing strings of letters
+ which the package management system cannot interpret (such as
+ <tt>ALPHA</tt> or <tt>pre-</tt>), or with silly orderings (the
+ author of this manual has heard of a package whose versions
+ went <tt>1.1</tt>, <tt>1.2</tt>, <tt>1.3</tt>, <tt>1</tt>,
+ <tt>2.1</tt>, <tt>2.2</tt>, <tt>2</tt> and so forth).
+ </p>
+
+ <p>
+ If an upstream package has problematic version numbers they
+ should be converted to a sane form for use in the
+ <tt>Version</tt> field.
+ </p>
+
+ <sect>
+ <heading>Version numbers based on dates</heading>
+ <p>
+ In general, Debian packages should use the same version
+ numbers as the upstream sources.</p>
+
+ <p>
+ However, in some cases where the upstream version number is
+ based on a date (e.g., a development `snapshot' release) the
+ package management system cannot handle these version
+ numbers without epochs. For example, dpkg will consider
+ `96May01' to be greater than `96Dec24'.</p>
+
+ <p>
+ To prevent having to use epochs for every new upstream
+ version, the version number should be changed to the
+ following format in such cases: `19960501', `19961224'. It
+ is up to the maintainer whether he/she wants to bother the
+ upstream maintainer to change the version numbers upstream,
+ too.</p>
+
+ <p>
+ Note, that other version formats based on dates which are
+ parsed correctly by the package management system should
+ <em>not</em> be changed.</p>
+
+ <p>
+ Native Debian packages (i.e., packages which have been
+ written especially for Debian) whose version numbers include
+ dates should always use the `YYYYMMDD' format.</p>
+ </sect>
+ </chapt>
+
+ <chapt id="miscellaneous"><heading>Packaging Considerations</heading>
+
+ <sect id="timestamps"><heading>Time Stamps</heading>
+ <p>
+ Maintainers are encouraged to preserve the modification
+ times of the upstream source files in a package, as far as
+ is reasonably possible. Even though this is optional, this
+ is still a good idea.
+ <footnote>
+ <p>
+ The rationale is that there is some information conveyed
+ by knowing the age of the file, for example, you could
+ recognize that some documentation is very old by looking
+ at the modification time, so it would be nice if the
+ modification time of the upstream source would be
+ preserved.
+ </p>
+ </footnote>
+ </p>
+ </sect>
+
+ <sect id="debianrules"><heading><tt>debian/rules</tt> - the
+ main building script </heading>
+
+ <p>
+ This file must be an executable makefile, and contains the
+ package-specific recipes for compiling the package and
+ building binary package(s) out of the source.
+ </p>
+
+ <p>
+ It must start with the line <tt>#!/usr/bin/make -f</tt>,
+ so that it can be invoked by saying its name rather than
+ invoking <prgn>make</prgn> explicitly.
+ </p>
+
+ <p>
+ Since an interactive <tt>debian/rules</tt> script makes it
+ impossible to auto-compile that package and also makes it
+ hard for other people to reproduce the same binary
+ package, all <strong>required targets</strong> MUST be
+ non-interactive. At a minimum, required targets are the
+ ones called by <prgn>dpkg-buildpackage</prgn>, namely,
+ <em>clean</em>, <em>binary</em>, <em>binary-arch</em>,
+ <em>binary-indep</em>, and <em>build</em>. It also follows
+ that any target that these targets depend on must also be
+ non-interactive.
+ </p>
+
+ <p>
+ The targets which must be present are:
+ <taglist>
+ <tag><tt>build</tt></tag>
+ <item>
+ <p>
+ This should perform all non-interactive
+ configuration and compilation of the package. If a
+ package has an interactive pre-build configuration
+ routine, the Debianised source package should be
+ built after this has taken place, so that it can be
+ built without rerunning the configuration.
+ </p>
+
+ <p>
+ For some packages, notably ones where the same
+ source tree is compiled in different ways to produce
+ two binary packages, the <prgn>build</prgn> target
+ does not make much sense. For these packages it is
+ good enough to provide two (or more) targets
+ (<tt>build-a</tt> and <tt>build-b</tt> or whatever)
+ for each of the ways of building the package, and a
+ <prgn>build</prgn> target that does nothing. The
+ <prgn>binary</prgn> target will have to build the
+ package in each of the possible ways and make the
+ binary package out of each.
+ </p>
+
+ <p>
+ The <prgn>build</prgn> target must not do anything
+ that might require root privilege.
+ </p>
+
+ <p>
+ The <prgn>build</prgn> target may need to run
+ <prgn>clean</prgn> first - see below.
+ </p>
+
+ <p>
+ When a package has a configuration routine that
+ takes a long time, or when the makefiles are poorly
+ designed, or when <prgn>build</prgn> needs to run
+ <prgn>clean</prgn> first, it is a good idea to
+ <tt>touch build</tt> when the build process is
+ complete. This will ensure that if <tt>debian/rules
+ build</tt> is run again it will not rebuild the
+ whole program.
+ </p>
+ </item>
+
+ <tag><tt>binary</tt>, <tt>binary-arch</tt>,
+ <tt>binary-indep</tt>
+ </tag>
+ <item>
+ <p>
+ The <prgn>binary</prgn> target must be all that is
+ necessary for the user to build the binary
+ package. All these targets are required to be
+ non-interactive. It is split into two parts:
+ <prgn>binary-arch</prgn> builds the packages' output
+ files which are specific to a particular
+ architecture, and <prgn>binary-indep</prgn> builds
+ those which are not.
+ </p>
+
+ <p>
+ <prgn>binary</prgn> may be (and commonly is) a target
+ with no commands which simply depends on
+ <prgn>binary-arch</prgn> and
+ <prgn>binary-indep</prgn>.
+ </p>
+
+ <p>
+ Both <prgn>binary-*</prgn> targets should depend on
+ the <prgn>build</prgn> target, above, so that the
+ package is built if it has not been already. It
+ should then create the relevant binary package(s),
+ using <prgn>dpkg-gencontrol</prgn> to make their
+ control files and <prgn>dpkg-deb</prgn> to build
+ them and place them in the parent of the top level
+ directory.
+ </p>
+
+ <p>
+ If one of the <prgn>binary-*</prgn> targets has
+ nothing to do (this will be always be the case if
+ the source generates only a single binary package,
+ whether architecture-dependent or not) it
+ <em>must</em> still exist, and must always
+ succeed.
+ </p>
+
+ <p>
+ The <prgn>binary</prgn> targets must be invoked as
+ root.
+ </p>
+ </item>
+
+ <tag><tt>clean</tt></tag>
+ <item>
+
+ <p>
+ This must undo any effects that the
+ <prgn>build</prgn> and <prgn>binary</prgn> targets
+ may have had, except that it should leave alone any
+ output files created in the parent directory by a
+ run of <prgn>binary</prgn>. This target must be
+ non-interactive.
+ </p>
+
+ <p>
+ If a <prgn>build</prgn> file is touched at the end
+ of the <prgn>build</prgn> target, as suggested
+ above, it should be removed as the first thing that
+ <prgn>clean</prgn> does, so that running
+ <prgn>build</prgn> again after an interrupted
+ <prgn>clean</prgn> doesn't think that everything is
+ already done.
+ </p>
+
+ <p>
+ The <prgn>clean</prgn> target may need to be
+ invoked as root if <prgn>binary</prgn> has been
+ invoked since the last <prgn>clean</prgn>, or if
+ <prgn>build</prgn> has been invoked as root (since
+ <prgn>build</prgn> may create directories, for
+ example).
+ </p>
+ </item>
+
+ <tag><tt>get-orig-source</tt> (optional)</tag>
+ <item>
+
+ <p>
+ This target fetches the most recent version of the
+ original source package from a canonical archive site
+ (via FTP or WWW, for example), does any necessary
+ rearrangement to turn it into the original source
+ tar file format described below, and leaves it in the
+ current directory.
+ </p>
+
+ <p>
+ This target may be invoked in any directory, and
+ should take care to clean up any temporary files it
+ may have left.
+ </p>
+
+ <p>
+ This target is optional, but providing it if
+ possible is a good idea.
+ </p>
+ </item>
+ </taglist>
+
+ <p>
+ The <prgn>build</prgn>, <prgn>binary</prgn> and
+ <prgn>clean</prgn> targets must be invoked with a current
+ directory of the package's top-level directory.
+ </p>
+
+
+ <p>
+ Additional targets may exist in <tt>debian/rules</tt>,
+ either as published or undocumented interfaces or for the
+ package's internal use.
+ </p>
+
+ <p>
+ The architecture we build on and build for is determined by
+ make variables via dpkg-architecture. You can get the Debian
+ architecture and the GNU style architecture specification
+ string for the build machine as well as the host
+ machine. Here is a list of supported make variables:
+ <list compact="compact">
+ <item>
+ <p><tt>DEB_*_ARCH</tt> (the Debian architecture)</p>
+ </item>
+ <item>
+ <p><tt>DEB_*_GNU_TYPE</tt> (the GNU style architecture
+ specification string)</p>
+ </item>
+ <item>
+ <p><tt>DEB_*_GNU_CPU</tt> (the CPU part of DEB_*_GNU_TYPE)</p>
+ </item>
+ <item>
+ <p><tt>DEB_*_GNU_SYSTEM</tt> (the System part of
+ DEB_*_GNU_TYPE)</p>
+ </list>
+ </p>
+
+ <p>
+ where <tt>*</tt> is either <tt>BUILD</tt> for specification of
+ the build machine or <tt>HOST</tt> for specification of the machine
+ we build for.
+ </p>
+
+ <p>
+ Backward compatibility can be provided in the rules file
+ by setting the needed variables to suitable default
+ values, please refer to the documentation of
+ dpkg-architecture for details.
+ </p>
+
+ <p>
+ It is important to understand that the <tt>DEB_*_ARCH</tt>
+ string only determines which Debian architecture we are
+ building on or for. It should not be used to get the CPU
+ or system information; the GNU style variables should be
+ used for that.
+ </p>
+ </sect>
+
+ <sect id="dpkgchangelog"><heading><tt>debian/changelog</tt>
+ </heading>
+
+ <p>
+ This file records the changes to the Debian-specific parts of the
+ package
+ <footnote>
+ <p>
+ Though there is nothing stopping an author who is also
+ the Debian maintainer from using it for all their
+ changes, it will have to be renamed if the Debian and
+ upstream maintainers become different
+ people.
+ </p>
+ </footnote>.
+ </p>
+
+ <p>
+ It has a special format which allows the package building
+ tools to discover which version of the package is being
+ built and find out other release-specific information.
+ </p>
+
+ <p>
+ That format is a series of entries like this:
+ <example>
+ <var>package</var> (<var>version</var>) <var>distribution(s)</var>; urgency=<var>urgency</var>
+
+ * <var>change details</var>
+ <var>more change details</var>
+ * <var>even more change details</var>
+
+ -- <var>maintainer name and email address</var> <var>date</var>
+ </example>
+ </p>
+
+ <p>
+ <var>package</var> and <var>version</var> are the source
+ package name and version number.
+ </p>
+
+ <p>
+ <var>distribution(s)</var> lists the distributions where
+ this version should be installed when it is uploaded - it
+ is copied to the <tt>Distribution</tt> field in the
+ <tt>.changes</tt> file. See <ref id="f-Distribution">.
+ </p>
+
+ <p>
+ <var>urgency</var> is the value for the <tt>Urgency</tt>
+ field in the <tt>.changes</tt> file for the upload. It is
+ not possible to specify an urgency containing commas; commas
+ are used to separate
+ <tt><var>keyword</var>=<var>value</var></tt> settings in the
+ <prgn>dpkg</prgn> changelog format (though there is
+ currently only one useful <var>keyword</var>,
+ <tt>urgency</tt>).
+ </p>
+
+ <p>
+ The change details may in fact be any series of lines
+ starting with at least two spaces, but conventionally each
+ change starts with an asterisk and a separating space and
+ continuation lines are indented so as to bring them in
+ line with the start of the text above. Blank lines may be
+ used here to separate groups of changes, if desired.
+ </p>
+
+ <p>
+ The maintainer name and email address need <em>not</em>
+ necessarily be those of the usual package maintainer.
+ They should be the details of the person doing
+ <em>this</em> version. The information here will be
+ copied to the <tt>.changes</tt> file, and then later used
+ to send an acknowledgement when the upload has been
+ installed.
+ </p>
+
+ <p>
+ The <var>date</var> should be in RFC822 format
+ <footnote>
+ <p>
+ This is generated by the <prgn>822-date</prgn>
+ program.
+ </p>
+ </footnote>; it should include the time zone specified
+ numerically, with the time zone name or abbreviation
+ optionally present as a comment.
+ </p>
+
+ <p>
+ The first `title' line with the package name should start
+ at the left hand margin; the `trailer' line with the
+ maintainer and date details should be preceded by exactly
+ one space. The maintainer details and the date must be
+ separated by exactly two spaces.
+ </p>
+
+ <sect1><heading>Defining alternative changelog formats</heading>
+
+ <p>
+ It is possible to use a different format to the standard
+ one, by providing a parser for the format you wish to
+ use.
+ </p>
+ <p>
+ A changelog parser must not interact with the user at
+ all.
+ </p>
+ </sect1>
+ </sect>
+
+ <sect id="srcsubstvars"><heading><tt>debian/substvars</tt>
+ and variable substitutions </heading>
+
+ <p>
+ When <prgn>dpkg-gencontrol</prgn>,
+ <prgn>dpkg-genchanges</prgn> and <prgn>dpkg-source</prgn>
+ generate control files they do variable substitutions on
+ their output just before writing it. Variable
+ substitutions have the form
+ <tt>${<var>variable-name</var>}</tt>. The optional file
+ <tt>debian/substvars</tt> contains variable substitutions
+ to be used; variables can also be set directly from
+ <tt>debian/rules</tt> using the <tt>-V</tt> option to the
+ source packaging commands, and certain predefined
+ variables are available.
+ </p>
+
+ <p>
+ The is usually generated and modified dynamically by
+ <tt>debian/rules</tt> targets; in this case it must be
+ removed by the <prgn>clean</prgn> target.
+ </p>
+
+ <p>
+ See <manref name="dpkg-source" section="1"> for full
+ details about source variable substitutions, including the
+ format of <tt>debian/substvars</tt>.</p>
+ </sect>
+
+ <sect id="debianfiles"><heading><tt>debian/files</tt>
+ </heading>
+
+ <p>
+ This file is not a permanent part of the source tree; it
+ is used while building packages to record which files are
+ being generated. <prgn>dpkg-genchanges</prgn> uses it
+ when it generates a <tt>.changes</tt> file.
+ </p>
+
+ <p>
+ It should not exist in a shipped source package, and so it
+ (and any backup files or temporary files such as
+ <tt>files.new</tt>
+ <footnote>
+ <p>
+ <tt>files.new</tt> is used as a temporary file by
+ <prgn>dpkg-gencontrol</prgn> and
+ <prgn>dpkg-distaddfile</prgn> - they write a new
+ version of <tt>files</tt> here before renaming it,
+ to avoid leaving a corrupted copy if an error
+ occurs
+ </p>
+ </footnote>) should be removed by the
+ <prgn>clean</prgn> target. It may also be wise to
+ ensure a fresh start by emptying or removing it at the
+ start of the <prgn>binary</prgn> target.
+ </p>
+
+ <p>
+ <prgn>dpkg-gencontrol</prgn> adds an entry to this file
+ for the <tt>.deb</tt> file that will be created by
+ <prgn>dpkg-deb</prgn> from the control file that it
+ generates, so for most packages all that needs to be done
+ with this file is to delete it in <prgn>clean</prgn>.
+ </p>
+
+ <p>
+ If a package upload includes files besides the source
+ package and any binary packages whose control files were
+ made with <prgn>dpkg-gencontrol</prgn> then they should be
+ placed in the parent of the package's top-level directory
+ and <prgn>dpkg-distaddfile</prgn> should be called to add
+ the file to the list in <tt>debian/files</tt>.</p>
+ </sect>
+
+ <sect id="restrictions"><heading>Restrictions on objects in source packages
+ </heading>
+
+ <p>
+ The source package may not contain any hard links
+ <footnote>
+ <p>
+ This is not currently detected when building source
+ packages, but only when extracting
+ them.
+ </p>
+ </footnote>
+ <footnote>
+ <p>
+ Hard links may be permitted at some point in the
+ future, but would require a fair amount of
+ work.
+ </p>
+ </footnote>, device special files, sockets or setuid or
+ setgid files.
+ <footnote>
+ <p>
+ Setgid directories are allowed.
+ </p>
+ </footnote>
+ </p>
+ </sect>
+ <sect id="descriptions"><heading>Descriptions of packages - the
+ <tt>Description</tt> field </heading>
+
+ <p>
+ The description is intended to describe the program to a user
+ who has never met it before so that they know whether they
+ want to install it. It should also give information about the
+ significant dependencies and conflicts between this package
+ and others, so that the user knows why these dependencies and
+ conflicts have been declared.
+ </p>
+
+ <sect1><heading>Notes about writing descriptions
+ </heading>
+
+ <p>
+ The single line synopsis should be kept brief - certainly
+ under 80 characters.
+ </p>
+
+ <p>
+ Do not include the package name in the synopsis line. The
+ display software knows how to display this already, and you
+ do not need to state it. Remember that in many situations
+ the user may only see the synopsis line - make it as
+ informative as you can.
+ </p>
+
+ <p>
+ Do not try to continue the single line synopsis into the
+ extended description. This will not work correctly when
+ the full description is displayed, and makes no sense
+ where only the summary (the single line synopsis) is
+ available.
+ </p>
+
+ <p>
+ The extended description should describe what the package
+ does and how it relates to the rest of the system (in terms
+ of, for example, which subsystem it is which part of).
+ </p>
+
+ <p>
+ The description field needs to make sense to anyone, even
+ people who have no idea about any of the things the
+ package deals with.
+ <footnote>
+ <p>
+ The blurb that comes with a program in its
+ announcements and/or <prgn>README</prgn> files is
+ rarely suitable for use in a description. It is
+ usually aimed at people who are already in the
+ community where the package is used.
+ </p>
+ </footnote>
+ </p>
+
+ <p>
+ Put important information first, both in the synopsis and
+ extended description. Sometimes only the first part of the
+ synopsis or of the description will be displayed. You can
+ assume that there will usually be a way to see the whole
+ extended description.
+ </p>
+
+ <p>
+ You may include information about dependencies and so forth
+ in the extended description, if you wish.
+ </p>
+
+ <p>
+ Do not use tab characters. Their effect is not predictable.
+ </p>
+
+ </sect1>
+ </sect>
+ </chapt>
+
+
+ <chapt id="maintainerscripts"><heading>Package maintainer scripts
+ and installation procedure
+ </heading>
+
+ <sect><heading>Introduction to package maintainer scripts
+ </heading>
+
+ <p>
+ It is possible to supply scripts as part of a package which
+ the package management system will run for you when your
+ package is installed, upgraded or removed.
+ </p>
+
+ <p>
+ These scripts should be the files <tt>preinst</tt>,
+ <tt>postinst</tt>, <tt>prerm</tt> and <tt>postrm</tt> in the
+ control area of the package. They must be proper executable
+ files; if they are scripts (which is recommended) they must
+ start with the usual <tt>#!</tt> convention. They should be
+ readable and executable by anyone, and not world-writable.
+ </p>
+
+ <p>
+ The package management system looks at the exit status from
+ these scripts. It is important that they exit with a
+ non-zero status if there is an error, so that the package
+ management system can stop its processing. For shell
+ scripts this means that you <em>almost always</em> need to
+ use <tt>set -e</tt> (this is usually true when writing shell
+ scripts, in fact). It is also important, of course, that
+ they don't exit with a non-zero status if everything went
+ well.
+ </p>
+
+ <p>
+ It is necessary for the error recovery procedures that the
+ scripts be idempotent: i.e., invoking the same script several
+ times in the same situation should do no harm. If the first
+ call failed, or aborted half way through for some reason,
+ the second call should merely do the things that were left
+ undone the first time, if any, and exit with a success
+ status.
+ </p>
+
+ <p>
+ When a package is upgraded a combination of the scripts from
+ the old and new packages is called in amongst the other
+ steps of the upgrade procedure. If your scripts are going
+ to be at all complicated you need to be aware of this, and
+ may need to check the arguments to your scripts.
+ </p>
+
+ <p>
+ Broadly speaking the <prgn>preinst</prgn> is called before
+ (a particular version of) a package is installed, and the
+ <prgn>postinst</prgn> afterwards; the <prgn>prerm</prgn>
+ before (a version of) a package is removed and the
+ <prgn>postrm</prgn> afterwards.
+ </p>
+
+ <p> Programs called from maintainer scripts should not
+ normally have a path prepended to them. Before installation
+ is started the package management system checks to see if
+ the programs <prgn>ldconfig</prgn>,
+ <prgn>start-stop-daemon</prgn>, <prgn>install-info</prgn>,
+ and <prgn>update-rc.d</prgn> can be found via the
+ <tt>PATH</tt> environment variable. Those programs, and any
+ other program that one would expect to on the <tt>PATH</tt>,
+ should thus be invoked without an absolute
+ pathname. Maintainer scripts should also not reset the
+ <tt>PATH</tt>, though they might choose to modify it by pre-
+ or appending package-specific directories. These
+ considerations really apply to all shell scripts.</p>
+ </sect>
+ <sect>
+ <heading>Maintainer scripts Idempotency</heading>
+
+ <p>
+ It is very important to make maintainer scripts
+ idempotent.
+ <footnote>
+ <p>
+ That means that if it runs successfully or fails
+ and then you call it again it doesn't bomb out,
+ but just ensures that everything is the way it
+ ought to be.
+ </p>
+ </footnote> This is so that if an error occurs, the
+ user interrupts <prgn>dpkg</prgn> or some other
+ unforeseen circumstance happens you don't leave the
+ user with a badly-broken package.
+ </p>
+ </sect>
+ <sect>
+ <heading>Controlling terminal for maintainer scripts</heading>
+
+ <p>
+ The maintainer scripts are guaranteed to run with a
+ controlling terminal and can interact with the user.
+ If they need to prompt for passwords, do full-screen
+ interaction or something similar you should do these
+ things to and from <tt>/dev/tty</tt>, since
+ <prgn>dpkg</prgn> will at some point redirect scripts'
+ standard input and output so that it can log the
+ installation process. Likewise, because these scripts
+ may be executed with standard output redirected into a
+ pipe for logging purposes, Perl scripts should set
+ unbuffered output by setting <tt>$|=1</tt> so that the
+ output is printed immediately rather than being
+ buffered.
+ </p>
+
+ <p>
+ Each script should return a zero exit status for
+ success, or a nonzero one for failure.
+ </p>
+ </sect>
+
+ <sect id="mscriptsinstact"><heading>Summary of ways maintainer
+ scripts are called
+ </heading>
+
+ <p>
+ <list compact="compact">
+ <item>
+ <p><var>new-preinst</var> <tt>install</tt></p>
+ </item>
+ <item>
+ <p><var>new-preinst</var> <tt>install</tt>
+ <var>old-version</var></p>
+ </item>
+ <item>
+ <p><var>new-preinst</var> <tt>upgrade</tt>
+ <var>old-version</var></p>
+ </item>
+ <item>
+ <p><var>old-preinst</var> <tt>abort-upgrade</tt>
+ <var>new-version</var>
+ </p>
+ </item>
+ </list>
+
+ <p>
+ <list compact="compact">
+ <item>
+ <p><var>postinst</var> <tt>configure</tt>
+ <var>most-recently-configured-version</var></p>
+ </item>
+ <item>
+ <p><var>old-postinst</var> <tt>abort-upgrade</tt>
+ <var>new version</var></p>
+ </item>
+ <item>
+ <p><var>conflictor's-postinst</var> <tt>abort-remove</tt>
+ <tt>in-favour</tt> <var>package</var>
+ <var>new-version</var></p>
+ </item>
+ <item>
+ <p>
+ <var>deconfigured's-postinst</var>
+ <tt>abort-deconfigure</tt> <tt>in-favour</tt>
+ <var>failed-install-package</var> <var>version</var>
+ <tt>removing</tt> <var>conflicting-package</var>
+ <var>version</var>
+ </p>
+ </item>
+ </list>
+
+ <p>
+ <list compact="compact">
+ <item>
+ <p><var>prerm</var> <tt>remove</tt></p>
+ </item>
+ <item>
+ <p><var>old-prerm</var> <tt>upgrade</tt>
+ <var>new-version</var></p>
+ </item>
+ <item>
+ <p><var>new-prerm</var> <tt>failed-upgrade</tt>
+ <var>old-version</var></p>
+ </item>
+ <item>
+ <p><var>conflictor's-prerm</var> <tt>remove</tt>
+ <tt>in-favour</tt> <var>package</var>
+ <var>new-version</var></p>
+ </item>
+ <item>
+ <p>
+ <var>deconfigured's-prerm</var> <tt>deconfigure</tt>
+ <tt>in-favour</tt> <var>package-being-installed</var>
+ <var>version</var> <tt>removing</tt>
+ <var>conflicting-package</var>
+ <var>version</var>
+ </p>
+ </item>
+ </list>
+
+ <p>
+ <list compact="compact">
+ <item>
+ <p><var>postrm</var> <tt>remove</tt></p>
+ </item>
+ <item>
+ <p><var>postrm</var> <tt>purge</tt></p>
+ </item>
+ <item>
+ <p>
+ <var>old-postrm</var> <tt>upgrade</tt>
+ <var>new-version</var></p>
+ </item>
+ <item>
+ <p><var>new-postrm</var> <tt>failed-upgrade</tt>
+ <var>old-version</var></p>
+ </item>
+ <item>
+ <p><var>new-postrm</var> <tt>abort-install</tt></p>
+ </item>
+ <item>
+ <p><var>new-postrm</var> <tt>abort-install</tt>
+ <var>old-version</var></p>
+ </item>
+ <item>
+ <p><var>new-postrm</var> <tt>abort-upgrade</tt>
+ <var>old-version</var></p>
+ </item>
+ <item>
+ <p>
+ <var>disappearer's-postrm</var> <tt>disappear</tt>
+ <var>overwriter</var>
+ <var>overwriter-version</var></p></item>
+ </list>
+ </p>
+
+
+ <sect id="unpackphase"><heading>Details of unpack phase of
+ installation or upgrade
+ </heading>
+
+ <p>
+ The procedure on installation/upgrade/overwrite/disappear
+ (i.e., when running <tt>dpkg --unpack</tt>, or the unpack
+ stage of <tt>dpkg --install</tt>) is as follows. In each
+ case if an error occurs the actions are, in general, run
+ backwards - this means that the maintainer scripts are run
+ with different arguments in reverse order. These are the
+ `error unwind' calls listed below.
+
+ <enumlist>
+ <item>
+ <p>
+ <enumlist>
+ <item>
+ <p>If a version of the package is already
+ installed, call
+ <example>
+ <var>old-prerm</var> upgrade <var>new-version</var>
+ </example></p>
+ </item>
+ <item>
+ <p>
+ If the script runs but exits with a non-zero
+ exit status, <prgn>dpkg</prgn> will attempt:
+ <example>
+ <var>new-prerm</var> failed-upgrade <var>old-version</var>
+ </example>
+ Error unwind, for both the above cases:
+ <example>
+ <var>old-postinst</var> abort-upgrade <var>new-version</var>
+ </example>
+ </p>
+ </item>
+ </enumlist>
+ </p>
+ </item>
+ <item>
+ <p>If a `conflicting' package is being removed at the same time:
+ <enumlist>
+ <item>
+ <p>
+ If any packages depended on that conflicting
+ package and <tt>--auto-deconfigure</tt> is
+ specified, call, for each such package:
+ <example>
+ <var>deconfigured's-prerm</var> deconfigure \
+ in-favour <var>package-being-installed</var> <var>version</var> \
+ removing <var>conflicting-package</var> <var>version</var>
+ </example>
+ Error unwind:
+ <example>
+ <var>deconfigured's-postinst</var> abort-deconfigure \
+ in-favour <var>package-being-installed-but-failed</var> <var>version</var> \
+ removing <var>conflicting-package</var> <var>version</var>
+ </example>
+ The deconfigured packages are marked as
+ requiring configuration, so that if
+ <tt>--install</tt> is used they will be
+ configured again if possible.</p>
+ </item>
+ <item>
+ <p>To prepare for removal of the conflicting package, call:
+ <example>
+ <var>conflictor's-prerm</var> remove in-favour <var>package</var> <var>new-version</var>
+ </example>
+ Error unwind:
+ <example>
+ <var>conflictor's-postinst</var> abort-remove \
+ in-favour <var>package</var> <var>new-version</var>
+ </example>
+ </p>
+ </item>
+ </enumlist>
+ </p>
+ </item>
+ <item>
+ <p>
+ <enumlist>
+ <item>
+ <p>If the package is being upgraded, call:
+ <example>
+ <var>new-preinst</var> upgrade <var>old-version</var>
+ </example></p>
+ </item>
+ <item>
+ <p>
+ Otherwise, if the package had some configuration
+ files from a previous version installed (i.e., it
+ is in the `configuration files only' state):
+ <example>
+ <var>new-preinst</var> install <var>old-version</var>
+ </example></p>
+
+ <item>
+ <p>Otherwise (i.e., the package was completely purged):
+ <example>
+ <var>new-preinst</var> install
+ </example>
+ Error unwind versions, respectively:
+ <example>
+ <var>new-postrm</var> abort-upgrade <var>old-version</var>
+ <var>new-postrm</var> abort-install <var>old-version</var>
+ <var>new-postrm</var> abort-install
+ </example>
+ </p>
+ </item>
+ </enumlist>
+ </p>
+ </item>
+ <item>
+
+ <p>
+ The new package's files are unpacked, overwriting any
+ that may be on the system already, for example any
+ from the old version of the same package or from
+ another package (backups of the old files are left
+ around, and if anything goes wrong the package
+ management system will attempt to put them back as
+ part of the error unwind).
+ </p>
+
+ <p>
+ It is an error for a package to contains files which
+ are on the system in another package, unless
+ <tt>Replaces</tt> is used (see <ref id="replaces">).
+ Currently the <tt>--force-overwrite</tt> flag is
+ enabled, downgrading it to a warning, but this may not
+ always be the case.
+ </p>
+
+ <p>
+ It is a more serious error for a package to contain a
+ plain file or other kind of non-directory where another
+ package has a directory (again, unless
+ <tt>Replaces</tt> is used). This error can be
+ overridden if desired using
+ <tt>--force-overwrite-dir</tt>, but this is not
+ advisable.
+ </p>
+
+ <p>
+ Packages which overwrite each other's files produce
+ behavior which though deterministic is hard for the
+ system administrator to understand. It can easily
+ lead to `missing' programs if, for example, a package
+ is installed which overwrites a file from another
+ package, and is then removed again.
+ <footnote>
+ <p>
+ Part of the problem is due to what is arguably a
+ bug in <prgn>dpkg</prgn>.
+ </p>
+ </footnote>
+ </p>
+
+ <p>
+ A directory will never be replaced by a symbolic links
+ to a directory or vice versa; instead, the existing
+ state (symlink or not) will be left alone and
+ <prgn>dpkg</prgn> will follow the symlink if there is
+ one.</p>
+ </item>
+
+ <item>
+
+ <p><enumlist>
+ <item>
+ <p>If the package is being upgraded, call
+ <example>
+ <var>old-postrm</var> upgrade <var>new-version</var>
+ </example></p>
+ </item>
+ <item>
+ <p>If this fails, <prgn>dpkg</prgn> will attempt:
+ <example>
+ <var>new-postrm</var> failed-upgrade <var>old-version</var>
+ </example>
+ Error unwind, for both cases:
+ <example>
+ <var>old-preinst</var> abort-upgrade <var>new-version</var>
+ </example>
+ </p>
+ </item>
+ </enumlist>
+ <p>
+ This is the point of no return - if
+ <prgn>dpkg</prgn> gets this far, it won't back off
+ past this point if an error occurs. This will
+ leave the package in a fairly bad state, which
+ will require a successful re-installation to clear
+ up, but it's when <prgn>dpkg</prgn> starts doing
+ things that are irreversible.
+ </p>
+ </item>
+ <item>
+ <p>
+ Any files which were in the old version of the package
+ but not in the new are removed.</p>
+ </item>
+ <item>
+ <p>The new file list replaces the old.</p>
+ </item>
+ <item>
+ <p>The new maintainer scripts replace the old.</p>
+ </item>
+
+ <item>
+ <p>Any packages all of whose files have been overwritten during the
+ installation, and which aren't required for
+ dependencies, are considered to have been removed.
+ For each such package,
+ <enumlist>
+ <item>
+ <p><prgn>dpkg</prgn> calls:
+ <example>
+ <var>disappearer's-postrm</var> disappear \
+ <var>overwriter</var> <var>overwriter-version</var>
+ </example>
+ </p>
+ </item>
+ <item>
+ <p>The package's maintainer scripts are removed.
+ </p>
+ </item>
+ <item>
+ <p>
+ It is noted in the status database as being in a
+ sane state, namely not installed (any conffiles
+ it may have are ignored, rather than being
+ removed by <prgn>dpkg</prgn>). Note that
+ disappearing packages do not have their prerm
+ called, because <prgn>dpkg</prgn> doesn't know
+ in advance that the package is going to
+ vanish.
+ </p>
+ </item>
+ </enumlist>
+ </p>
+ </item>
+ <item>
+ <p>
+ Any files in the package we're unpacking that are also
+ listed in the file lists of other packages are removed
+ from those lists. (This will lobotomize the file list
+ of the `conflicting' package if there is one.)
+ </p>
+ </item>
+ <item>
+ <p>
+ The backup files made during installation, above, are
+ deleted.
+ </p>
+ </item>
+
+ <item>
+ <p>
+ The new package's status is now sane, and recorded as
+ `unpacked'. Here is another point of no return - if
+ the conflicting package's removal fails we do not
+ unwind the rest of the installation; the conflicting
+ package is left in a half-removed limbo.
+ </p>
+ </item>
+ <item>
+ <p>
+ If there was a conflicting package we go and do the
+ removal actions (described below), starting with the
+ removal of the conflicting package's files (any that
+ are also in the package being installed have already
+ been removed from the conflicting package's file list,
+ and so do not get removed now).
+ </p>
+ </item>
+ </enumlist>
+ </p>
+ </sect>
+
+ <sect><heading>Details of configuration</heading>
+
+ <p>
+ When we configure a package (this happens with <tt>dpkg
+ --install</tt>, or with <tt>--configure</tt>), we first
+ update the conffiles and then call:
+ <example>
+ <var>postinst</var> configure <var>most-recently-configured-version</var>
+ </example>
+ </p>
+
+ <p>
+ No attempt is made to unwind after errors during
+ configuration.
+ </p>
+
+ <p>
+ If there is no most recently configured version
+ <prgn>dpkg</prgn> will pass a null argument; older versions
+ of dpkg may pass <tt><unknown></tt> (including the
+ angle brackets) in this case. Even older ones do not pass a
+ second argument at all, under any circumstances.
+ </p>
+ </sect>
+
+ <sect><heading>Details of removal and/or configuration purging
+ </heading>
+
+ <p>
+ <enumlist>
+ <item>
+ <p>
+ <example>
+ <var>prerm</var> remove
+ </example>
+ </p>
+ </item>
+ <item>
+ <p>
+ The package's files are removed (except conffiles).
+ </p>
+ </item>
+ <item>
+ <p><example>
+ <var>postrm</var> remove
+ </example></p>
+ </item>
+ <item>
+ <p>All the maintainer scripts except the postrm are removed.
+ </p>
+
+ <p>
+ If we aren't purging the package we stop here. Note
+ that packages which have no postrm and no conffiles
+ are automatically purged when removed, as there is no
+ difference except for the <prgn>dpkg</prgn>
+ status.</p>
+ </item>
+ <item>
+ <p>
+ The conffiles and any backup files (<tt>~</tt>-files,
+ <tt>#*#</tt> files, <tt>%</tt>-files,
+ <tt>.dpkg-{old,new,tmp}</tt>, etc.) are removed.</p>
+ </item>
+ <item>
+ <p><example>
+ <var>postrm</var> purge
+ </example></p>
+ </item>
+ <item>
+ <p>The package's file list is removed.</p>
+ </item>
+ </enumlist>
+ No attempt is made to unwind after errors during
+ removal.</p>
+ </sect>
+ </chapt>
+
+
+ <chapt id="relationships"><heading>Declaring relationships between
+ packages </heading>
+
+ <p>
+ Packages can declare in their control file that they have
+ certain relationships to other packages - for example, that
+ they may not be installed at the same time as certain other
+ packages, and/or that they depend on the presence of others,
+ or that they should overwrite files in certain other packages
+ if present.
+ </p>
+
+ <p>
+ This is done using the <tt>Depends</tt>, <tt>Recommends</tt>,
+ <tt>Suggests</tt>, <tt>Enhances</tt>, <tt>Conflicts</tt>,
+ <tt>Provides</tt> and <tt>Replaces</tt> control file fields.
+ </p>
+
+ <p>
+ Source packages may declare relationships to binary packages,
+ saying that they require certain binary packages to be
+ installed or absent at the time of building the package.
+ </p>
+
+ <p>
+ This is done using the <tt>Build-Depends</tt>,
+ <tt>Build-Depends-Indep</tt>, <tt>Build-Conflicts</tt>, and
+ <tt>Build-Conflicts-Indep</tt> control file fields.
+ </p>
+
+ <sect id="depsyntax"><heading>Syntax of relationship fields
+ </heading>
+
+ <p>
+ These fields all have a uniform syntax. They are a list of
+ package names separated by commas.
+ </p>
+
+ <p>
+ In the <tt>Depends</tt>, <tt>Recommends</tt>,
+ <tt>Suggests</tt>, <tt>Pre-Depends</tt>,
+ <tt>Build-Depends</tt> and <tt>Build-Depends-Indep</tt>
+ control file fields of the package, which declare
+ dependencies on other packages, the package names listed may
+ also include lists of alternative package names, separated
+ by vertical bar symbols <tt>|</tt> (pipe symbols). In such
+ a case, the presence of any one of the alternative packages
+ is installed, that part of the dependency is considered to
+ be satisfied.
+ </p>
+
+ <p>
+ All the fields except <tt>Provides</tt> may restrict their
+ applicability to particular versions of each named package.
+ This is done in parentheses after each individual package
+ name; the parentheses should contain a relation from the
+ list below followed by a version number, in the format
+ described in <ref id="versions">.
+ </p>
+
+ <p>
+ The relations allowed are <tt><<</tt>, <tt><=</tt>,
+ <tt>=</tt>, <tt>>=</tt> and <tt>>></tt> for
+ strictly earlier, earlier or equal, exactly equal, later or
+ equal and strictly later, respectively. The forms
+ <tt><</tt> and <tt>></tt> were used to mean
+ earlier/later or equal, rather than strictly earlier/later,
+ so they should not appear in new packages (though
+ <prgn>dpkg</prgn> still supports them).
+ </p>
+
+ <p>
+ Whitespace may appear at any point in the version
+ specification, and must appear where it's necessary to
+ disambiguate; it is not otherwise significant. For
+ consistency and in case of future changes to
+ <prgn>dpkg</prgn> it is recommended that a single space be
+ used after a version relationship and before a version
+ number; it is usual also to put a single space after each
+ comma, on either side of each vertical bar, and before each
+ open parenthesis.
+ </p>
+
+ <p>
+ For example:
+ <example>
+ Package: metamail
+ Version: 2.7-3
+ Depends: libc5 (>= 5.2.18-4), mime-support, csh | tcsh
+ </example>
+ </p>
+
+ <p>
+ All fields that specify build-time relationships
+ (<tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
+ <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>)
+ may be restricted to a certain set of architectures. This
+ is done in brackets after each individual package name and
+ the optional version specification. The brackets enclose a
+ list of Debian architecture names separated by whitespace.
+ An exclamation mark may be prepended to each name. If the
+ current Debian host architecture is not in this list and
+ there are no exclamation marks in the list, or it is in the
+ list with a prepended exclamation mark, the package name and
+ the associated version specification are ignored completely
+ for the purposes of defining the relationships.
+ </p>
+
+ <p>
+ For example:
+ <example>
+ Source: glibc
+ Build-Depends-Indep: texinfo
+ Build-Depends: kernel-headers-2.2.10 [!hurd-i386],
+ hurd-dev [hurd-i386], gnumach-dev [hurd-i386]
+ </example>
+ </p>
+ </sect>
+
+ <sect>
+ <heading>Binary Dependencies - <tt>Depends</tt>,
+ <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
+ <tt>Pre-Depends</tt>
+ </heading>
+
+ <p>
+ These five fields are used to declare a dependency
+ relationship by one package on another. They appear in the
+ depending package's control file.
+ </p>
+
+ <p>
+ All but <tt>Pre-Depends</tt> and <tt>Conflicts</tt>
+ (discussed below) take effect <em>only</em> when a package
+ is to be configured. They do not prevent a package being on
+ the system in an unconfigured state while its dependencies
+ are unsatisfied, and it is possible to replace a package
+ whose dependencies are satisfied and which is properly
+ installed with a different version whose dependencies are
+ not and cannot be satisfied; when this is done the depending
+ package will be left unconfigured (since attempts to
+ configure it will give errors) and will not function
+ properly.
+ </p>
+
+ <p>
+ For this reason packages in an installation run are usually
+ all unpacked first and all configured later; this gives
+ later versions of packages with dependencies on later
+ versions of other packages the opportunity to have their
+ dependencies satisfied.
+ </p>
+
+ <p>
+ Thus <tt>Depends</tt> allows package maintainers to impose
+ an order in which packages should be configured.
+ <taglist>
+ <tag><tt>Depends</tt></tag>
+ <item>
+
+ <p>This declares an absolute dependency.
+ </p>
+
+ <p>
+ The <tt>Depends</tt> field should be used if the
+ depended-on package is required for the depending
+ package to provide a significant amount of
+ functionality.</p>
+ </item>
+
+ <tag><tt>Recommends</tt></tag>
+ <item>
+ <p>This declares a strong, but not absolute, dependency.
+ </p>
+
+ <p>
+ The <tt>Recommends</tt> field should list packages
+ that would be found together with this one in all but
+ unusual installations.</p>
+ </item>
+
+ <tag><tt>Suggests</tt></tag>
+ <item>
+
+ <p>
+ This is used to declare that one package may be more
+ useful with one or more others. Using this field
+ tells the packaging system and the user that the
+ listed packages are related to this one and can
+ perhaps enhance its usefulness, but that installing
+ this one without them is perfectly reasonable.
+ </p>
+ </item>
+
+ <tag><tt>Enhances</tt></tag>
+ <item>
+ <p>
+ This field is similar to Suggests but works in the
+ opposite direction. It is used to declare that a
+ package can enhance the functionality of another
+ package.
+ </p>
+ </item>
+
+ <tag><tt>Pre-Depends</tt></tag>
+ <item>
+
+ <p>
+ This field is like <tt>Depends</tt>, except that it
+ also forces <prgn>dpkg</prgn> to complete installation
+ of the packages named before even starting the
+ installation of the package which declares the
+ Pre-dependency.
+ </p>
+
+ <p>
+ <tt>Pre-Depends</tt> should be used sparingly,
+ preferably only by packages whose premature upgrade or
+ installation would hamper the ability of the system to
+ continue with any upgrade that might be in progress.
+ </p>
+
+ <p>
+ When the package declaring it is being configured, a
+ <tt>Pre-Dependency</tt> will be considered satisfied
+ only if the depending package has been correctly
+ configured, just as if an ordinary <tt>Depends</tt>
+ had been used.
+ </p>
+
+ <p>
+ However, when a package declaring a Pre-dependency is
+ being unpacked the predependency can be satisfied even
+ if the depended-on package(s) are only unpacked or
+ half-configured, provided that they have been
+ configured correctly at some point in the past (and
+ not removed or partially removed since). In this case
+ both the previously-configured and currently unpacked
+ or half-configured versions must satisfy any version
+ clause in the <tt>Pre-Depends</tt> field.
+ </p>
+ </item>
+ </taglist>
+ </p>
+ <p>
+ When selecting which level of dependency to use you should
+ consider how important the depended-on package is to the
+ functionality of the one declaring the dependency. Some
+ packages are composed of components of varying degrees of
+ importance. Such a package should list using
+ <tt>Depends</tt> the package(s) which are required by the
+ more important components. The other components'
+ requirements may be mentioned as Suggestions or
+ Recommendations, as appropriate to the components' relative
+ importance.
+ </p>
+
+
+ <sect id="conflicts"><heading>Alternative binary packages -
+ <tt>Conflicts</tt> and <tt>Replaces</tt>
+ </heading>
+
+ <p>
+ When one binary package declares a conflict with another
+ <prgn>dpkg</prgn> will refuse to allow them to be installed
+ on the system at the same time.
+ </p>
+
+ <p>
+ If one package is to be installed, the other must be removed
+ first - if the package being installed is marked as
+ replacing (<ref id="replaces">) the one on the system, or
+ the one on the system is marked as deselected, or both
+ packages are marked <tt>Essential</tt>, then
+ <prgn>dpkg</prgn> will automatically remove the package
+ which is causing the conflict, otherwise it will halt the
+ installation of the new package with an error. This
+ mechanism specifically doesn't work when the installed
+ package is <tt>Essential</tt>, but the new package is not.
+ </p>
+
+
+ <p>
+ A package will not cause a conflict merely because its
+ configuration files are still installed; it must be at least
+ half-installed.
+ </p>
+
+ <p>
+ A special exception is made for packages which declare a
+ conflict with their own package name, or with a virtual
+ package which they provide (see below): this does not
+ prevent their installation, and allows a package to conflict
+ with others providing a replacement for it. You use this
+ feature when you want the package in question to be the only
+ package providing something.
+ </p>
+
+ <p>
+ A <tt>Conflicts</tt> entry should almost never have an
+ `earlier than' version clause. This would prevent
+ <prgn>dpkg</prgn> from upgrading or installing the package
+ which declared such a conflict until the upgrade or removal
+ of the conflicted-with package had been completed.
+ </p>
+ </sect>
+
+ <sect id="virtual"><heading>Virtual packages - <tt>Provides</tt>
+ </heading>
+
+ <p>
+ As well as the names of actual (`concrete') packages, the
+ package relationship fields <tt>Depends</tt>,
+ <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
+ <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Conflicts</tt>,
+ <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt> may
+ mention virtual packages.
+ </p>
+
+ <p>
+ A virtual package is one which appears in the
+ <tt>Provides</tt> control file field of another package.
+ The effect is as if the package(s) which provide a
+ particular virtual package name had been listed by name
+ everywhere the virtual package name appears.
+ </p>
+
+ <p>
+ If there are both a real and a virtual package of the same
+ name then the dependency may be satisfied (or the conflict
+ caused) by either the real package or any of the virtual
+ packages which provide it. This is so that, for example,
+ supposing we have
+ <example>
+ Package: vm
+ Depends: emacs
+ </example>
+ and someone else releases an xemacs package they can say
+ <example>
+ Package: xemacs
+ Provides: emacs
+ </example> and all will work in the interim (until a purely
+ virtual package name is decided on and the <tt>emacs</tt>
+ and <tt>vm</tt> packages are changed to use it).
+ </p>
+
+ <p>
+ If a dependency or a conflict has a version number attached
+ then only real packages will be considered to see whether
+ the relationship is satisfied (or the prohibition violated,
+ for a conflict) - it is assumed that a real package which
+ provides the virtual package is not of the `right' version.
+ So, a <tt>Provides</tt> field may not contain version
+ numbers, and the version number of the concrete package
+ which provides a particular virtual package will not be
+ looked at when considering a dependency on or conflict with
+ the virtual package name.
+ </p>
+
+ <p>
+ It is likely that the ability will be added in a future
+ release of <prgn>dpkg</prgn> to specify a version number for
+ each virtual package it provides. This feature is not yet
+ present, however, and is expected to be used only
+ infrequently.
+ </p>
+
+ <p>
+ If you want to specify which of a set of real packages should be the
+ default to satisfy a particular dependency on a virtual package, you
+ should list the real package as an alternative before the virtual.
+ </p>
+ </sect>
+
+
+ <sect id="replaces"><heading><tt>Replaces</tt> - overwriting
+ files and replacing packages
+ </heading>
+
+ <p>
+ The <tt>Replaces</tt> control file field has two purposes,
+ which come into play in different situations.
+ </p>
+
+ <p>
+ Virtual packages (<ref id="virtual">) are not considered
+ when looking at a <tt>Replaces</tt> field - the packages
+ declared as being replaced must be mentioned by their real
+ names.
+ </p>
+
+ <sect1><heading>Overwriting files in other packages
+ </heading>
+
+ <p>
+ Firstly, as mentioned before, it is usually an error for a
+ package to contain files which are on the system in
+ another package, though currently the
+ <tt>--force-overwrite</tt> flag is enabled by default,
+ downgrading the error to a warning,
+ </p>
+
+ <p>
+ If the overwriting package declares that it replaces the
+ one containing the file being overwritten then
+ <prgn>dpkg</prgn> will proceed, and replace the file from
+ the old package with that from the new. The file will no
+ longer be listed as `owned' by the old package.
+ </p>
+
+ <p>
+ If a package is completely replaced in this way, so that
+ <prgn>dpkg</prgn> does not know of any files it still
+ contains, it is considered to have disappeared. It will
+ be marked as not wanted on the system (selected for
+ removal) and not installed. Any conffiles details noted
+ in the package will be ignored, as they will have been
+ taken over by the replacing package(s). The package's
+ <prgn>postrm</prgn> script will be run to allow the
+ package to do any final cleanup required. See <ref
+ id="mscriptsinstact">.
+ </p>
+
+ <p>
+ In the future <prgn>dpkg</prgn> will discard files which
+ would overwrite those from an already installed package
+ which declares that it replaces the package being
+ installed. This is so that you can install an older
+ version of a package without problems.
+ </p>
+
+ <p>
+ This usage of <tt>Replaces</tt> only takes effect when
+ both packages are at least partially on the system at
+ once, so that it can only happen if they do not conflict
+ or if the conflict has been overridden.</p>
+ </sect1>
+
+ <sect1><heading>Replacing whole packages, forcing their
+ removal
+ </heading>
+
+ <p>
+ Secondly, <tt>Replaces</tt> allows the packaging system to
+ resolve which package should be removed when there is a
+ conflict - see <ref id="conflicts">. This usage only
+ takes effect when the two packages <em>do</em> conflict,
+ so that the two effects do not interfere with each other.
+ </p>
+ </sect1>
+ </sect>
+
+ <sect><heading>Relationships between source and binary packages -
+ <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
+ <tt>Build-Conflicts</tt>, <tt>Build-Conflicts-Indep</tt>
+ </heading>
+
+ <p>
+ A source package may declare a dependency or a conflict on a
+ binary package. This is done with the control file fields
+ <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
+ <tt>Build-Conflicts</tt>, and
+ <tt>Build-Conflicts-Indep</tt>. Their semantics are that
+ the dependencies and conflicts they define must be satisfied
+ (as defined earlier for binary packages), when one of the
+ targets in <tt>debian/rules</tt> that the particular field
+ applies to is invoked.
+
+ <taglist>
+ <tag><tt>Build-Depends</tt>, <tt>Build-Conflicts</tt></tag>
+ <item>
+ <p>
+ The <tt>Build-Depends</tt> and
+ <tt>Build-Conflicts</tt> fields apply to the targets
+ <tt>build</tt>, <tt>binary</tt>, <tt>binary-arch</tt>
+ and <tt>binary-indep</tt>.
+ </p>
+ </item>
+ <tag><tt>Build-Depends-Indep</tt>, <tt>Build-Conflicts-Indep</tt></tag>
+ <item>
+ <p>
+ The <tt>Build-Depends-Indep</tt> and
+ <tt>Build-Conflicts-Indep</tt> fields apply to the
+ targets <tt>binary</tt> and <tt>binary-indep</tt>.
+ </p>
+ </item>
+ </taglist>
+
+ </p>
+
+ </sect>
+ </chapt>
+
+
+ <chapt id="conffiles"><heading>Configuration file handling
+ </heading>
+
+ <p>
+ <prgn>dpkg</prgn> can do a certain amount of automatic
+ handling of package configuration files.
+ </p>
+
+ <p>
+ Whether this mechanism is appropriate depends on a number of
+ factors, but basically there are two approaches to any
+ particular configuration file.
+ </p>
+
+ <p>
+ The easy method is to ship a best-effort configuration in the
+ package, and use <prgn>dpkg</prgn>'s conffile mechanism to
+ handle updates. If the user is unlikely to want to edit the
+ file, but you need them to be able to without losing their
+ changes, and a new package with a changed version of the file
+ is only released infrequently, this is a good approach.
+ </p>
+
+ <p>
+ The hard method is to build the configuration file from
+ scratch in the <prgn>postinst</prgn> script, and to take the
+ responsibility for fixing any mistakes made in earlier
+ versions of the package automatically. This will be
+ appropriate if the file is likely to need to be different on
+ each system.
+ </p>
+
+
+ <chapt id="sharedlibs"><heading>Shared libraries
+ </heading>
+
+ <p>
+ Packages containing shared libraries must be constructed with
+ a little care to make sure that the shared library is always
+ available. This is especially important for packages whose
+ shared libraries are vitally important, such as the libc.
+ </p>
+
+ <p>
+ Firstly, your package should install the shared libraries
+ under their normal names. For example, the
+ <prgn>libgdbm1</prgn> package should install
+ <tt>libgdbm.so.1.7.3</tt> as
+ <tt>/usr/lib/libgdbm.so.1.7.3</tt>. The files should not be
+ renamed or re-linked by any prerm or postrm scripts;
+ <prgn>dpkg</prgn> will take care of renaming things safely
+ without affecting running programs, and attempts to interfere
+ with this are likely to lead to problems.
+ </p>
+
+ <p>
+ Secondly, your package should include the symlink that
+ <prgn>ldconfig</prgn> would create for the shared libraries.
+ For example, the <prgn>libgdbm1</prgn> package should include
+ a symlink from <tt>/usr/lib/libgdbm.so.1</tt> to
+ <tt>libgdbm.so.1.7.3</tt>. This is needed so that
+ <prgn>ld.so</prgn> can find the library in between the time
+ <prgn>dpkg</prgn> installs it and <prgn>ldconfig</prgn> is run
+ in the <prgn>postinst</prgn> script. Furthermore, older
+ versions of the package management system required the library
+ must be placed before the symlink pointing to it in the
+ <tt>.deb</tt> file. This is so that by the time
+ <prgn>dpkg</prgn> comes to install the symlink (overwriting
+ the previous symlink pointing at an older version of the
+ library) the new shared library is already in place.
+ Unfortunately, this was not not always possible, since it
+ highly depends on the behavior of the file system. Some
+ file systems (such as reiserfs) will reorder the files so it
+ doesn't matter in what order you create them. Starting with
+ release <tt>1.7.0</tt> <prgn>dpkg</prgn> will reorder the
+ files itself when building a package.
+ </p>
+
+ <p>
+ Thirdly, the development package should contain a symlink for
+ the shared library without a version number. For example, the
+ <tt>libgdbm1-dev</tt> package should include a symlink from
+ <tt>/usr/lib/libgdm.so</tt> to <tt>libgdm.so.1.7.3</tt>. This
+ symlink is needed by <prgn>ld</prgn> when compiling packages
+ as it will only look for <tt>libgdm.so</tt> and
+ <tt>libgdm.a</tt> when compiling dynamically or statically,
+ respectively.
+ </p>
+
+ <p>
+ Any package installing shared libraries in a directory that's listed
+ in <tt>/etc/ld.so.conf</tt> or in one of the default library
+ directories of <prgn>ld.so</prgn> (currently, these are <tt>/usr/lib</tt>
+ and <tt>/lib</tt>) must call <prgn>ldconfig</prgn> in its <prgn>postinst</prgn>
+ script if and only if the first argument is `configure'. However, it
+ is important not to call <prgn>ldconfig</prgn> in the postrm or preinst
+ scripts in the case where the package is being upgraded (see <ref
+ id="unpackphase">), as <prgn>ldconfig</prgn> will see the temporary names
+ that <prgn>dpkg</prgn> uses for the files while it is
+ installing them and will make the shared library links point
+ to them, just before <prgn>dpkg</prgn> continues the
+ installation and removes the links!
+ </p>
+
+ <sect id="shlibs"><heading>The <tt>shlibs</tt> File Format
+ </heading>
+
+ <p>
+ This file is for use by <prgn>dpkg-shlibdeps</prgn> and is
+ required when your package provides shared libraries.
+ </p>
+
+ <p>
+ Each line is of the form:
+ <example>
+ <var>library-name</var> <var>version-or-soname</var> <var>dependencies ...</var>
+ </example>
+ </p>
+
+ <p>
+ <var>library-name</var> is the name of the shared library,
+ for example <tt>libc5</tt>.
+ </p>
+
+ <p>
+ <var>version-or-soname</var> is the soname of the library -
+ i.e., the thing that must exactly match for the library to be
+ recognized by <prgn>ld.so</prgn>. Usually this is the major
+ version number of the library.
+ </p>
+
+ <p>
+ <var>dependencies</var> has the same syntax as a dependency
+ field in a binary package control file. It should give
+ details of which package(s) are required to satisfy a binary
+ built against the version of the library contained in the
+ package. See <ref id="depsyntax">.
+ </p>
+
+ <p>
+ For example, if the package <tt>foo</tt> contains
+ <tt>libfoo.so.1.2.3</tt>, where the soname of the library is
+ <tt>libfoo.so.1</tt>, and the first version of the package
+ which contained a minor number of at least <tt>2.3</tt> was
+ <var>1.2.3-1</var>, then the package's <var>shlibs</var>
+ could say:
+ <example>
+ libfoo 1 foo (>= 1.2.3-1)
+ </example>
+ </p>
+
+ <p>
+ The version-specific dependency is to avoid warnings from
+ <prgn>ld.so</prgn> about using older shared libraries with
+ newer binaries.</p>
+ </sect>
+
+ <sect><heading>Further Technical information on
+ <tt>shlibs</tt></heading>
+
+ <sect1><heading><em>What</em> are the <tt>shlibs</tt> files?
+ </heading>
+
+ <p>
+ The <tt>debian/shlibs</tt> file provides a way of checking
+ for shared library dependencies on packaged binaries.
+ They are intended to be used by package maintainers to
+ make their lives easier.
+ </p>
+
+ <p>
+ Other <tt>shlibs</tt> files that exist on a Debian system are
+ <list>
+ <item> <p><tt>/etc/dpkg/shlibs.default</tt></p></item>
+ <item> <p><tt>/etc/dpkg/shlibs.override</tt></p></item>
+ <item> <p><tt>/var/lib/dpkg/info/*.shlibs</tt></p></item>
+ <item> <p><tt>debian/shlibs.local</tt></p></item>
+ </list>
+ These files are used by <prgn>dpkg-shlibdeps</prgn> when
+ creating a binary package.</p>
+ </sect1>
+
+ <sect1><heading><em>How</em> does <prgn>dpkg-shlibdeps</prgn>
+ work?
+ </heading>
+ <p>
+ <prgn>dpkg-shlibdeps</prgn>
+ determines the shared libraries directly
+ <footnote>
+ <p>
+ It used to do this by calling <prgn>ldd</prgn>, but it
+ now calls <prgn>objdump</prgn> to to this. This
+ requires a couple of changes in the way that packages
+ are built.
+ </p>
+ <p>
+ A binary <tt>foo</tt> directly uses a library
+ <tt>libbar</tt> if it is linked with that
+ library. Other libraries that are needed by
+ <tt>libbar</tt> are linked indirectly to <tt>foo</tt>,
+ and the dynamic linker will load them automatically
+ when it loads <tt>libbar</tt>. Running<prgn>ldd</prgn>
+ lists all of the libraries used, both directly and
+ indirectly; but <prgn>objdump</prgn> only lists the
+ directly linked libraries. A package only needs to
+ depend on the libraries it is directly linked to,
+ since the dependencies for those libraries should
+ automatically pull in the other libraries.
+ </p>
+ <p>
+ This change does mean a change in the way packages are
+ build though: currently <prgn>dpkg-shlibdeps</prgn> is
+ only run on binaries. But since we will now rely on the
+ libraries depending on the libraries they themselves
+ need, the packages containing those libraries will
+ need to run <prgn>dpkg-shlibdeps</prgn> on the
+ libraries.
+ </p>
+ <p>
+ A good example where this would help us is the current
+ mess with multiple version of the <tt>mesa</tt>
+ library. With the <prgn>ldd</prgn>-based system, every
+ package that uses <tt>mesa</tt> needs to add a
+ dependency on <tt>svgalib|svgalib-dummy</tt> in order
+ to handle the glide <tt>mesa</tt> variant. With an
+ <prgn>objdump</prgn>-based system this isn't necessary
+ anymore and would have saved everyone a lot of work.
+ </p>
+ <p>
+ Another example: we could update <tt>libimlib</tt>
+ with a new version that supports a new graphics format
+ called dgf. If we use the old <prgn>ldd</prgn> method,
+ every package that uses <tt>libimlib</tt> would need
+ to be recompiled so it would also depend on
+ <tt>libdgf</tt> or it wouldn't run due to missing
+ symbols. However with the new system, packages using
+ <tt>libimlib</tt> can rely on <tt>libimlib</tt> itself
+ having the dependency on <tt>libdgf</tt> and wouldn't
+ need to be updated.
+ </p>
+ </footnote>
+ used by the compiled binaries and libraries passed through
+ on its command line.
+ </p>
+
+ <p>
+ For each shared library linked to,
+ <prgn>dpkg-shlibdeps</prgn> needs to know
+ <list compact="compact">
+ <item><p>the package containing the library, and</p></item>
+ <item><p>the library version number,</p></item>
+ </list>
+ and it scans the following files in this order:
+ <enumlist compact="compact">
+ <item><p><tt>debian/shlibs.local</tt></p></item>
+ <item><p><tt>/etc/dpkg/shlibs.override</tt></p></item>
+ <item><p><tt>/var/lib/dpkg/info/*.shlibs</tt></p></item>
+ <item><p><tt>/etc/dpkg/shlibs.default</tt></p></item>
+ </enumlist>
+ </p>
+ </sect1>
+
+ <sect1><heading><em>Who</em> maintains the various
+ <tt>shlibs</tt> files?
+ </heading>
+
+ <p>
+ <list compact="compact">
+ <item>
+ <p><tt>/etc/dpkg/shlibs.default</tt> - the maintainer
+ of dpkg</p>
+ </item>
+ <item>
+ <p>
+ <tt>/var/lib/dpkg/info/<var>package</var>.shlibs</tt>
+ - the maintainer of each package</p>
+ </item>
+ <item>
+ <p>
+ <tt>/etc/dpkg/shlibs.override</tt> - the local
+ system administrator</p>
+ </item>
+ <item>
+ <p><tt>debian/shlibs.local</tt> - the maintainer of
+ the package
+ </p>
+ </item>
+ </list>
+ The <tt>shlibs.default</tt> file is managed by
+ <prgn>dpkg</prgn>. The entries in <tt>shlibs.default</tt>
+ that are provided by <prgn>dpkg</prgn> are just there to
+ fix things until the shared library packages all have
+ <tt>shlibs</tt> files.
+ </p>
+ </sect1>
+
+ <sect1><heading><em>How</em> to use <prgn>dpkg-shlibdeps</prgn> and
+ the <tt>shlibs</tt> files
+ </heading>
+
+ <sect2><heading>If your package doesn't provide a shared
+ library
+ </heading>
+
+ <p>
+ Put a call to <prgn>dpkg-shlibdeps</prgn> into your
+ <tt>debian/rules</tt> file. If your package contains
+ only binaries (e.g. no scripts) use:
+ <example>
+ dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/*
+ </example>
+ If <prgn>dpkg-shlibdeps</prgn> doesn't complain, you're
+ done. If it does complain you might need to create your
+ own <tt>debian/shlibs.local</tt> file.</p>
+ </sect2>
+
+ <sect2><heading>If your package provides a shared library
+ </heading>
+
+ <p>
+ Create a <tt>debian/shlibs</tt> file and let
+ <tt>debian/rules</tt> install it in the control area:
+ <example>
+ install -m644 debian/shlibs debian/tmp/DEBIAN
+ </example>
+ If your package contains additional binaries see above.
+ </p>
+ </sect2>
+ </sect1>
+
+ <sect1><heading><em>How</em> to write
+ <tt>debian/shlibs.local</tt>
+ </heading>
+
+ <p>
+ This file is intended only as a <em>temporary</em> fix if
+ your binaries depend on a library which doesn't provide
+ its own <tt>/var/lib/dpkg/info/*.shlibs</tt> file yet.
+ </p>
+
+ <p>
+ Let's assume you are packaging a binary <tt>foo</tt>. Your
+ output in building the package might look like this.
+ <example>
+ $ ldd foo
+ libbar.so.1 => /usr/X11R6/lib/libbar.so.1.0 (0x4001e000)
+ libX11.so.6 => /usr/X11R6/lib/libX11.so.6 (0x4002c000)
+ libc.so.6 => /lib/libc.so.6 (0x40114000)
+ /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
+ </example>
+ And when you ran <prgn>dpkg-shlibdeps</prgn>
+ <example>
+ $ dpkg-shlibdeps -O foo
+ dpkg-shlibdeps: warning: unable to find dependency information for shared library libbar
+ (soname 1, path /usr/X11R6/lib/libbar.so.1.0, dependency field Depends)
+ shlibs:Depends=libc6 (>= 2.2.1), xlibs (>= 4.0.1-11)
+ </example>
+ The <prgn>foo</prgn> binary depends on the
+ <prgn>libbar</prgn> shared library, but no package seems
+ to provide a <tt>*.shlibs</tt> file in
+ <tt>/var/lib/dpkg/info/</tt>. Let's determine the package
+ responsible:
+ </p>
+
+ <p>
+ <example>
+ $ dpkg -S /usr/X11R6/lib/libbar.so.1.0
+ bar1: /usr/X11R6/lib/libbar.so.1.0
+ $ dpkg -s bar1 | grep Version
+ Version: 1.0-1
+ </example>
+ This tells us that the <prgn>bar1</prgn> package, version
+ 1.0-1 is the one we are using. Now we can create our own
+ <tt>debian/shlibs.local</tt> to temporarily fix the above
+ problem. Include the following line into your
+ <tt>debian/shlibs.local</tt> file.
+ <example>
+ libbar 1 bar1 (>= 1.0-1)
+ </example>
+ Now your package build should work. As soon as the
+ maintainer of <prgn>libbar1</prgn> provides a
+ <tt>shlibs</tt> file, you can remove your
+ <tt>debian/shlibs.local</tt> file.
+ </p>
+ </sect1>
+ </sect>
+ </chapt>
+
+ <chapt><heading>The Operating System</heading>
+
+
+ <sect>
+ <heading>File system hierarchy</heading>
+
+
+ <sect1>
+ <heading>Linux File system Structure</heading>
+
+ <p>
+ The location of all installed files and directories must
+ comply with the Linux File system Hierarchy Standard
+ (FHS). The latest version of this document can be found
+ alongside this manual or on
+ <url id="http://www.pathname.com/fhs/">.
+ Specific questions about following the standard may be
+ asked on <prgn>debian-devel</prgn>, or referred to Daniel
+ Quinlan, the FHS coordinator, at
+ <email>quinlan@pathname.com</email>.</p></sect1>
+
+
+ <sect1>
+ <heading>Site-specific programs</heading>
+
+ <p>
+ As mandated by the FHS, packages must not place any
+ files in <tt>/usr/local</tt>, either by putting them in
+ the file system archive to be unpacked by <prgn>dpkg</prgn>
+ or by manipulating them in their maintainer scripts.</p>
+
+ <p>
+ However, the package may create empty directories below
+ <tt>/usr/local</tt> so that the system administrator knows
+ where to place site-specific files. These directories
+ should be removed on package removal if they are
+ empty.</p>
+
+ <p>
+ Note, that this applies only to directories <em>below</em>
+ <tt>/usr/local</tt>, not <em>in</em>
+ <tt>/usr/local</tt>. Packages must not create sub-directories
+ in the directory <tt>/usr/local</tt> itself, except those listed in
+ FHS, section 4.5. However, you may create directories
+ below them as you wish. You must not remove any of the
+ directories listed in 4.5, even if you created them.</p>
+
+ <p>
+ Since <tt>/usr/local</tt> can be mounted read-only from a
+ remote server, these directories must be created and
+ removed by the <tt>postinst</tt> and <tt>prerm</tt>
+ maintainer scripts. These scripts must not fail if either
+ of these operations fail. (In the future, it will be
+ possible to tell <prgn>dpkg</prgn> not to unpack files
+ matching certain patterns, so that the directories can be
+ included in the <tt>.deb</tt> packages and system
+ administrators who do not wish these directories in
+ /usr/local do not need to have them.)</p>
+
+ <p>
+ For example, the <prgn>emacs</prgn> package will contain
+ <example>
+ mkdir -p /usr/local/lib/emacs/site-lisp || true
+ </example>
+ in the <tt>postinst</tt> script, and
+ <example>
+ rmdir /usr/local/lib/emacs/site-lisp || true
+ rmdir /usr/local/lib/emacs || true
+ </example>
+ in the <tt>prerm</tt> script.</p>
+
+ <p>
+ If you do create a directory in <tt>/usr/local</tt> for
+ local additions to a package, you should ensure that
+ settings in <tt>/usr/local</tt> take precedence over the
+ equivalents in <tt>/usr</tt>.</p>
+
+ <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 (by default) have
+ permissions 2775 (group-writable and set-group-id) and be
+ owned by <tt>root.staff</tt>.</p>
+ </sect1>
+ </sect>
+
+ <sect>
+ <heading>Users and groups</heading>
+
+ <p>
+ The Debian system can be configured to use either plain or
+ shadow passwords.</p>
+
+ <p>
+ Some user ids (UIDs) and group ids (GIDs) are reserved
+ globally for use by certain packages. Because some packages
+ need to include files which are owned by these users or
+ groups, or need the ids compiled into binaries, these ids
+ must be used on any Debian system only for the purpose for
+ which they are allocated. This is a serious restriction, and
+ we should avoid getting in the way of local administration
+ policies. In particular, many sites allocate users and/or
+ local system groups starting at 100.</p>
+
+ <p>
+ Apart from this we should have dynamically allocated ids,
+ which should by default be arranged in some sensible
+ order--but the behavior should be configurable.</p>
+
+ <p>
+ Packages other than <tt>base-passwd</tt> must not modify
+ <tt>/etc/passwd</tt>, <tt>/etc/shadow</tt>,
+ <tt>/etc/group</tt> or <tt>/etc/gshadow</tt>.</p>
+
+ <p>
+ The UID and GID ranges are as follows:
+ <taglist>
+ <tag>0-99:</tag>
+ <item>
+ <p>
+ Globally allocated by the Debian project, the
+ same on every Debian system. These ids will appear in
+ the <tt>passwd</tt> and <tt>group</tt> files of all
+ Debian systems, new ids in this range being added
+ automatically as the <tt>base-passwd</tt> package is
+ updated.</p>
+
+ <p>
+ Packages which need a single statically allocated uid
+ or gid should use one of these; their maintainers
+ should ask the <tt>base-passwd</tt> maintainer for
+ ids.</p>
+ </item>
+
+ <tag>100-999:</tag>
+ <item>
+ <p>
+ Dynamically allocated system users and groups.
+ Packages which need a user or group, but can have this
+ user or group allocated dynamically and differently on
+ each system, should use `<tt>adduser --system</tt>' to
+ create the group and/or user. <prgn>adduser</prgn>
+ will check for the existence of the user or group, and
+ if necessary choose an unused id based on the ranges
+ specified in <tt>adduser.conf</tt>.</p></item>
+
+
+ <tag>1000-29999:</tag>
+ <item>
+ <p>
+ Dynamically allocated user accounts. By default
+ <prgn>adduser</prgn> will choose UIDs and GIDs for
+ user accounts in this range, though
+ <tt>adduser.conf</tt> may be used to modify this
+ behavior.</p>
+ </item>
+
+ <tag>30000-59999:</tag>
+ <item>
+ <p>Reserved.</p></item>
+
+
+ <tag>60000-64999:</tag>
+ <item>
+ <p>
+ Globally allocated by the Debian project, but only
+ created on demand. The ids are allocated centrally and
+ statically, but the actual accounts are only created
+ on users' systems on demand.</p>
+
+ <p>
+ These ids are for packages which are obscure or which
+ require many statically-allocated ids. These packages
+ should check for and create the accounts in
+ <tt>/etc/passwd</tt> or <tt>/etc/group</tt> (using
+ <prgn>adduser</prgn> if it has this facility) if
+ necessary. Packages which are likely to require
+ further allocations should have a `hole' left after
+ them in the allocation, to give them room to
+ grow.</p></item>
+
+
+ <tag>65000-65533:</tag>
+ <item>
+ <p>Reserved.</p></item>
+
+
+ <tag>65534:</tag>
+ <item>
+ <p>User `<tt>nobody</tt>.' The corresponding gid refers
+ to the group `<tt>nogroup</tt>.'</p></item>
+
+
+ <tag>65535:</tag>
+ <item>
+ <p>
+ <tt>(uid_t)(-1) == (gid_t)(-1)</tt>. NOT TO BE USED,
+ because it is the error return sentinel value.</p>
+ </item>
+ </taglist>
+ </p>
+ </sect>
+ <sect id="sysvinit">
+ <heading>System run levels</heading>
+
+
+ <sect1 id="/etc/init.d">
+ <heading>Introduction</heading>
+
+ <p>
+ The <tt>/etc/init.d</tt> directory contains the scripts
+ executed by <prgn>init</prgn> at boot time and when init
+ state (or `runlevel') is changed (see <manref name="init"
+ section="8">).</p>
+
+ <p>
+ There are at least two different, yet functionally
+ equivalent, ways of handling these scripts. For the sake
+ of simplicity, this document describes only the symbolic
+ link method. However, it must not be assumed by maintainer
+ scripts that this method is being used, and any automated
+ manipulation of the various runlevel behaviours by
+ maintainer scripts must be performed using `update-rc.d'
+ as described below and not by manually installing or
+ removing symlinks. For information on the
+ implementation details of the other method, implemented in
+ the <tt>file-rc</tt> package, please refer to the
+ documentation of that package.</p>
+
+ <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>
+ 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>.</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>,
+ followed by the scripts prefixed with an <tt>S</tt>, each
+ with the single argument <tt>start</tt>. The <tt>K</tt>
+ links are responsible for killing services and the
+ <tt>S</tt> link for starting services upon entering the
+ runlevel.</p>
+
+ <p>
+ For example, if we are changing from runlevel 2 to
+ runlevel 3, init will first execute all of the <tt>K</tt>
+ prefixed scripts it finds in <tt>/etc/rc3.d</tt>, and then
+ all of the <tt>S</tt> prefixed scripts. The links
+ starting with <tt>K</tt> will cause the referred-to file
+ to be executed with an argument of <tt>stop</tt>, and the
+ <tt>S</tt> links with an argument of <tt>start</tt>.</p>
+
+ <p>
+ The two-digit number <var>mm</var> is used to decide which
+ order to start and stop things in--low-numbered links have
+ their scripts run first. For example, the <tt>K20</tt>
+ scripts will be executed before the <tt>K30</tt> scripts.
+ This is used when a certain service must be started before
+ another. For example, the name server <prgn>bind</prgn>
+ might need to be started before the news server
+ <prgn>inn</prgn> so that <prgn>inn</prgn> can set up its
+ access lists. In this case, the script that starts
+ <prgn>bind</prgn> would have a lower number than the
+ script that starts <prgn>inn</prgn> so that it runs first:
+ <example>
+ /etc/rc2.d/S17bind
+ /etc/rc2.d/S70inn
+ </example>
+ </p>
+ </sect1>
+
+ <sect1>
+ <heading>Writing the scripts</heading>
+
+ <p>
+ Packages that include daemons for system services should
+ place scripts in <tt>/etc/init.d</tt> to start or stop
+ services at boot time or during a change of runlevel.
+ These scripts should be named
+ <tt>/etc/init.d/<var>package</var></tt>, and they should
+ accept one argument, saying what to do:
+
+ <taglist>
+ <tag><tt>start</tt></tag>
+ <item><p>start the service,</p></item>
+
+ <tag><tt>stop</tt></tag>
+ <item><p>stop the service,</p></item>
+
+ <tag><tt>restart</tt></tag>
+ <item><p>stop and restart the service,</p></item>
+
+ <tag><tt>reload</tt></tag>
+ <item><p>cause the configuration of the service to be
+ reloaded without actually stopping and restarting
+ the service,</p></item>
+
+ <tag><tt>force-reload</tt></tag> <item><p>cause the
+ configuration to be reloaded if the service supports
+ this, otherwise restart the service.</p></item>
+ </taglist>
+
+ The <tt>start</tt>, <tt>stop</tt>, <tt>restart</tt>, and
+ <tt>force-reload</tt> options should be supported by all
+ scripts in <tt>/etc/init.d</tt>, the <tt>reload</tt>
+ option is optional.</p>
+
+ <p>
+ The <tt>init.d</tt> scripts should ensure that they will
+ behave sensibly if invoked with <tt>start</tt> when the
+ service is already running, or with <tt>stop</tt> when it
+ isn't, and that they don't kill unfortunately-named user
+ processes. The best way to achieve this is usually to use
+ <prgn>start-stop-daemon</prgn>.</p>
+
+ <p>
+ If a service reloads its configuration automatically (as
+ in the case of <prgn>cron</prgn>, for example), the
+ <tt>reload</tt> option of the <tt>init.d</tt> script
+ should behave as if the configuration has been reloaded
+ successfully.</p>
+
+ <p>
+ These scripts should not fail obscurely when the
+ configuration files remain but the package has been
+ removed, as configuration files remain on the system after
+ the package has been removed. Only when <prgn>dpkg</prgn>
+ is executed with the <tt>--purge</tt> option will
+ configuration files be removed. In particular, 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>
+
+ <p>
+ Often there are some values in the `<tt>init.d</tt>'
+ scripts that a system administrator will frequently want
+ to change. While the scripts are frequently conffiles,
+ modifying them requires that the administrator merge in
+ their changes each time the package is upgraded and the
+ conffile changes. To ease the burden on the system
+ administrator, such configurable values should not be
+ placed directly in the script. Instead, they should be
+ placed in a file in `<tt>/etc/default</tt>', which
+ typically will have the same base name as the
+ `<tt>init.d</tt>' script. This extra file can be sourced
+ by the script when the script runs. It must contain only
+ variable settings and comments.
+ </p>
+
+ <p>
+ To ensure that vital configurable values are always
+ available, the `<tt>init.d</tt>' script should set default
+ values for each of the shell variables it uses before
+ sourcing the <tt>/etc/default/</tt> file. Also, since the
+ `<tt>/etc/default/</tt>' file is often a conffile, the
+ `<tt>init.d</tt>' script must behave sensibly without
+ failing if it is deleted.
+ </p>
+
+ </sect1>
+
+ <sect1>
+ <heading>Managing the links</heading>
+
+ <p>
+ The program <prgn>update-rc.d</prgn> is provided to make
+ it easier for package maintainers to arrange for the
+ proper creation and removal of
+ <tt>/etc/rc<var>n</var>.d</tt> symbolic links, or their
+ functional equivalent if another method is being used.
+ This may be used by maintainers in their packages'
+ <tt>postinst</tt> and <tt>postrm</tt> scripts.</p>
+
+ <p>
+ You must use this script to make changes to
+ <tt>/etc/rc<var>n</var>.d</tt> and <em>never</em> either
+ include any <tt>/etc/rc<var>n</var>.d</tt> symbolic links
+ in the actual archive or manually create or remove the
+ symbolic links in maintainer scripts. (The latter will
+ fail if an alternative method of maintaining runlevel
+ information is being used.)</p>
+
+ <p>
+ By default <prgn>update-rc.d</prgn> will start services in
+ each of the multi-user state runlevels (2, 3, 4, and 5)
+ and stop them in the halt runlevel (0), the single-user
+ runlevel (1) and the reboot runlevel (6). The system
+ administrator will have the opportunity to customize
+ runlevels by 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
+ <tt>postinst</tt> script
+ <example>
+ update-rc.d <var>package</var> defaults >/dev/null
+ </example>
+ and in your <tt>postrm</tt>
+ <example>
+ if [ purge = "$1" ]; then
+ update-rc.d <var>package</var> remove >/dev/null
+ fi
+ </example></p>
+
+ <p>
+ This will use a default sequence number of 20. If it does
+ not matter when or in which order the script is run, use
+ this default. If it does, then you should talk to the
+ maintainer of the <prgn>sysvinit</prgn> package or post to
+ <tt>debian-devel</tt>, and they will help you choose a
+ number.</p>
+
+ <p>
+ For more information about using <tt>update-rc.d</tt>,
+ please consult its manpage <manref name="update-rc.d"
+ section="8">.</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">. Packages must not
+ place files in <tt>/etc/rc.boot</tt>.</p>
+
+ <sect1 id="init.d notes">
+ <heading>Notes</heading>
+
+ <p>
+ <em>Do not</em> include the
+ <tt>/etc/rc<var>n</var>.d/*</tt> symbolic links in the
+ <tt>.deb</tt> file system archive! <em>This will cause
+ problems!</em> You must create them with
+ <prgn>update-rc.d</prgn>, as above.</p>
+
+ <p>
+ <em>Do not</em> include the
+ <tt>/etc/rc<var>n</var>.d/*</tt> symbolic links in
+ <prgn>dpkg</prgn>'s conffiles list! <em>This will cause
+ problems!</em> You should, however, treat the
+ <tt>/etc/init.d</tt> scripts as configuration files,
+ either by marking them as conffiles or managing them
+ correctly in the maintainer scripts (see
+ <ref id="config files">). (This is important since we want
+ to give the local system administrator the chance to adapt
+ the scripts to the local system--e.g., to disable a
+ service without de-installing the package, or to specify
+ some special command line options when starting a
+ service--while making sure her changes aren't lost during
+ the next package upgrade.)</p>
+ </sect1>
+
+ <sect1>
+ <heading>Example</heading>
+
+ <p>
+ The <prgn>bind</prgn> DNS (nameserver) package wants to
+ make sure that the nameserver is running in multiuser
+ runlevels, and is properly shut down with the system. It
+ puts a script in <tt>/etc/init.d</tt>, naming the script
+ appropriately <tt>bind</tt>. As you can see, the script
+ interprets the argument <tt>reload</tt> to send the
+ nameserver a <tt>HUP</tt> signal (causing it to reload its
+ configuration); this way the user can say
+ <tt>/etc/init.d/bind reload</tt> to reload the name
+ server. The script has one configurable value, which can
+ be used to pass parameters to the named program at
+ startup.
+ </p>
+
+ <p>
+ <example>
+ #!/bin/sh
+ #
+ # Original version by Robert Leslie
+ # <rob@mars.org>, edited by iwj and cs
+
+ test -x /usr/sbin/named || exit 0
+
+ # Source defaults file.
+ PARAMS=''
+ if [ -f /etc/default/bind ]; then
+ . /etc/default/bind
+ fi
+
+
+ case "$1" in
+ start)
+ echo -n "Starting domain name service: named"
+ start-stop-daemon --start --quiet --exec /usr/sbin/named \
+ -- $PARAMS
+ echo "."
+ ;;
+ stop)
+ echo -n "Stopping domain name service: named"
+ start-stop-daemon --stop --quiet \
+ --pidfile /var/run/named.pid --exec /usr/sbin/named
+ echo "."
+ ;;
+ restart)
+ echo -n "Restarting domain name service: named"
+ start-stop-daemon --stop --quiet \
+ --pidfile /var/run/named.pid --exec /usr/sbin/named
+ start-stop-daemon --start --verbose --exec /usr/sbin/named \
+ -- $PARAMS
+ echo "."
+ ;;
+ force-reload|reload)
+ echo -n "Reloading configuration of domain name service: named"
+ start-stop-daemon --stop --signal 1 --quiet \
+ --pidfile /var/run/named.pid --exec /usr/sbin/named
+ echo "."
+ ;;
+ *)
+ echo "Usage: /etc/init.d/bind {start|stop|restart|reload|force-reload}" >&2
+ exit 1
+ ;;
+ esac
+
+ exit 0
+ </example>
+ </p>
+
+ <p>
+ Complementing the above init script is a file
+ '<tt>/etc/default/bind</tt>', which contains configurable
+ parameters used by the script.
+ </p>
+ <p>
+ <example>
+ # Specified parameters to pass to named. See named(8).
+ # You may uncomment the following line, and edit to taste.
+ #PARAMS="-u nobody"
+ </example>
+ </p>
+
+ <p>
+ Another example on which to base your <tt>/etc/init.d</tt>
+ scripts is in <tt>/etc/init.d/skeleton</tt>.</p>
+
+ <p>
+ If this package is happy with the default setup from
+ <prgn>update-rc.d</prgn>, namely an ordering number of 20
+ and having named running in all runlevels, it can say in
+ its <tt>postinst</tt>:
+ <example>
+ update-rc.d bind defaults >/dev/null
+ </example>
+ And in its <tt>postrm</tt>, to remove the links when the
+ package is purged:
+ <example>
+ if [ purge = "$1" ]; then
+ update-rc.d bind remove >/dev/null
+ fi
+ </example></p>
+ </sect1></sect>
+
+ <sect>
+ <heading>Cron jobs</heading>
+
+ <p>
+ Packages must not modify the configuration file
+ <tt>/etc/crontab</tt>, and they must not modify the files in
+ <tt>/var/spool/cron/crontabs</tt>.</p>
+
+ <p>
+ If a package wants to install a job that has to be executed
+ via cron, it should place a file with the name of the
+ package in one of the following directories:
+ <example>
+ /etc/cron.daily
+ /etc/cron.weekly
+ /etc/cron.monthly
+ </example>
+ As these directory names imply, the files within them are
+ executed on a daily, weekly, or monthly basis,
+ respectively. The exact times are listed in
+ <tt>/etc/crontab</tt>.</p>
+
+ <p>
+ All files installed in any of these directories must be
+ scripts (shell scripts, Perl scripts, etc.) so that they can
+ easily be modified by the local system administrator. In
+ addition, they should be treated as configuration files.</p>
+
+ <p>
+ If a certain job has to be executed more frequently than
+ daily, the package should install a file
+ <tt>/etc/cron.d/<var>package-name</var></tt>. This file uses
+ the same syntax as <tt>/etc/crontab</tt> and is processed by
+ <prgn>cron</prgn> automatically. The file must also be
+ treated as a configuration file. (Note, that entries in the
+ <tt>/etc/cron.d</tt> directory are not handled by
+ <prgn>anacron</prgn>. Thus, you should only use this
+ directory for jobs which may be skipped if the system is not
+ running.)</p>
+
+ <p>
+ The scripts or crontab entries in these directories should
+ check if all necessary programs are installed before they
+ try to execute them. Otherwise, problems will arise when a
+ package was removed but not purged since configuration files
+ are kept on the system in this situation.</p>
+ </sect>
+
+ <sect>
+ <heading>Console messages</heading>
+
+ <p>
+ This section describes different formats for messages
+ written to standard output by the <tt>/etc/init.d</tt>
+ scripts. The intent is to improve the consistency of
+ Debian's startup and shutdown look and feel.</p>
+
+ <p>
+ Please look very careful at the details. We want to get the
+ messages to look exactly the same way concerning spaces,
+ punctuation, and case of letters.</p>
+
+ <p>
+ Here is a list of overall rules that you should use when you
+ create output messages. They can be useful if you have a
+ non-standard message that isn't covered in the sections
+ below.</p>
+
+ <p>
+ <list>
+ <item>
+ <p>
+ Every message should cover one line, start with a
+ capital letter and end with a period `.'.</p></item>
+
+
+ <item>
+ <p>
+ If you want to express that the computer is working on
+ something (performing a specific task, not starting or
+ stopping a program), we use an ``ellipsis'', namely
+ three dots `...'. Note that we don't insert spaces in
+ front of or behind the dots. If the task has been
+ completed we write `done.' and a line feed.</p></item>
+
+
+ <item>
+ <p>
+ Design your messages as if the computer is telling you
+ what he is doing (let him be polite :-) but don't
+ mention ``him'' directly. For example, if you think
+ of saying
+ <example>
+ I'm starting network daemons: nfsd mountd.
+ </example>
+ just say
+ <example>
+ Starting network daemons: nfsd mountd.
+ </example></p></item>
+ </list></p>
+
+ <p>
+ The following formats should be used</p>
+
+ <p>
+ <list>
+ <item>
+ <p>when daemons get started.</p>
+
+ <p>
+ Use this format if your script starts one or more
+ daemons. The output should look like this (a single
+ line, no leading spaces):
+ <example>
+ Starting <description>: <daemon-1> <daemon-2> <...> <daemon-n>.
+ </example>
+ The <description> should describe the subsystem
+ the daemon or set of daemons are part of, while
+ <daemon-1> up to <daemon-n> denote each
+ daemon's name (typically the file name of the
+ program).</p>
+
+ <p>
+ For example, the output of /etc/init.d/lpd would look like:
+ <example>
+ Starting printer spooler: lpd.
+ </example></p>
+
+ <p>
+ This can be achieved by saying
+ <example>
+ echo -n "Starting printer spooler: lpd"
+ start-stop-daemon --start --quiet lpd
+ echo "."
+ </example>
+ in the script. If you have more than one daemon to
+ start, you should do the following:
+ <example>
+ echo -n "Starting remote file system services:"
+ echo -n " nfsd"; start-stop-daemon --start --quiet nfsd
+ echo -n " mountd"; start-stop-daemon --start --quiet mountd
+ echo -n " ugidd"; start-stop-daemon --start --quiet ugidd
+ echo "."
+ </example>
+ This makes it possible for the user to see what takes
+ so long and when the final daemon has been
+ started. You should be careful where to put spaces: In the
+ example above the system administrator can easily
+ comment out a line if he don't wants to start a
+ specific daemon, while the displayed message still
+ looks good.</p></item>
+
+
+ <item>
+ <p>when something needs to be configured.</p>
+
+ <p>
+ If you have to set up different parameters of the
+ system upon boot up, you should use this format:
+ <example>
+ Setting <parameter> to `<value>'.
+ </example></p>
+
+ <p>
+ You can use the following echo statement to get the quotes right:
+ <example>
+ echo "Setting DNS domainname to \`"value"'."
+ </example></p>
+
+ <p>
+ Note that the left quotation mark (`) is different
+ from the right (').</p></item>
+
+ <item>
+ <p>when a daemon is stopped.</p>
+
+ <p>
+ When you stop a daemon you should issue a message
+ similar to the startup message, except that `Starting'
+ is replaced with `Stopping'.</p>
+
+ <p>
+ So stopping the printer daemon will like like this:
+ <example>
+ Stopping printer spooler: lpd.
+ </example></p></item>
+
+ <item>
+ <p>when something is executed.</p>
+
+ <p>
+ There are several examples where you have to run a
+ program at system startup or shutdown to perform a
+ specific task. For example, setting the system's clock
+ via `netdate' or killing all processes when the system
+ comes down. Your message should like this:
+ <example>
+ Doing something very useful...done.
+ </example>
+ You should print the `done.' right after the job has been completed,
+ so that the user gets informed why he has to wait. You can get this
+ behavior by saying
+ <example>
+ echo -n "Doing something very useful..."
+ do_something
+ echo "done."
+ </example>
+ in your script.</p></item>
+
+ <item>
+ <p>when the configuration is reloaded.</p>
+
+ <p>
+ When a daemon is forced to reload its configuration
+ files you should use the following format:
+ <example>
+ Reloading <daemon's-name> configuration...done.
+ </example></p></item>
+
+ <item>
+ <p>when none of the above rules apply.</p>
+
+ <p>
+ If you have to print a message that doesn't fit into
+ the styles described above, you can use something
+ appropriate, but please have a look at the overall
+ rules listed above.</p></item>
+ </list></p></sect>
+
+
+ <sect>
+ <heading>Menus</heading>
+
+ <p>
+ Menu entries should follow the current menu policy as
+ defined in the file <ftpsite>ftp.debian.org</ftpsite> in
+ <ftppath>/debian/doc/package-developer/menu-policy.txt.gz</ftppath>
+ or your local mirror. In addition, it is included in the
+ <tt>debian-policy</tt> package.
+ </p>
+
+ <p>
+ The Debian <tt>menu</tt> packages provides a unique
+ interface between packages providing applications and
+ documents, and <em>menu programs</em> (either X window
+ managers or text-based menu programs as
+ <prgn>pdmenu</prgn>).</p>
+
+ <p>
+ All packages that provide applications that need not be
+ passed any special command line arguments for normal
+ operation should register a menu entry for those
+ applications, so that users of the <tt>menu</tt> package
+ will automatically get menu entries in their window
+ managers, as well in shells like <tt>pdmenu</tt>.</p>
+
+ <p>
+ 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>
+
+
+ <sect>
+ <heading>Multimedia handlers</heading>
+
+ <p>
+ Packages which provide the ability to view/show/play,
+ compose, edit or print MIME types should register themselves
+ as such following the current MIME support policy as defined
+ in the file found on <ftpsite>ftp.debian.org</ftpsite> in
+ <ftppath>/debian/doc/package-developer/mime-policy.txt.gz</ftppath>
+ or your local mirror. In addition, it is included in the
+ <tt>debian-policy</tt> package.
+ </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>
+
+ <p>
+ To achieve a consistent keyboard configuration (i.e., all
+ applications interpret a keyboard event the same way) all
+ programs in the Debian distribution must be configured to
+ comply with the following guidelines.</p>
+
+ <p>
+ Here is a list that contains certain keys and their interpretation:
+
+ <taglist>
+ <tag><tt><--</tt></tag>
+ <item><p>delete the character to the left of the cursor</p></item>
+
+ <tag><tt>Delete</tt></tag>
+ <item><p>delete the character to the right of the cursor</p></item>
+
+ <tag><tt>Control+H</tt></tag>
+ <item><p>emacs: the help prefix</p></item>
+ </taglist>
+
+ The interpretation of any keyboard events should be independent
+ of the terminal that's used, be it a virtual console, an X
+ terminal emulator, an rlogin/telnet session, etc.</p>
+
+ <p>
+ The following list explains how the different programs
+ should be set up to achieve this:</p>
+
+ <p>
+ <list compact="compact">
+ <item><p>`<tt><--</tt>' generates KB_Backspace in
+ X.</p></item>
+
+ <item><p>`<tt>Delete</tt>' generates KB_Delete in X.</p></item>
+
+ <item>
+ <p>
+ X translations are set up to make KB_Backspace
+ generate ASCII DEL, and to make KB_Delete generate
+ <tt>ESC [ 3 ~</tt> (this is the vt220 escape code for
+ the `delete character' key). This must be done by
+ loading the resources using xrdb on all local X
+ displays, not using the application defaults, so that
+ the translation resources used correspond to the
+ xmodmap settings.</p></item>
+
+ <item>
+ <p>
+ The Linux console is configured to make
+ `<tt><--</tt>' generate DEL, and `Delete' generate
+ <tt>ESC [ 3 ~</tt> (this is the case at the
+ moment).</p></item>
+
+ <item><p>
+ X applications are configured so that Backspace
+ deletes left, and Delete deletes right. Motif
+ applications already work like this.</p></item>
+
+ <item><p>stty erase <tt>^?</tt> .</p></item>
+
+ <item><p>
+ The `xterm' terminfo entry should have <tt>ESC [ 3
+ ~</tt> for kdch1, just like TERM=linux and
+ TERM=vt220.</p></item>
+
+ <item><p>
+ Emacs is programmed to map KB_Backspace or the `stty
+ erase' character to delete-backward-char, and
+ KB_Delete or kdch1 to delete-forward-char, and
+ <tt>^H</tt> to help as always.</p></item>
+
+ <item><p>
+ Other applications use the `stty erase' character and
+ kdch1 for the two delete keys, with ASCII DEL being
+ `delete previous character' and kdch1 being `delete
+ character under cursor'.</p></item>
+ </list></p>
+
+ <p>
+ This will solve the problem except for:</p>
+
+ <p>
+ <list compact="compact">
+ <item><p>
+ Some terminals have a <tt><--</tt> key that cannot
+ be made to produce anything except <tt>^H</tt>. On
+ these terminals Emacs help will be unavailable on
+ <tt>^H</tt> (assuming that the `stty erase' character
+ takes precedence in Emacs, and has been set
+ correctly). M-x help or F1 (if available) can be used
+ instead.</p></item>
+
+ <item><p>
+ Some operating systems use <tt>^H</tt> for stty erase.
+ However, modern telnet versions and all rlogin
+ versions propagate stty settings, and almost all UNIX
+ versions honour stty erase. Where the stty settings
+ are not propagated correctly things can be made to
+ work by using stty manually.</p></item>
+
+ <item><p>
+ Some systems (including previous Debian versions) use
+ xmodmap to arrange for both <tt><--</tt> and Delete
+ to generate KB_Delete. We can change the behavior
+ of their X clients via the same X resources that we
+ use to do it for our own, or have our clients be
+ configured via their resources when things are the
+ other way around. On displays configured like this
+ Delete will not work, but <tt><--</tt>
+ will.</p></item>
+
+ <item><p>
+ Some operating systems have different kdch1 settings
+ in their terminfo for xterm and others. On these
+ systems the Delete key will not work correctly when
+ you log in from a system conforming to our policy, but
+ <tt><--</tt> will.</p></item>
+ </list>
+ </p>
+ </sect>
+
+
+ <sect>
+ <heading>Environment variables</heading>
+
+ <p>
+ A program must not depend on environment variables to get
+ reasonable defaults. (That's because these environment
+ variables would have to be set in a system-wide
+ configuration file like /etc/profile, which is not supported
+ by all shells.)</p>
+
+ <p>
+ If a program usually depends on environment variables for its
+ configuration, the program should be changed to fall back to
+ a reasonable default configuration if these environment
+ variables are not present. If this cannot be done easily
+ (e.g., if the source code of a non-free program is not
+ available), the program must be replaced by a small
+ `wrapper' shell script which sets the environment variables
+ if they are not already defined, and calls the original program.</p>
+
+ <p>
+ Here is an example of a wrapper script for this purpose:
+
+ <example>
+ #!/bin/sh
+ BAR=${BAR:-/var/lib/fubar}
+ export BAR
+ exec /usr/lib/foo/foo "$@"
+ </example></p>
+
+ <p>
+ Furthermore, as <tt>/etc/profile</tt> is a configuration
+ file of the <prgn>base-files</prgn> package, other packages must not
+ put any environment variables or other commands into that
+ file.</p>
+ </sect>
+ </chapt>
+ <chapt>
+ <heading>Files</heading>
+
+
+ <sect>
+ <heading>Binaries</heading>
+
+ <p>
+ Two different packages must not install programs with
+ different functionality but with the same filenames. (The
+ case of two programs having the same functionality but
+ different implementations is handled via `alternatives.')
+ If this case happens, one of the programs must 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 the generation of 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 one to generate a package with debugging
+ information included. The following makefile snippet is only
+ an example of how one may 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 "DEB_BUILD_OPTIONS=debug" 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
+ INSTALL_FILE = $(INSTALL) -p -o root -g root -m 644
+ INSTALL_PROGRAM = $(INSTALL) -p -o root -g root -m 755
+ INSTALL_SCRIPT = $(INSTALL) -p -o root -g root -m 755
+ INSTALL_DIR = $(INSTALL) -p -d -o root -g root -m 755
+
+ ifneq (,$(findstring debug,$(DEB_BUILD_OPTIONS)))
+ CFLAGS += -g
+ endif
+ ifeq (,$(findstring nostrip,$(DEB_BUILD_OPTIONS)))
+ INSTALL_PROGRAM += -s
+ endif
+ </example>
+
+ Please note that the above example is merely informative,
+ and is not a policy mandate. You may have to massage this
+ example in order to make it work for your package.
+
+ </p>
+
+ <p>
+ It is up to the package maintainer to decide what
+ compilation options are best for the package. Certain
+ binaries (such as computationally-intensive programs) will
+ function better with certain flags (<tt>-O3</tt>, for
+ example); feel free to use them. Please use good judgment
+ here. Don't use flags for the sake of it; only use them
+ if there is good reason to do so. Feel free to override
+ the upstream author's ideas about which compilation
+ options are best--they are often inappropriate for our
+ environment.</p></sect>
+
+
+ <sect>
+ <heading>Libraries</heading>
+
+ <p>
+ All libraries must have a shared version in the lib
+ package and a static version in the lib-dev package. The
+ shared version must be compiled with <tt>-fPIC</tt>, and
+ the static version must not be. In other words, each
+ <tt>*.c</tt> file will need to be compiled twice.</p>
+
+ <p>
+ You must specify the gcc option <tt>-D_REENTRANT</tt>
+ when building a library (either static or shared) to make
+ the library compatible with LinuxThreads.</p>
+
+ <p>
+ Note that all installed shared libraries should be
+ stripped with
+ <example>
+ strip --strip-unneeded <your-lib>
+ </example>
+ (The option `--strip-unneeded' makes <tt>strip</tt> remove
+ only the symbols which aren't needed for relocation
+ processing.) Shared libraries can function perfectly well
+ when stripped, since the symbols for dynamic linking are
+ in a separate part of the ELF object file.</p>
+
+ <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>
+ 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 should
+ 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>
+ You must make sure that you use only released versions of
+ shared libraries to build your packages; otherwise other
+ users will not be able to run your binaries
+ properly. Producing source packages that depend on
+ unreleased compilers is also usually a bad
+ idea.
+ </p>
+ </sect>
+
+
+ <sect>
+ <heading>Shared libraries</heading>
+
+ <p>
+ Packages involving shared libraries should be split up
+ into several binary packages.</p>
+
+ <p>
+ For a straightforward library which has a development
+ environment and a runtime kit including just shared
+ libraries you need to create two packages:
+ <tt><var>libraryname</var><var>soname</var></tt>
+ (<var>soname</var> is the shared object name of the shared
+ library--it's the thing that has to match exactly between
+ building an executable and running it for the dynamic
+ linker to be able run the program; usually the
+ <var>soname</var> is the major number of the library) and
+ <tt><var>libraryname</var><var>soname</var>-dev</tt>.</p>
+
+ <p>
+ If you prefer only to support one development version at a
+ time you may name the development package
+ <tt><var>libraryname</var>-dev</tt>; otherwise you may
+ wish to use <prgn>dpkg</prgn>'s conflicts mechanism to
+ ensure that the user only installs one development version
+ at a time (after all, different development versions are
+ likely to have the same header files in them, causing a
+ filename clash if both are installed). Typically the
+ development version should also have an exact version
+ dependency on the runtime library, to make sure that
+ compilation and linking happens correctly.</p>
+
+ <p>
+ Packages which use the shared library should have a
+ dependency on the name of the shared library package,
+ <tt><var>libraryname</var><var>soname</var></tt>. When
+ the <var>soname</var> changes you can have both versions
+ of the library installed while moving from the old library
+ to the new.</p>
+
+ <p>
+ If your package has some run-time support programs which
+ use the shared library you must not put them in
+ the shared library package. If you do that then you won't
+ be able to install several versions of the shared library
+ without getting filename clashes. Instead, either create
+ a third package for the runtime binaries (this package
+ might typically be named
+ <tt><var>libraryname</var>-runtime</tt>--note the absence
+ of the <var>soname</var> in the package name) or if the
+ development package is small include them in there.</p>
+
+ <p>
+ If you have several shared libraries built from the same
+ source tree you may lump them all together into a single
+ shared library package, provided that you change all their
+ <var>soname</var>s at once (so that you don't get filename
+ clashes if you try to install different versions of the
+ combined shared libraries package).</p>
+
+ <p>
+ You should follow the directions in the <em>Debian Packaging
+ Manual</em> for putting the shared library in its package,
+ and you must include a <tt>shlibs</tt> control area
+ file with details of the dependencies for packages which
+ use the library.</p>
+
+ <p>
+ Shared libraries should not be installed
+ executable, since <prgn>ld.so</prgn> does not require this
+ and trying to execute a shared library results in a core
+ dump.</p></sect>
+
+
+ <sect id="scripts">
+ <heading>Scripts</heading>
+
+ <p>
+ All command scripts, including the package maintainer
+ scripts inside the package and used by <prgn>dpkg</prgn>,
+ should have a <tt>#!</tt> line naming the shell to be used
+ to interpret them.</p>
+
+ <p>
+ In the case of Perl scripts this should be
+ <tt>#!/usr/bin/perl</tt>.</p>
+
+ <p>
+ Shell scripts (<prgn>sh</prgn> and <prgn>bash</prgn>)
+ should almost certainly start with <tt>set -e</tt> so that
+ errors are detected. Every script should use
+ <tt>set -e</tt> or check the exit status of <em>every</em>
+ command.</p>
+
+ <p>
+ The standard shell interpreter `<tt>/bin/sh</tt>' can be a
+ symbolic link to any POSIX compatible shell, if <tt>echo
+ -n</tt> does not generate a newline.
+ <footnote>
+ <p>
+ Debian policy specifies POSIX behavior for /bin/sh, but
+ echo -n has widespread use in the Linux community
+ (including especially debian policy, the linux kernel
+ source, many debian scripts, etc.). This echo -n
+ mechanism is valid but not required under POSIX, hence
+ this explicit addition. Also, rumour has it that this
+ shall be mandated under the LSB anyway.
+ </p>
+ </footnote>
+ Thus, shell scripts
+ specifying `<tt>/bin/sh</tt>' as interpreter should only
+ use POSIX features. If a script requires non-POSIX
+ features from the shell interpreter, the appropriate shell
+ must be specified in the first line of the script (e.g.,
+ `<tt>#!/bin/bash</tt>') and the package must depend on the
+ package providing the shell (unless the shell package is
+ marked `Essential', e.g., in the case of
+ <prgn>bash</prgn>).
+ </p>
+
+ <p>
+ You may wish to restrict your script to POSIX features when possible so
+ that it may use <tt>/bin/sh</tt> as its interpreter. If
+ your script works with <prgn>ash</prgn>, it's probably
+ POSIX compliant, but if you are in doubt, use
+ <tt>/bin/bash</tt>.</p>
+
+ <p>
+ Perl scripts should check for errors when making any
+ system calls, including <tt>open</tt>, <tt>print</tt>,
+ <tt>close</tt>, <tt>rename</tt> and <tt>system</tt>.</p>
+
+ <p>
+ <prgn>csh</prgn> and <prgn>tcsh</prgn> should be avoided
+ as scripting languages. See <em>Csh Programming
+ Considered Harmful</em>, one of the <tt>comp.unix.*</tt>
+ FAQs. 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-writeable
+ directories (e.g., in <tt>/tmp</tt>) must use a
+ mechanism which will fail if a file with the same name
+ already exists.</p>
+
+ <p>
+ The Debian base distribution provides the
+ <prgn>tempfile</prgn> and <prgn>mktemp</prgn> utilities
+ for use by scripts for this purpose.</p></sect>
+
+
+ <sect>
+ <heading>Symbolic links</heading>
+
+ <p>
+ In general, symbolic links within a top-level directory
+ should be relative, and symbolic links pointing from one
+ top-level directory into another should be absolute. (A
+ top-level directory is a sub-directory of the root
+ directory `/'.)</p>
+
+ <p>
+ In addition, symbolic links should be specified as short
+ as possible, i.e., link targets like `foo/../bar' are
+ deprecated.</p>
+
+ <p>
+ Note that when creating a relative link using
+ <prgn>ln</prgn> it is not necessary for the target of the
+ link to exist relative to the working directory you're
+ running <prgn>ln</prgn> from; nor is it necessary to
+ change directory to the directory where the link is to be
+ made. Simply include the string that should appear as the
+ target of the link (this will be a pathname relative to
+ the directory in which the link resides) as the first
+ argument to <prgn>ln</prgn>.</p>
+
+ <p>
+ For example, in your <prgn>Makefile</prgn> or
+ <tt>debian/rules</tt>, do things like:
+ <example>
+ ln -fs gcc $(prefix)/bin/cc
+ ln -fs gcc debian/tmp/usr/bin/cc
+ ln -fs ../sbin/sendmail $(prefix)/bin/runq
+ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
+ </example></p>
+
+ <p>
+ A symbolic link pointing to a compressed file should
+ always have the same file extension as the referenced
+ file. (For example, if a file `<tt>foo.gz</tt>' is
+ referenced by a symbolic link, the filename of the link
+ has to end with `<tt>.gz</tt>' too, as in
+ `bar.gz.')</p></sect>
+
+
+ <sect>
+ <heading>Device files</heading>
+
+ <p>
+ Packages must not include device files in the package file
+ tree.</p>
+
+ <p>
+ If a package needs any special device files that are not
+ included in the base system, it must call
+ <prgn>MAKEDEV</prgn> in the <tt>postinst</tt> script,
+ after asking the user for permission to do so.</p>
+
+ <p>
+ Packages must not remove any device files in the
+ <tt>postrm</tt> or any other script. This is left to the
+ system administrator.</p>
+
+ <p>
+ Debian uses the serial devices
+ <tt>/dev/ttyS*</tt>. Programs using the old
+ <tt>/dev/cu*</tt> devices should be changed to use
+ <tt>/dev/ttyS*</tt>.</p>
+ </sect>
+
+ <sect id="config files">
+ <heading>Configuration files</heading>
+ <sect1>
+ <heading>Definitions</heading>
+ <p>
+ <taglist>
+ <tag>configuration file</tag>
+ <item><p>
+ A file that affects the operation of 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
+ must 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>
+ If your package 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 must 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 only if it is possible to distribute a default
+ version that will work for most installations, although
+ some system administrators may choose to modify it. This
+ implies that the default version will be part of the
+ package distribution, and must not be modified by the
+ maintainer scripts during installation (or at any other
+ time).
+ </p>
+
+ <p>
+ In order to ensure that local changes are preserved
+ correctly, no package may contain or make hard links to
+ conffiles.
+ <footnote>
+ <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 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 are not required to configure every possible option for
+ the package, but only those necessary to get the package
+ running on a given system. Ideally the sysadmin should not
+ have to do any configuration other than that done
+ (semi-)automatically by the <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 must
+ not be mixed, for that way lies madness:
+ <prgn>dpkg</prgn> will ask about overwriting the file
+ every time the package is upgraded.</p>
+
+ </sect1>
+
+ <sect1>
+ <heading>Sharing configuration files</heading>
+ <p>
+ Packages which specify the same file as
+ `<tt>conffile</tt>' must be tagged as <em>conflicting</em>
+ with each other.
+ </p>
+
+ <p>
+ The maintainer scripts must not alter the conffile of
+ <em>any</em> package, including the one the scripts belong
+ to.</p>
+
+ <p>
+ If two or more packages use the same configuration file
+ and it is reasonable for both to be installed at the same
+ time, one of these packages must be defined as
+ <em>owner</em> of the configuration file, i.e., it will be
+ the package to list that distributes the file and lists it
+ as a <tt>conffile</tt>. Other packages that use the
+ configuration file must depend on the owning package if
+ they require the configuration file to operate. If the
+ other package will use the configuration file if present,
+ but is capable of operating without it, no dependency need
+ be declared.</p>
+
+ <p>
+ If it is desirable for two or more related packages to
+ share a configuration file <em>and</em> for all of the
+ related packages to be able to modify that configuration
+ file, then the following should be done:
+ <enumlist>
+ <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
+ 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
+ may 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>
+ </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
+ log files, or need a separate directory for permissions
+ reasons (<tt>/var/log</tt> is writable only by
+ <tt>root</tt>), you should usually create a directory named
+ <tt>/var/log/<var>package</var></tt>.</p>
+
+ <p>
+ Log files must be rotated occasionally so
+ that they don't grow indefinitely; the best way to do this
+ 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>
+ /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>
+ Log files should be removed when the package is
+ purged (but not when it is only removed), by checking the
+ argument to the <tt>postrm</tt> script (see the <em>Debian
+ Packaging Manual</em> for details).</p>
+ </sect>
+
+
+ <sect>
+ <heading>Permissions and owners</heading>
+
+ <p>
+ The rules in this section are guidelines for general use.
+ If necessary you may deviate from the details below.
+ However, if you do so you must make sure that what is done
+ is secure and you should try to be as consistent as possible
+ with the rest of the system. You should probably also
+ discuss it on <prgn>debian-devel</prgn> first.</p>
+
+ <p>
+ Files should be owned by <tt>root.root</tt>, and made
+ writable only by the owner and universally readable (and
+ executable, if appropriate).</p>
+
+ <p>
+ Directories should be mode 755 or (for group-writability)
+ mode 2775. The ownership of the directory should be
+ consistent with its mode--if a directory is mode 2775, it
+ should be owned by the group that needs write access to
+ it.</p>
+
+ <p>
+ Setuid and setgid executables should be mode 4755 or 2755
+ respectively, and owned by the appropriate user or group.
+ They should not be made unreadable (modes like 4711 or
+ 2711 or even 4111); doing so achieves no extra security,
+ because anyone can find the binary in the freely available
+ Debian package--it is merely inconvenient. For the same
+ reason you should not restrict read or execute permissions
+ on non-set-id executables.</p>
+
+ <p>
+ Some setuid programs need to be restricted to particular
+ sets of users, using file permissions. In this case they
+ should be owned by the uid to which they are set-id, and
+ by the group which should be allowed to execute them.
+ They should have mode 4754; there is no point in making
+ them unreadable to those users who must not be allowed to
+ execute them.</p>
+
+ <p>
+ You must not arrange that the system administrator can only
+ reconfigure the package to correspond to their local
+ security policy by changing the permissions on a binary.
+ Ordinary files installed by <prgn>dpkg</prgn> (as opposed
+ to conffiles and other similar objects) have their
+ permissions reset to the distributed permissions when the
+ package is reinstalled. Instead you should consider (for
+ example) creating a group for people allowed to use the
+ program(s) and making any setuid executables executable
+ only by that group.</p>
+
+ <p>
+ If you need to create a new user or group for your package
+ there are two possibilities. Firstly, you may need to
+ make some files in the binary package be owned by this
+ user or group, or you may need to compile the user or
+ group id (rather than just the name) into the binary
+ (though this latter should be avoided if possible, as in
+ this case you need a statically allocated id).</p>
+
+ <p>
+ If you need a statically allocated id, you must ask for a
+ user or group id from the base system
+ maintainer, and must not release the package until you
+ have been allocated one. Once you have been allocated one
+ you must make the package depend on a version of the base
+ system with the id present in <tt>/etc/passwd</tt> or
+ <tt>/etc/group</tt>, or alternatively arrange for your
+ package to create the user or group itself with the
+ correct id (using <tt>adduser</tt>) in its pre- or
+ post-installation script (the latter is to be preferred if
+ it is possible).</p>
+
+ <p>
+ On the other hand, the program might be able to determine the
+ uid or gid from the group name at runtime, so that a
+ dynamic id can be used. In this case you should choose an
+ appropriate user or group name, discussing this on
+ <prgn>debian-devel</prgn> and checking with the base
+ system maintainer that it is unique and that they do not
+ wish you to use a statically allocated id instead. When
+ this has been checked you must arrange for your package to
+ create the user or group if necessary using
+ <prgn>adduser</prgn> in the pre- or post-installation
+ script (again, the latter is to be preferred if it is
+ possible).</p>
+
+ <p>
+ Note that changing the numeric value of an id associated with a name
+ is very difficult, and involves searching the file system for all
+ appropriate files. You need to think carefully whether a static or
+ dynamic id is required, since changing your mind later will cause
+ problems.</p>
+ </sect>
+ </chapt>
+
+ <chapt>
+ <heading>Customized programs</heading>
+
+ <sect id="arch-spec">
+ <heading>Architecture specification strings</heading>
+
+ <p>
+ If a program needs to specify an <em>architecture specification
+ string</em> in some place, the following format should be used:
+ <example>
+ <arch>-<os>
+ </example>
+ where `<arch>' is one of the following: i386, alpha, arm, m68k,
+ powerpc, sparc and `<os>' is one of: linux, gnu. Use
+ of <em>gnu</em> in this string is reserved for the GNU/Hurd
+ operating system.</p>
+ <p>
+ Note, that we don't want to use `<arch>-debian-linux'
+ to apply to the rule `architecture-vendor-os' since this
+ would make our programs incompatible to other Linux
+ distributions. Also note, that we don't use
+ `<arch>-unknown-linux', since the `unknown' does not
+ look very good.</p></sect>
+
+
+ <sect>
+ <heading>Daemons</heading>
+
+ <p>
+ The configuration files <tt>/etc/services</tt>,
+ <tt>/etc/protocols</tt>, and <tt>/etc/rpc</tt> are managed
+ by the <prgn>netbase</prgn> package and may not be modified
+ by other packages.</p>
+
+ <p>
+ If a package requires a new entry in one of these files, the
+ maintainer should get in contact with the
+ <prgn>netbase</prgn> maintainer, who will add the entries
+ and release a new version of the <prgn>netbase</prgn>
+ package.</p>
+
+ <p>
+ The configuration file <tt>/etc/inetd.conf</tt> must not be
+ modified by the package's scripts except via the
+ <prgn>update-inetd</prgn> script or the
+ <prgn>DebianNet.pm</prgn> Perl module.</p>
+
+ <p>
+ If a package wants to install an example entry into
+ <tt>/etc/inetd.conf</tt>, the entry must be preceded with
+ exactly one hash character (<tt>#</tt>). Such lines are
+ treated as `commented out by user' by the
+ <prgn>update-inetd</prgn> script and are not changed or
+ activated during 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 setgid utmp.
+ </p>
+ </sect>
+
+ <sect>
+ <heading>Editors and pagers</heading>
+
+ <p>
+ Some programs have the ability to launch an editor or pager
+ program to edit or display a text document. Since there are
+ lots of different editors and pagers available in the Debian
+ distribution, the system administrator and each user should
+ have the possibility to choose his/her preferred editor and
+ pager.</p>
+
+ <p>
+ In addition, every program should choose a good default
+ editor/pager if none is selected by the user or system
+ administrator.</p>
+
+ <p>
+ Thus, every program that launches an editor or pager must
+ 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 <tt>/usr/bin/editor</tt>
+ and <tt>/usr/bin/pager</tt> should be used, respectively.</p>
+
+ <p>
+ These two files are managed through `alternatives.' That is,
+ every package providing an editor or pager must call the
+ <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 variables, that program may be configured
+ 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
+ launch the appropriate program or fall back to
+ <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>
+ It is not required for a package to depend on
+ `editor' and `pager', nor is it required for a package to
+ provide such virtual packages.
+ <footnote>
+ <p>
+ The Debian base system already provides an editor and
+ a pager program,
+ </p>
+ </footnote>
+ </p>
+
+ </sect>
+
+
+ <sect id="web-appl">
+ <heading>Web servers and applications</heading>
+
+ <p>
+ This section describes the locations and URLs that should
+ be used by all web servers and web application in the Debian
+ system.</p>
+
+ <p>
+ <enumlist>
+ <item>
+ <p>Cgi-bin executable files are installed in the
+ directory
+ <example>
+ /usr/lib/cgi-bin/<cgi-bin-name>
+ </example>
+ and should be referred to as
+ <example>
+ http://localhost/cgi-bin/<cgi-bin-name>
+ </example></p></item>
+
+
+ <item><p>Access to html documents</p>
+
+ <p>
+ Html documents for a package are stored in
+ <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>
+
+
+ <item><p>Web Document Root</p>
+
+ <p>
+ Web Applications should try to avoid storing files in
+ the Web Document Root. Instead they should use the
+ /usr/share/doc/<package> directory for documents and
+ register the Web Application via the menu package. If
+ access to the web-root is unavoidable then use
+ <example>
+ /var/www
+ </example>
+ as the Document Root. This might be just a
+ symbolic link to the location where the sysadmin has
+ put the real document root.</p>
+ </item>
+
+ </enumlist></p></sect>
+
+
+ <sect>
+ <heading>Mail transport, delivery and user agents</heading>
+
+ <p>
+ Debian packages which process electronic mail, whether
+ mail-user-agents (MUAs) or mail-transport-agents (MTAs),
+ must make sure that they are compatible with the
+ configuration decisions below. Failure to do this may
+ result in lost mail, broken <tt>From:</tt> lines, and other
+ serious brain damage!</p>
+
+ <p>
+ The 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 FHS). The mail spool is part of the base system
+ and not part of the MTA package.</p>
+
+ <p>
+ All Debian MUAs, MTAs, MDAs and other mailbox accessing
+ programs (like IMAP daemons) must lock the mailbox in an
+ NFS-safe way. This means that <tt>fcntl()</tt> locking must
+ be combined with dot locking. To avoid deadlocks, a
+ program should use <tt>fcntl()</tt> first and dot locking
+ after this or alternatively implement the two locking
+ methods in a non blocking way<footnote>
+ <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
+ mailbox (unless it has nonstandard permissions) in which
+ case the MTA or another MUA must recreate it if needed.
+ Mailboxes must be writable by group mail.</p>
+
+ <p>
+ The mail spool is 2775 <tt>root.mail</tt>, and MUAs should
+ be setgid mail to do the locking mentioned above (and
+ must obviously avoid accessing other users' mailboxes
+ using this privilege).</p>
+
+ <p>
+ <tt>/etc/aliases</tt> is the source file for the system mail
+ aliases (e.g., postmaster, usenet, etc.)--it is the one
+ which the sysadmin and <tt>postinst</tt> scripts may edit.
+ After <tt>/etc/aliases</tt> is edited the program or human
+ editing it must call <prgn>newaliases</prgn>. All MTA
+ packages must come with a <prgn>newaliases</prgn> program,
+ even if it does nothing, but older MTA packages do not do
+ this so programs should not fail if <prgn>newaliases</prgn>
+ cannot be found.</p>
+
+ <p>
+ The convention of writing <tt>forward to
+ <var>address</var></tt> in the mailbox itself is not
+ supported. Use a <tt>.forward</tt> file instead.</p>
+
+ <p>
+ The <prgn>rmail</prgn> program used by UUCP
+ for incoming mail should be <tt>/usr/sbin/rmail</tt>.
+ Likewise, <prgn>rsmtp</prgn>, for receiving
+ batch-SMTP-over-UUCP, should be <tt>/usr/sbin/rsmtp</tt> if it
+ is supported.</p>
+
+ <p>
+ If you need to know what name to use (for example) on
+ outgoing news and mail messages which are generated locally,
+ you should use the file <tt>/etc/mailname</tt>. It will
+ contain the portion after the username and <tt>@</tt> (at)
+ sign for email addresses of users on the machine (followed
+ by a newline).</p>
+
+ <p>
+ A package should check for the existence of this file. If
+ it exists it should use it without comment. (An MTA's
+ prompting configuration script may wish to prompt the user
+ even if it finds this file exists.) If it does not exist it
+ should prompt the user for the value and store it in
+ <tt>/etc/mailname</tt> as well as using it in the package's
+ configuration. The prompt should make it clear that the
+ name will not just be used by that package. For example, in
+ this situation the INN package says:
+ <example>
+ Please enter the `mail name' of your system. This is the
+ hostname portion of the address to be shown on outgoing
+ news and mail messages. The default is
+ <var>syshostname</var>, your system's host name. Mail
+ name [`<var>syshostname</var>']:
+ </example>
+ where <var>syshostname</var> is the output of <tt>hostname
+ --fqdn</tt>.</p></sect>
+
+
+ <sect>
+ <heading>News system configuration</heading>
+
+ <p>
+ All the configuration files related to the NNTP (news)
+ servers and clients should be located under
+ <tt>/etc/news</tt>.</p>
+
+ <p>
+ There are some configuration issues that apply to a number
+ of news clients and server packages on the machine. These
+ are:
+
+ <taglist>
+ <tag>/etc/news/organization</tag>
+ <item><p>A string which should appear as the
+ organization header for all messages posted
+ by NNTP clients on the machine</p></item>
+
+ <tag>/etc/news/server</tag>
+ <item><p>Contains the FQDN of the upstream NNTP
+ server, or localhost if the local machine is
+ an NNTP server.</p></item>
+ </taglist>
+
+ Other global files may be added as required for cross-package news
+ configuration.</p></sect>
+
+
+ <sect>
+ <heading>Programs for the X Window System</heading>
+
+ <p>
+ <em>Programs that may be configured with support for the X Window
+ System</em> must be configured to do so and must declare any
+ package dependencies necessary to satisfy their runtime
+ requirements when using the X Window System, unless the package
+ in question is of standard or higher priority, in which case
+ X-specific binaries may be split into a separate package, or
+ alternative versions of the package with X support may be
+ provided.
+ </p>
+
+
+ <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>
+ This implements current practice, and provides 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>xutils</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>xutils</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>xutils (>=
+ 4.0.2)</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>xutils
+ (>= 4.0.2)</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>/etc/X11/app-defaults/</tt> (use of a
+ localized subdirectory of <tt>/etc/X11/</tt> as described in
+ the <em>X Toolkit Intrinsics - C Language Interface</em>
+ manual is also permitted). They must be registered as
+ <em>conffile</em>s or handled as configuration files. For
+ programs that are not linked against the X Toolkit (Xt)
+ library, customization of programs' X resources may also be
+ supported with the provision of a file with the same name as
+ that of the package placed in the
+ <tt>/etc/X11/Xresources/</tt> directory, which must
+ registered as a <em>conffile</em> or handled as a
+ configuration file. <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> file which
+ had been customized by the system administrator.
+ </p>
+
+ <p>
+ <em>Packages using the X Window System should abide by the FHS
+ standard whenever possible</em>; they should install binaries,
+ libraries, manual pages, and other files in FHS-mandated
+ locations wherever possible. This means that files must
+ not be installed into <tt>/usr/X11R6/bin/</tt>,
+ <tt>/usr/X11R6/lib/</tt>, or <tt>/usr/X11R6/man/</tt> unless
+ this is necessary for the package to operate properly.
+ Configuration files for window managers and display managers
+ should be placed in a subdirectory of <tt>/etc/X11/</tt>
+ corresponding to the package name due to these programs'
+ tight integration with the mechanisms of the X Window
+ System. Application-level programs should use the
+ <tt>/etc/</tt> directory unless otherwise mandated by
+ policy. The installation of files into subdirectories of
+ <tt>/usr/X11R6/include/X11/</tt> and
+ <tt>/usr/X11R6/lib/X11/</tt> is permitted but discouraged;
+ package maintainers should determine if subdirectories of
+ <tt>/usr/lib/</tt> and <tt>/usr/share/</tt> can be used
+ instead (symlinks from the X11R6 directories to
+ FHS-compliant locations is encouraged if the program is not
+ easily configured to look elsewhere for its files).
+ Packages must not provide -- or install files into -- the
+ directories <tt>/usr/bin/X11/</tt>,
+ <tt>/usr/include/X11/</tt>, or <tt>/usr/lib/X11/</tt>.
+ Files within a package should, however, make reference to
+ these directories, rather than their X11R6-named
+ counterparts <tt>/usr/X11R6/bin/</tt>,
+ <tt>/usr/X11R6/include/X11/</tt>, and
+ <tt>/usr/X11R6/lib/X11/</tt>, if the resources being
+ referred to have not been moved to FHS-compliant locations.
+ </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>Emacs lisp programs</heading>
+
+ <p>
+ Please refer to the `Debian Emacs Policy' (documented in
+ <tt>debian-emacs-policy.gz</tt> of the
+ <prgn>emacsen-common</prgn> package) for details of how to
+ package emacs lisp programs.</p></sect>
+
+
+ <sect>
+ <heading>Games</heading>
+
+ <p>
+ The permissions on /var/games are 755
+ <tt>root.root</tt>.</p>
+
+ <p>
+ Each game decides on its own security policy.</p>
+
+ <p>
+ Games which require protected, privileged access to
+ high-score files, savegames, etc., may be made
+ set-<em>group</em>-id (mode 2755) and owned by
+ <tt>root.games</tt>, and use files and directories with
+ appropriate permissions (770 <tt>root.games</tt>, for
+ example). They must not be made
+ set-<em>user</em>-id, as this causes security problems. (If
+ an attacker can subvert any set-user-id game they can
+ overwrite the executable of any other, causing other players
+ of these games to run a Trojan horse program. With a
+ set-group-id game the attacker only gets access to less
+ important game data, and if they can get at the other
+ players' accounts at all it will take considerably more
+ effort.)</p>
+
+ <p>
+ Some packages, for example some fortune cookie programs, are
+ configured by the upstream authors to install with their
+ data files or other static information made unreadable so
+ that they can only be accessed through set-id programs
+ provided. You should not do this in a Debian package: anyone can
+ download the <tt>.deb</tt> file and read the data from it,
+ so there is no point making the files unreadable. Not
+ making the files unreadable also means that you don't have
+ to make so many programs set-id, which reduces the risk of a
+ security hole.</p>
+
+ <p>
+ 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
+ for games (X and non-X games) should be installed in
+ <tt>/usr/share/man/man6</tt>.</p>
+ </sect>
+ </chapt>
+
+ <chapt><heading>Documentation</heading>
+
+
+ <sect>
+ <heading>Manual pages</heading>
+
+ <p>
+ You should install manual pages in <prgn>nroff</prgn> source
+ 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 not install a preformatted `cat
+ page'.</p>
+
+ <p>
+ Each program, utility, and function should have an
+ associated manpage included in the same package. It is
+ suggested that all configuration files also have a manual
+ page included as well.
+ </p>
+
+ <p>
+ If no manual page is available for a particular program,
+ utility, function or configuration file and this is reported as a bug on
+ debian-bugs, a symbolic link from the requested manual page
+ to the <manref name="undocumented" section="7"> manual page
+ may be provided. This symbolic link can be created from
+ <tt>debian/rules</tt> like this:
+ <example>
+ ln -s ../man7/undocumented.7.gz \
+ debian/tmp/usr/share/man/man[1-9]/the_requested_manpage.[1-9].gz
+ </example>
+ 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
+ (you can report it yourself, if you like). Do not close the
+ bug report until a proper manpage is available.</p>
+
+ <p>
+ You may forward a complaint about a missing manpage to the
+ upstream authors, and mark the bug as forwarded in the
+ Debian bug tracking system. Even though the GNU Project do
+ not in general consider the lack of a manpage to be a bug,
+ we do--if they tell you that they don't consider it a bug
+ you should leave the bug in our bug tracking system open
+ anyway.</p>
+
+ <p>
+ Manual pages should be installed compressed using <tt>gzip
+ -9</tt>.</p>
+
+ <p>
+ If one manpage needs to be accessible via several names it
+ is better to use a symbolic link than the <tt>.so</tt>
+ feature, but there is no need to fiddle with the relevant
+ parts of the upstream source to change from <tt>.so</tt> to
+ symlinks--don't do it unless it's easy. You should not create hard
+ links in the manual page directories, nor put
+ absolute filenames in <tt>.so</tt> directives. The filename
+ in a <tt>.so</tt> in a manpage should be relative to the
+ base of the manpage tree (usually
+ <tt>/usr/share/man</tt>).</p></sect>
+
+
+ <sect>
+ <heading>Info documents</heading>
+
+ <p>
+ Info documents should be installed in <tt>/usr/share/info</tt>.
+ They should be compressed with <tt>gzip -9</tt>.</p>
+
+ <p>
+ Your package should call <prgn>install-info</prgn> to update the Info
+ <tt>dir</tt>
+ file, in its post-installation script:
+ <example>
+ install-info --quiet --section Development Development \
+ /usr/share/info/foobar.info
+ </example></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/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
+ to match (case-insensitively) against an existing section,
+ the second is used when creating a new one.</p>
+
+ <p>
+ You should remove the entries in the pre-removal script:
+ <example>
+ install-info --quiet --remove /usr/share/info/foobar.info
+ </example></p>
+
+ <p>
+ If <prgn>install-info</prgn> cannot find a description entry
+ in the Info file you must supply one. See <manref
+ name="install-info" section="8"> for details.</p>
+ </sect>
+
+ <sect>
+ <heading>Additional documentation</heading>
+
+ <p>
+ Any additional documentation that comes with the package may
+ be installed at the discretion of the package maintainer.
+ Text documentation should be installed in a directory
+ <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>
+ If a package comes with large amounts of documentation which
+ many users of the package will not require you should create
+ a separate binary package to contain it, so that it does not
+ take up disk space on the machines of users who do not need
+ or want it installed.</p>
+
+ <p>
+ 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/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>
+
+ <p>
+ Files in <tt>/usr/share/doc</tt> should not be referenced by
+ any program, and the system administrator should be able to
+ delete them without causing any programs to break. Any files
+ that are referenced by programs but are also useful as
+ standalone documentation should be installed under
+ <tt>/usr/share/<package>/</tt> and symlinked in
+ <tt>/usr/share/doc/<package>/</tt>.
+ </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>
+ The unification of Debian documentation is being carried out
+ via HTML.</p>
+
+ <p>
+ If your package comes with extensive documentation in a
+ 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/share/doc/<var>appropriate package</var></tt> or its
+ subdirectories.
+ <footnote>
+ <p>The rationale: The important thing here is that HTML
+ docs should be available in <em>some</em> package, not
+ necessarily in the main binary package, though. </p>
+ </footnote>
+ </p>
+
+ <p>
+ Other formats such as PostScript may be provided at your
+ option.</p>
+ </sect>
+
+ <sect id="copyrightfile">
+ <heading>Copyright information</heading>
+
+ <p>
+ Every package must be accompanied by a verbatim copy of its
+ copyright and distribution license in the file
+ /usr/share/doc/<package-name>/copyright. This file must
+ neither be compressed nor be a symbolic link.</p>
+
+ <p>
+ In addition, the copyright file must say where the upstream
+ sources (if any) were obtained, and should explain briefly what
+ modifications were made in the Debian version of the package
+ compared to the upstream one. It should name the original
+ authors of the package and the Debian maintainer(s) who were
+ involved with its creation.</p>
+
+ <p>
+ A copy of the file which will be installed in
+ <tt>/usr/share/doc/<var>package</var>/copyright</tt> should be
+ in <tt>debian/copyright</tt>.</p>
+
+
+ <p>
+ /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
+ means.</p>
+
+ <p>
+ Packages distributed under the UCB BSD license, the Artistic
+ license, the GNU GPL, and the GNU LGPL should refer to the
+ 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>
+ You should 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/share/doc/<var>package</var>/README</tt> or
+ <tt>README.Debian</tt> or some other appropriate place.</p>
+ </sect>
+
+ <sect>
+ <heading>Examples</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. 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">
+ <heading>Changelog files</heading>
+
+ <p>
+ Packages that are not Debian-native must contain a copy of
+ <tt>debian/changelog</tt> file from the Debian source tree
+ in <tt>/usr/share/doc/<var>package</var></tt> as
+ <tt>changelog.Debian.gz</tt>. If an upstream changelog is
+ available, it should be accessible as
+ <tt>/usr/share/doc/<var>package</var>/changelog.gz</tt> in
+ plain text. If the upstream changelog is distributed in
+ HTML, it should be made available in that form as
+ <tt>/usr/share/doc/<var>package</var>/changelog.html.gz</tt>
+ and the <tt>changelog.gz</tt> should be generated using, eg,
+ <tt>lynx -dump -nolist</tt>. If the upstream changelog files
+ do not already conform to this naming convention, then this
+ may be achieved either by renaming the files, or adding a
+ symbolic link, at the maintainer's discretion.
+ <footnote>
+ <p>
+ Rationale: People should not have to look into two
+ places for upstream changelogs merely because they are
+ in HTML format.
+ </p>
+ </footnote>
+ </p>
+
+
+ <p>
+ All these files should be installed compressed using <tt>gzip -9</tt>,
+ as they will become large with time even if they start out
+ small.
+ </p>
+
+ <p>
+ If the package has only one changelog which is used both as
+ the Debian changelog and the upstream one because there is
+ no separate upstream maintainer then that changelog should
+ usually be installed as
+ <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>
+ </chapt>
+ </book>
+</debiandoc>
projects / debian / debian-policy.git / blobdiff