path: root/doc/guidelines.info-1

This is Info file guidelines.info, produced by Makeinfo-1.63 from the
input file ./guidelines.texi.

START-INFO-DIR-ENTRY
* Guidelines: (guidelines).       How to make Debian packages.
END-INFO-DIR-ENTRY


File: guidelines.info,  Node: Top,  Next: Additional Information,  Prev: (dir),  Up: (dir)

Debian GNU/Linux Packaging Guidelines
*************************************

   This file documents the steps that must be taken in the preparation
of a Debian GNU/Linux package.  All submissions to be included in the
distribution proper and all packages to be considered for `contrib' or
`non-free' availability *must* conform to the guidelines and standards
described in this document or they cannot be included or made available
at the archive with the distribution.

   Please read the Guidelines carefully.  If you have comments or
questions, please contact `debian-devel@pixar.com'.  If you are
planning on going further than just contributing a package (i.e., if
you plan to maintain it for an extended period of time or if you are
generally interested in becoming more involved in the Project), you
should join the `debian-devel' mailing list.  For more details, read
`info/mailing-lists.txt', available at any Debian GNU/Linux archive.

   (This file was last updated on 26th January 1996.  Please check the
most recent `dpkg' package at any Debian GNU/Linux archive for a
potentially more up to date copy.)

* Menu:

* Additional Information::      Where other info is to be found.
* Package Copyright::           A few words about the importance of
                                understanding the package copyright.
* Package Content::             Requirements for the package content.
* Source Package::              Creating the source package.
* Binary Package::              Creating the binary package.
* Control Files::               The binary package control files.
* Appendix::                    More specific details about some aspects.


File: guidelines.info,  Node: Additional Information,  Next: Package Copyright,  Prev: Top,  Up: Top

Additional Information
**********************

   These Guidelines are intended to be fairly general.  More specific
information is available about certain aspects of building packages,
such as how to use the features of Init under Debian GNU/Linux and how
to interact with some more technical details of dpkg's operation.  This
information can be found in the directory `doc/package-developer' at
any Debian GNU/Linux archive.  At the time of this writing, the
following documents are available:

`virtual-package-names-list.text'
     The list of virtual package names currently in use, together with
     the procedure for getting new virtual package names allocated.

`auto-deconfiguration.txt'
     How dpkg can sometimes automatically deconfigure packages in order
     to do bulk installations smoothly.

`dpkg-essential-flag.txt'
     How to tell dpkg a package is essential and should not be removed.
     (This is for the use of base system packages only.)

`dpkg-disappear-replace.txt'
     What happens when a package appears to have been completely
     replaced.

   In the future, we hope also to make available:

`copyright.txt'
     How to choose a good copyright notice to attach to new programs.

`version-ordering.txt'
     The algorithm with which packages' version numbers are compared.

   Also, you should download the sample files and the sample package
(GNU Hello) available in `standards/samples'.  You may use any of this
material as a starting point for new packages.  The following sample
files, incidentally, are available:

   * debian.README

   * debian.control

   * debian.postinst

   * debian.postrm

   * debian.rules

   Some more detailed information about certain topics is available in
the appendix to this document (*note Appendix::.).


File: guidelines.info,  Node: Package Copyright,  Next: Package Content,  Prev: Additional Information,  Up: Top

Package Copyright
*****************

   Please study the copyright of your submission *carefully* and
*understand it* before proceeding!  If you have doubts or questions,
please ask!

   In order to understand how we classify and distribute certain
packages, it is important to understand the distinction between being
freely available and being freely redistributable.

   Being "freely available", quite simply, means that the software can
be made available freely, at least for non-commercial purposes and in
its original, unmodified form.  This includes packages made available
freely that have restrictions on non-commercial use, redistribution of
modifications, etc.  Being freely available, therefore, has nothing to
do with being able to modify and redistribute the software.  It only
means that you can get a copy of the software without having to pay
(and it does not necessarily mean that you can *use* the software
without having to pay--shareware is an example of freely available
software).

   "freely redistributable", while generally being freely available,
goes beyond just being freely available.  Freely redistributable means
that that the software, in addition to being able to be made available
freely, must be able to be freely modified and redistributed without
restriction.

   All submissions to be included in the distribution proper *must* be
freely redistributable.

   In addition to the distribution, the Project maintains two separate
archives of software packages with the distribution: the `contrib'
archive and the `non-free' archive.

   `contrib' is an archive of user-contributed packages that are not
maintained by the Project, packages that were once maintained by the
Project but that are no longer actively maintained, and packages that
are maintained by the Project but that are not yet considered ready for
inclusion in the distribution proper (i.e., ALPHA and BETA packages).
As above, all submissions for inclusion in the `contrib' archive *must*
be freely redistributable.

   `non-free' is an archive of packages with either restrictive or
unclear terms of copying or modification.  If a package has *any*
restrictions on modification or redistribution, it can not be included
in the distribution or `contrib' archive.  It can only be included in
the `non-free' archive, and then only if it is freely available.

   In summary, in order to be included in the distribution proper or the
`contrib' archive, a package must be *freely redistributable*.  Anyone
must be able to make copies of it, modify it, redistribute it with
their modifications in place, include it on a CD-ROM, or generally sell
it.  To be included in the `non-free' archive, a package may have
restrictions, as long as the package remains *freely available*.  We
must be available to make it available freely at the archive, and anyone
must be able to make copies of it and use it for at least
non-commercial, personal purposes.  Software that will typically be
included in `non-free' are software that does not allow commercial
distribution, software that does not allow modification or
redistribution of modifications, commercial "demos", and "shareware".

   When in doubt, send mail to `iwj10@cus.cam.ac.uk' and
`imurdock@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".

   Every package submission *must* be accompanied by verbatim copy of
its copyright (with the exceptions of public domain packages and those
covered by the UCB BSD licence or the GNU GPL or LGPL; in these cases
simply indicate which is appropriate).  This information must be
included in a file installed to the directory `/usr/doc/copyright'.
See below for details.


File: guidelines.info,  Node: Package Content,  Next: Source Package,  Prev: Package Copyright,  Up: Top

Package Content
***************

   The following requirements apply equally to both the binary and
source packages.  In either case, when files have been installed, they
must conform to the requirements described in this section.

   The primary rule in Debian GNU/Linux is to follow the Linux "File
System Standard" ("FSSTND").  The location of installed files *must*
comply *fully* with the FSSTND.  The latest version of this document
can be found alongside the Guidelines or at `tsx-11.mit.edu' in
`/pub/linux/docs/linux-standards/fsstnd'.  Specific questions about
following the standard should be addressed to Daniel Quinlan, the
FSSTND coordinator, at `quinlan@yggdrasil.com'.

   In addition to the FSSTND, all Debian GNU/Linux packages must follow
the guidelines below.

   * Directories should be mode 755 or (for group-writability) mode
     2775, with the exception of special "system" directories that need
     to be another mode.  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, of course.
     Use common sense in assigning permissions and ownerships to
     directories, and make sure that what is done is secure if it is
     "non-standard".

   * Normal binaries should be mode 755 and owned by `root.root'.  If
     there is a good reason to use a different mode or ownership, you
     may do so, but you must try to be as consistent as possible with
     the rest of the system.  If you need to use a different mode or
     ownership, please discuss it with `imurdock@debian.org'.

   * Setuid binaries should normally be mode 4755 (not 4711!) and, of
     course, owned by the appropriate user.

   * Setgid binaries should normally be mode 2755 (not 2711!) and, of
     course, owned by the appropriate group.

   * Library files should generally be mode 644 and owned by
     `root.root'.  If the package requires different permissions or
     ownerships to function correctly, they should be used instead.

   * Manual pages should be mode 644 and owned by `root.root'.  The
     `nroff' source must be installed.  You should *not* install a
     preformatted "cat page", and you should only use sections 1 to
     9--see the FSSTND for more details.  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 `undocumented'(7) manual page should
     be provided. This symbolic link can be created from `debian.rules'
     like this:

          ln -s ../man7/undocumented.7 debian-tmp/usr/man/man[1-9]/the_requested_manpage.[1-9]

     Do not close the bug report until a proper manpage is available.
     You may forward the complaint to the upstream maintainers, and
     mark the bug as forwarded in the Debian bug tracking system.  The
     GNU Project do not in general consider the lack of a manpage to be
     a bug, but we do - if they tell you to go away leave the bug open
     anyway.

   * Info documents should be mode 644, owned by `root.root', and
     compressed with `gzip -9' when installed.  The package must call
     `install-info' to update the Info `dir' file.  This should be done
     in the post-installation script (`postinst'), like this:

          install-info --quiet /usr/info/foobar.info

     The entries should be removed by the pre-removal script (`prerm'),
     like this:

          install-info --quiet --remove /usr/info/foobar.info

     It is also a good idea to specify a section for the Info `dir'
     entry.  This is done with the `--section' switch.  To determine
     which section to use, you should use look at `/usr/info/dir' on
     your system and choose the most relevant (or create a new section
     if none of the current sections are relevant).

     If `install-info' cannot find a description entry in the Info file
     you will have to supply one.  See `install-info'(8) for details.

   * If a package contains any shared libraries you will have to invoke
     `ldconfig' in both the `postinst' and `prerm' scripts to correctly
     update the library links.  See `ldconfig'(8) for details.

   * Any additional documentation that comes with the package can be
     installed at the discretion of the package maintainer.  Text
     documentation should be mode 644, owned by `root.root', installed
     to `/usr/doc', and compressed with `gzip -9' unless it is small.

     If a subdirectory of `/usr/doc' is warranted, please do create one.
     Please do not install DVI, PostScript, or large textual
     documentation in the same package; upload such documentation as a
     separate package (installing its files in `/usr/doc') so that it
     can be made available with the distribution.  If a user has the
     need for the documentation, they can easily get it from the
     archive, CD-ROM, etc., but it should not take up disk space on the
     machines of the user who do not need or want it installed.

   * Create a file named `/usr/doc/copyright/<package>' which gives
     details of the authorship and copyright of the package.  If the
     package is distributed under the GNU General Public Licence, the
     GNU Library General Public Licence or the Regents of the
     University of California at Berkeley (BSD) licence, please say so
     instead of including a copy of the licence.  The files `BSD',
     `GPL', and `LGPL' will be available in the `/usr/doc/copyright'
     directory for you to refer to.  `/usr/doc/copyright/<package>'
     should not be compressed.

     *All* authorship and copyright information from the original source
     package must be included in the `/usr/doc/copyright/<package>'
     file.

   * Any example files (for example, sample configuration files) should
     be placed in the directory `/usr/doc/examples'.  If the file is
     normally a hidden file, such as `.emacs', then please call it
     `dot.emacs', to avoid confusion.  Again, you may create a
     subdirectory if it is needed.

   * All symbolic links should be relative, not absolute.  Absolute
     links, in general, cause problems when a file system is not
     mounted where it "normally" resides (for example, when mounted via
     NFS).  In certain cases, however, relative links may also cause
     similar problems.  I have generally made links into `/etc' and
     `/var' absolute and all other links relative.  There may be other
     cases in which absolute links are necessary.

     Therefore, in the `Makefile' or `debian.rules', do not do:
          install: all
                   [...]
                   ln -fs /usr/bin/gcc /usr/bin/cc
                   [...]
     Instead, do:
          ln -fs gcc /usr/bin/cc
     or
          ( cd /usr/bin ; ln -fs gcc cc )

     Please do not create hard links in the manual page directories.  In
     these cases, you should use relative symbolic links or files that
     `.so' (roff for `source') others instead.

   * All command scripts should have a `#!' line naming the shell to be
     used to interpret them.

   * In the case of Perl scripts this should be `#!/usr/bin/perl' or
     sometimes `#!/bin/perl', as follows: if the script is a critical
     one that may be called when the `/usr' partition is unmounted or
     broken it should use `/bin/perl'.  Otherwise (especially if the
     script is not specifically targetted at Debian) it should use
     Perl's standard location, `/usr/bin/perl'.

   * Generally the following compilation parameters should be used:

             CC = gcc
             CFLAGS = -O2 -g -Wall # sane warning options vary between programs
             LDFLAGS = # none (or -N, if appropriate; see below)
             install -s (or strip)

     Note that all installed binaries should be stripped, either by
     using the `-s' flag to `install', or by calling `strip' on the
     binaries after they have been copied into the `debian-tmp' but
     before the tree is made into a package.

     Make sure that you do not link with `-g', as this makes a.out
     compilers produce huge statically linked binaries.  The `-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.

     `-N' should only be used on binaries that are very small (less than
     8K with the `-N' option, roughly) and are not likely to have
     multiple instances in memory.  Do not use `-N' on daemons, no
     matter how small they are.

     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 (`-O3', for example); feel free to use them.  Please
     use good judgment here.  Don't add flags for the sake of adding
     flags; only add flags if there is good reason to do so.

   * 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.

   * Logfiles should usually be named `/var/log/<package>', or
     `/var/log/<package>.<something>' if you have several logfiles.  It
     may be appropriate to create a directory.  Make sure that any
     logfiles are rotated occasionally so that they don't grow
     indefinitely; the best way to do this is to use `savelog' from the
     cron package in an `/etc/cron.daily', `/etc/cron.weekly' or
     `/etc/cron.monthly' script.

   * Please check with the base system maintainer (Ian Murdock) before
     using users or groups other than `root' and others specified in
     this document.


File: guidelines.info,  Node: Source Package,  Next: Binary Package,  Prev: Package Content,  Up: Top

Source Package
**************

   The source package should contain a file called `debian.rules' which
contains at least the following targets, to be invoked in the top level
directory:

     build
     binary
     clean

   `debian.rules' should start with

     #!/usr/bin/make -f

and be executable.  It is a good idea to arrange for it not to fail
obscurely when invoked in the wrong directory, for example by testing
for the existence of a file in the source directory.

   * The `build' target should perform all non-interactive configuration
     and compilation of the package.  If a package has an interactive
     pre-build configuration routine, the source package should be built
     *after* this has taken place.

     For some packages, notably ones where the same source tree is
     compiled in different ways to produce two binary packages, the
     `build' target does not make much sense.  For these packages it is
     good enough to provide two (or more) targets (`build-a' and
     `build-b' or whatever) for each of the ways of building the
     package, and a `build' target that does nothing.  The `binary'
     target will have to build the package in each of the possible ways
     and make the binary package out of each.

   * The `binary' target of `debian.rules' should be all that is
     necessary for the user to build the binary package.  The binary
     package should be created using `dpkg' and placed in the parent of
     the top level directory.  The next section describes how to
     construct binary packages from the `binary' target.

   * The `clean' target should undo the effects of the `build' target
     and the `binary' target, except that it should leave alone any
     `../<package>-<version>.deb' file created by a run of `binary'.

   * Additional targets may exist in `debian.rules'.  We recommend using
     `source' and `diff' targets to build the Debianised source package
     and the Debianisation context diff, respectively.  These files
     should be placed in `../foo-<version>.tar.gz' and
     `../foo-<version>.diff.gz'.  The `install' target, for installing
     into a running system direct from the Debianised source tree, is
     no longer required.  The sample `debian.rules' provides `source'
     and `diff' targets that should work with little or no alteration,
     providing that the package-specific variables at the top of the
     script have been properly defined.

   * If you need to edit a `Makefile' where `configure' scripts are
     used, you should edit the `.in' files rather than editing the
     `Makefile' directly.  This allows the user to reconfigure the
     package if necessary.  You should *not* configure the package and
     edit the generated `Makefile'!  This makes it impossible for
     someone else to later reconfigure the package.

   * Please document your changes to the source package so that future
     package maintainers know what has been changed.  To do this,
     include a description of your changes in the `debian.README'
     (which, as described above, should already contain authorship and
     copyright information!) and include relevant information such as
     your name, electronic mail address, date, etc.  The
     `debian.README' file should also document any `unusual' packages
     which must be installed for this one to compile.

   * If changes to the source code are made that are applicable to Linux
     systems or systems in general 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.

     If changes to the source code are made, please use a `define'.  If
     they are changes required to compile or function under Linux in
     general, use `LINUX'.  If it is a cosmetic or functional change,
     use `DEBIAN'.

   * Create the source package using `tar', and use `gzip -9' to
     compress it.  Source packages should be named in the form
     <package>-<version>.tar.gz--for example, `fileutils-3.9-3.tar.gz'.

     NB, here `<version>' is the full Debian version number, in the
     form `<original_version>-<debian_revision>' (see below), but the
     tarfile should unpack into a directory named
     `<package>-<original_version>' (again, see the section below on
     version numbering).

   * Create the context diff against the original package using `diff
     -cNr', and use `gzip -9' to compress it.  Context diffs should be
     named in the form <package>-<version>.diff.gz--for example,
     `fileutils-3.9-3.diff.gz'.

   Please note that the package and patch filenames do *not* need to
fit in MS-DOS 8+3.  They will be made available under an alternative
8+3 name in the archive by the archive maintainer, using a symlink.


File: guidelines.info,  Node: Binary Package,  Next: Control Files,  Prev: Source Package,  Up: Top

Binary Package
**************

   The `binary' target of the source package `debian.rules' file should
do the following (see the sample `debian.rules' for an implementation
that you are free to modify and use in your own packages, of course):

   * Create an empty directory in the top-level directory of the source
     package (deleting it first, if necessary), and install the files
     belonging to this package in that directory.  For example, the
     directory could be called `debian-tmp' and would probably contain
     directories `debian-tmp/usr/bin', `debian-tmp/usr/lib', etc.
     (`debian-tmp' is the name traditionally used, and it is used in
     the sample `debian.rules' file, so we will use that name in the
     Guidelines.)

   * Make sure that all the files under `debian-tmp' have the correct
     ownerships and permissions (*note Package Content::., for more
     information about file locations, ownerships, and permissions.)

   * Create a subdirectory of `debian-tmp' called `DEBIAN'.  This
     directory contains the package control information, including at
     the very least the master information file named `control'.  The
     next section describes the semantics and syntax of the files
     required and allowed here.

   * Run `dpkg' to create the binary package, using something like

          dpkg --build debian-tmp

     This will create a file called `debian-tmp.deb', from the
     `debian-tmp' directory.  You should rename this file to
     `../<package>-<version>.deb' after it is built.

     After the `binary' target has done all this, the
     `<package>-<version>.deb' file in the parent directory is the
     binary distribution.  This file may be distributed and installed on
     any Debian GNU/Linux system with `dpkg' in the same manner and
     using the same methods as all packages are installed to the system.

   * If a single source package corresponds to several binary packages,
     there should usually be a `debian.rules' file with a single
     `binary' target that builds all the binary packages involved and
     move all packages to the parent directory of that containing the
     source package.

     In this case, you should choose binary package names which are
     meant to make clear the close relationship between the binary
     packages and which source package the binary packages came from
     (for example, the `texinfo' source package build two binary
     packages: `texidoc' and `texinfo').  You should place the
     appropriate binary package name in the `Package' field of the
     control file (not the source package name), and you should
     consider whether the other binary packages that come from the same
     source tree should be mentioned in the `Depends', `Recommends' or
     `Suggests' fields.  You should put the source package name in the
     `Source' field.

     You should retain the source package version numbering in the
     `Version' field, if possible--the version number should be the
     same for the Debianised source tree and all the binary packages
     generated from it.  It is more important, though, that the version
     numbers sort correctly.  See below for details of version numbers.


File: guidelines.info,  Node: Control Files,  Next: Appendix,  Prev: Binary Package,  Up: Top

Control Files
*************

   Each binary package contains, in addition to the files that comprise
the actual package, a set of text files that control how `dpkg'
installs, configures, upgrades, removes, etc. the package.  These files
are called "control files".  When creating the package, the control
files should placed in a directory called `DEBIAN', as described
earlier (*note Binary Package::., for further information).

   The control information files are:

`control'
     The master package control information file.

`conffiles'
     A list of package configuration files.

`preinst'
     The package pre-installation script.

`postinst'
     The package post-installation script.

`prerm'
     The package pre-removal script.

`postrm'
     The package post-removal script.

   Of these, only `control' is required.  The various installation
scripts, and the configuration files list, will only be used if they are
present.

* Menu:

* control::
* conffiles::
* Installation and Removal Scripts::
* Dependencies and Conflicts::
* Package Classification Fields::


File: guidelines.info,  Node: control,  Next: conffiles,  Prev: Control Files,  Up: Control Files

control
=======

   The `control' file contains a number of fields.  Each field begins
with a field name, such as `Package' or `Version' (case insensitive),
followed by a colon and optionally some spaces or tabs (a single space
is conventional).  Then comes the body of the field, which may be
several lines long; each continuation line must start with at least one
space or tab.  (These are the same rules as apply to RFC822 mail
headers.)  Blank lines are not permitted in the control file.

   The required fields in the control file are the following:

`Package'
     The name of the package.

`Description'
     The description of the package.  How to write an extended and more
     usefull description field can be found in *note How to write the
     Description control file field::..

`Maintainer'
     The name and e-mail address of the maintainer of the package.

`Version'
     The version number in the format
     `<original_version>-<debian_revision>'.

   Each field has a particular format and meaning for the package
installation tools.

   The value of `Package' should be the name of the package.  Package
names must start with an alphanumeric, must be at least two characters,
and may contain only alphanumerics and the characters - + . @ : = % _
(that is, hyphen, plus, stop, at, colon, equals, percent and
underscore).  They are not case sensitive.

   The `Maintainer' field should be in the form

     Joe J. Bloggs <jbloggs@foo.com>

Note that this will not be useable as an email address if the name
given contains full stop characters, because of a silly restriction in
the Internet mail standards.  If you want to use this as an email
address in a program you should check for full stops and change the
string to the form `jbloggs@foo.com (Joe J. Bloggs)' if you find any.

   The `Version' field should be the version number of the package.
For most packages which are not written specifically for Debian, this
should be in the form

     Version: <original_version>-<debian_revision>

where `<original_version>' is the original package version number in
whatever form the original package uses and `<debian_revision>'
indicates which "debianisation" this is (this should usually be a plain
number or perhaps a two numbers separated by a full stop, and should be
incremented each time the package is changed or updated).

   Packages which are written specifically for Debian do not have a
debian_revision, and their version number should simply be version
(which should not contain any hyphens, to avoid confusion).

   There is an ordering imposed on version numbers, described in
`version-ordering.txt'.  This ordering is designed to `do the right
thing' in most circumstances; if your package has an version number in
an unusual format you may need to reformat it somewhat to get the
ordering right.  This is important because `dpkg' is (for example)
reluctant to downgrade packages.

   The optional fields in the control file are the following:

`Depends'
     The names of prerequisite packages.

`Recommends'
     The names of related, recommended packages.

`Suggests'
     The names of related, optional packages.

`Conflicts'
     The names of packages which conflict with this package.

`Provides'
     The names of virtual packages which this package provides.

`Priority'
     The `priority' of the package, as shown and used by `dselect'.

`Section'
     The `section' of the package, as shown and used by `dselect', and
     used as a location for the package in the distribution.

`Essential'
     A boolean field used by the base packages.

`Pre-Depends'
     Used by base packages to ensure that (for example) shared
     libraries are present befoore they are upgraded.

`Source'
     Gives the name of the source package when several binary packages
     are generated from a single source tree.

See below for details of the semantics and syntax of these fields.
Most packages will need at least a `Depends' field.

   An example of a `control' file would be:

     Package: smail
     Version: 3.1.29.1-13
     Maintainer: Ian Jackson <iwj10@cus.cam.ac.uk>
     Recommends: pine | mailx | elm | emacs | mail-user-agent
     Suggests: metamail
     Depends: cron, libc5
     Conflicts: sendmail
     Provides: mail-transport-agent
     Description: Electronic mail transport system.
      Smail is the recommended mail transport agent (MTA) for Debian.
      .
      An MTA is the innards of the mail system - it takes messages from
      user-friendly mailer programs and arranges for them to be delivered
      locally or passed on to other systems as required.
      .
      In order to make use of it you must have one or more user level
      mailreader programs such as elm, pine, mailx or Emacs (which has Rmail
      and VM as mailreaders) installed.  If you wish to send messages other
      than just to other users of your system you must also have appropriate
      networking support, in the form of IP or UUCP.

   In this case, `mail-user-agent' is a virtual package representing
any user mailer program; the actual package names `pine' is quoted for
the reasons described in `dependency-ordering.txt', and the others
because older versions of those packages do not have the appropriate
`Provides' field.


File: guidelines.info,  Node: conffiles,  Next: Installation and Removal Scripts,  Prev: control,  Up: Control Files

conffiles
=========

   The contents of `conffiles' is simply a list of configuration files
in the package.  When installing the package, `dpkg' uses an
intelligent method to update these files.  This will ensure that
package-specific configuration files are not overwritten when a package
is upgraded, unless the user wishes the installation tools to do so.

   Typically, files listed in conffiles are package-specific
configuration files, which (according to the Linux Filesystem Standard)
are stored in `/etc'.  For example, the `sendmail' package may contain
the file `/etc/sendmail.cf', which we do not wish to overwrite
automatically when the user upgrades the sendmail package.  Only those
files listed in `DEBIAN/conffiles' will be updated intelligently when a
package is upgraded; all other files in the package will be overwritten
by the upgrade process.

   Configuration files which will be functional as shipped and will
probably need little or no local editing should simply be listed the
`conffiles' file; in this case you need read no further.

   For packages whose configuration files will need modification on
most systems there are two sensible approaches.  Which one is chosen
depends on how hard the configuration problem is and how much time the
package maintainer has available.

   One option is for you to ship a minimal `best-effort' file in
`/etc', and list the file in `conffiles'.  This will mean that the user
will have to go and edit the file themselves to get the package to work
properly, of course.  The next time they upgrade the package, if you
haven't changed the file version, their old file will be left in place.
If you have modified your version then the user will get a prompt
asking them which version of the file they want, theirs or yours.  They
will then usually have to resolve the discrepancies manually.

   The other option is to be preferred, if you can do it: do not put a
copy of the configuration file in the package at all.  Instead, you
check in the postinst whether the file exists, and if it doesn't you
prompt the user for the information you need to create a good one.  This
is obviously harder work.

   You also have to remember that you will have to keep up with your
package's changes: if you discover a bug in the program which generates
the configuration file, or if the format of the file changes from one
version to the next, you will have to arrange for the postinst script to
do something sensible--usually this will mean editing the installed
configuration file to remove the problem or change the syntax.  You will
have to do this very carefully, since the user may have changed the
file, perhaps to fix the very problem that your script is trying to deal
with--you will have to detect these situations and deal with them
correctly.

   If you do go down this route it's probably a good idea to make the
program that generates the configuration file(s) a separate program in
`/usr/sbin', by convention called package`config', and then run that if
appropriate from the post-installation script.  The package`config'
program should not unquestioningly overwrite an existing
configuration--if its mode of operation is geared towards setting up a
package for the first time (rather than any arbitrary reconfiguration
later) you should have it check whether the configuration already
exists, and require a `--force' flag to overwrite it.

   `conffiles' should almost certainly list all the files contained in
your package in the `/etc' directory.  There may also be other files
somewhere that the user is expected to edit, which should also be
included.  Note, however, that the FSSTND specifies that configuration
files must be in `/etc'.  No Debian package should contain
configuration files in `/usr/etc', and all programs should refer to
configuration files in `/etc'.

For example, the TCP/IP package might use a conffiles which contains

     /etc/init.d/netbase
     /etc/gateways
     /etc/protocols
     /etc/services
     /etc/hosts.allow
     /etc/hosts.deny
     /etc/rpc

and so on; the files

     /etc/hosts
     /etc/inetd.conf
     /etc/host.conf
     /etc/networks
     /etc/resolv.conf

might be generated by an interactive configuration program, and would
then not be included in the package or listed in the `conffiles'.


File: guidelines.info,  Node: Installation and Removal Scripts,  Next: Dependencies and Conflicts,  Prev: conffiles,  Up: Control Files

Installation and Removal Scripts
================================

   The scripts `preinst', `postinst', `prerm', and `postrm' are
optional (Bash or Perl) scripts.  As the names would indicate, if these
scripts exist, they will be executed before installing the package,
after installation, before package removal, and after removal,
respectively.

   They are given arguments which indicate the precise situation and
action being performed--see `maintainer-script-args.txt' for details of
exactly when each of the scripts is invoked and what its arguments are.
Extra arguments and situations may be added later, so you should not
test the number of arguments to your script to determine the situation,
and you should choose the sense of your `if it is this then do this
otherwise do that' tests carefully.

   These scripts can be used to perform any site-specific package
configuration.

   Because the scripts will be exectued by the dpkg front-end, it is
guaranteed that the scripts will be executed interactively.  User input
from the scripts should be read from standard input, not the user's
terminal.  Similarly, output should be sent to standard output.

   If your maintainer scripts need to prompt for passwords and/or do
full-screen interaction should do these things to and from `/dev/tty',
since `dpkg' 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 `$|=1' so that the output is printed immediately rather than
being buffered.

   The scripts must be idempotent, and they must clean up after
themselves properly.  Ie, they must do the right thing if run multiple
times, even if previous runs failed halfway through.  This is so that if
any errors occur, or if the `dpkg' run is interrupted, the user can
recover by rerunning `dpkg', and/or by upgrading to a new version and
then rerunning the failed operation.

   These scripts should avoid producing output which it is unnecessary
for the user to see and should rely on `dpkg' to stave off boredom on
the part of a user installing many packages.  This means, amongst other
things, using the `--quiet' option on `install-info'.

   Packages should try to minimise the amount of prompting they need to
do, and they should ensure that the user will only every be asked each
question once.  This means that packages should try to use appropriate
shared configuration files (such as `/etc/papersize' and
`/etc/news/server'), rather than each prompting for their own list of
required pieces of information.

   It also means that an upgrade should not ask the same questions
again, unless the user has used `dpkg --purge' to remove the package's
configuration.  The answers to configuration questions should be stored
in an appropriate place in `/etc' so that the user can modify them, and
how this has been done should be documented.

   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 `postinst'
script and prompt the user to hit Return to acknowledge the message.
Copyright messages do not count as vitally important (they belong in
`/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).

   They should return a zero exit status for success, or a nonzero one
for failure.  Note that if a script is a `#!/bin/sh' script it should
probably start with `set -e', to avoid continuing after errors--see
`bash'(1) for details.  Perl scripts should check for errors when
making calls such as `open', `print', `close', `rename' and `system'.

   If these scripts exist they should be left in the `DEBIAN' directory
with execute permission enabled and should contain an appropriate `#!'
line, such as `#!/bin/bash' for a `bash' script or `#!/bin/perl' for a
Perl script (see above).


File: guidelines.info,  Node: Dependencies and Conflicts,  Next: Package Classification Fields,  Prev: Installation and Removal Scripts,  Up: Control Files

Conflicts, Depends, Suggests, Recommends and Provides
=====================================================

   The `Depends' field lists packages that are required for this
package to provide a significant amount of functionality.  The package
maintenance software will not allow a package to be installed without
also installing packages listed in its `Depends' field, and will run
the `postinst' scripts of packages listed in `Depends' fields before
those of the packages which depend on them, and run the `prerm' scripts
before.

   Packages containing dynamically-linked executable binaries (this
includes almost all C programs) should include a `Depends' field which
mentions the shared C library required for the program to run.  For
a.out binaries linked against `libc.so.4' the relevant package name is
`libc' (for the a.out stable 0.93 tree) or `libc4' (for the unstable
development 1.1 tree); for ELF binaries linked against `libc.so.5' the
relevant package name is `libc5'.

   The `Recommends' field lists packages that would be found together
with this one in all but unusual installations.  The user-level package
maintenance program `dselect' will warn the user if they select a
package without those listed in its `Recommends' field.  Note that
`Recommends' fields do not currently have any implications for the
order in which the maintainer scripts are run.

   The `Suggests' field lists packages that are related to this one and
can perhaps enhance its usefulness, but without which installing this
package is perfectly reasonable.  The package maintenance software will
not moan at the user for not selecting `Suggests' related packages, but
may use the information in the `Suggests' field to assist the user
during package selection.

   The syntax of `Depends', `Recommends' and `Suggests' is a list of
groups of alternative packages.  Each group is a list of packages
separated by vertical bar (or `pipe') symbols, `|'.  The groups are
separated by commas.  Each package is a package name optionally
followed by a version number specification in parentheses.  A version
number may start with a `>=', in which case that version or any later
will match, or `<=' for that version or any earlier version. A version
number starting with a `>>' or `<<' will respectively match any later
or earlier version. If a version number or a version number starting
with `=' is specified an exact match is required. Commas are to be read
as `AND', and pipes as `OR', with pipes binding more tightly.

   Versions of dpkg before 1.0.9 used `<' and `>' for `<=' and `>='
(these are still supported for backward compatibility), and did not
support `<<' and `>>'.

   The `Conflicts' field lists packages that conflict with this one,
for example by containing files with the same names (an example would
be Smail vs. Sendmail).  The package maintenance software will not
allow conflicting packages to be installed.  Two conflicting packages
should each include a `Conflicts' line mentioning the other.

   The syntax of `Conflicts' is a list of package names (with optional
version numbers), separated by commas (and optional whitespace).  In
the `Conflicts' field the comma should be read as `OR'.

   The `Provides' field lists the names of any `virtual packages' of
which this packages is to be considered an instantiation.  Virtual
packages are used to allow packages to refer to a service they require
(such as the availability of `/usr/sbin/sendmail') without having to
know the names of all the relevant packages.  The virtual package names
defined in `Provides' fields may be used in other packages' `Depends',
`Recommends', `Suggests' and `Conflicts' fields.  For more information
about how to use virtual packages and which virtual package names to
use read *note Virtual dependencies::. and
`doc/package-developer/virtual-package-names-list.text'.

   The syntax of `Provides' is a list of package names separated by
commas (and optional whitespace).


File: guidelines.info,  Node: Package Classification Fields,  Prev: Dependencies and Conflicts,  Up: Control Files

Priority, Section and Essential
===============================

   The `Priority' and `Section' fields are used by `dselect' when
displaying the list of packages to the user.  There is no need to put
them into a package, since these are usually set by the distribution
maintainers in the `Packages' file.

   However, if a user installs a package which is not part of the
standard distribution, or without downloading and updating from a new
`Packages' file, the information about the priority and section of a
package will be absent, and the `dselect' package listing will have the
package listed under `unclassified'.  It is permissible for a package
to include `Section' or `Priority' fields to improve this; however, if
you do this you should make sure you keep the information up to date so
that users are not shown conflicting information.  The `Section' field
can also be used by the distribution maintainers as a suggestion about
which section you think is most appropriate for your package.

   The values for the `Section' and `Priority' fields should be
determined by the distribution maintainers; if you don't know what to
put in them just leave them out.  You can add them later, if you like,
but remember that you'll then have to reissue your package if the
distribution maintainers change the classification of your package.

   The `Essential' field should only appear in packages in the
installation's base system.  If it is set to `yes' then `dpkg' will not
remove the package even if asked to, and will make certain minor
modifications to its installation procedures.  The only other legal
value is `no', which is equivalent to the absence of the field.




File: guidelines.info,  Node: Appendix,  Prev: Control Files,  Up: Top

Appendix
********

* Menu:

* configuration files - /etc/skel vs /usr/doc/examples::
* How to write the Description control file field::
* Configuration of init::
* Maintainer script arguments and how `dpkg' does things::
* Mail processing packages::
* Virtual dependencies::