        Guidelines for Creating and Maintaining Debian Packages
                 Ian Jackson <iwj10@cus.cam.ac.uk>
              based on the source package guidelines by
                 Ian Murdock <imurdock@debian.org>
               
                   Revision: 21st September 1994

===============================================================================

This document describes the steps that must be taken in the
preparation of a Debian package.  All submissions to be included in
the Debian distribution and all packages wishing to be considered for
Debian `contrib' availability _must_ follow the guidelines and
standards listed in this document.

===========================================================================

Important consideration - Copyright
-----------------------------------

There is one _very_ important consideration to make before proceeding:
do you, the packager, understand the copyright of the package that you
wish to submit?  PLEASE study the copyright of your submission VERY
CAREFULLY and UNDERSTAND IT before proceeding!

Ensure that distribution is possible in binary and source form without
restrictions on modification, redistribution and for-profit use of the
package.  All submissions to be included in the distribution proper
_must_ be free of such restrictions or they cannot be included.

Submissions for `contrib' availability, however, may be allowed to
deviate from this requirement; we want the maximum amount of software
to be available in `dpkg' format for Debian users, so in certain
circumstances it will be allowable to have ``shareware'' and other
non-free software optionally available as `contrib' packages.  It is
important to note that these packages will be _optional_ additions to
the Debian system and that the Debian system itself will remain
completely free of such packages.

When in doubt, send mail to me (see above for address).  Be prepared
to provide me with the copyright.  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).  See below.

===========================================================================

Requirements for the content of the package
-------------------------------------------

The following requirements apply to the source and binary packages
equally; when files have been installed they should conform to the
requirements contained here.


* The location of installed files _must_ comply fully with the Linux
Filesystem Standard.  The latest version of this document can be found
alongside this Debian source package guidelines.  Specific questions
about following the standard can be addressed to Daniel Quinlan
<quinlan@yggdrasil.com>.


* All directories should be mode 755, or (for group-writeability)
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, then it should
be owned by the group that needs write access to it.  Use common sense
in assigning permissions and ownerships to directories, and make sure
that what is done is secure if it is ``non-standard''.


* In general, normal binaries should be mode 755 and owned by
root.root.  If there is a good reason to use a different mode or
ownership, then feel free to do so, but do try to be as consistent as
possible with the rest of the system.


* setuid/setgid binaries should normally be mode 4755/2755 and owned
by the appropriate user/group.


* Library files should generally be installed as mode 644 and owner
root.root; however, if the package requires different permissions or
ownerships to function correctly, then they should obviously be used
instead.


* Manual pages should be mode 644 and owned by root.root.  The nroff
source must be installed.  Do not install a pre-formatted cat page.
Only use manual sections 1 to 9 -- see the FSSTND for more details.


* Info documents should be mode 644, owned by root.root, and `gzipped'
when installed.  The package must call `install-info' to ensure that
its Info document(s) are properly listed in the `dir' file (for binary
packages this should be done by the postinst script).  For example,
        install-info --quiet /usr/info/foobar.info
Their entries should be deinstalled by the prerm script, for example,
        install-info --quiet --remove /usr/info/foobar.info

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


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


* Any other documentation that comes with the package should be
installed at the discretion of the package maintainer.  Text
documentation should be mode 644, owned by root.root, installed in
/usr/doc and `gzipped' unless it is very small.

If a subdirectory of /usr/doc is warranted, then please feel free to
create one.  Please do not install PostScript, DVI or large textual
documentation to /usr/doc; however, please do upload such
documentation as a separate package so that it can be made available
via FTP with the distribution in a `doc' directory.  If a user has the
need for the documentation they can easily get it from there.

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 licence (BSD copyright), please say so instead of
including a copy of the licence.  The files GPL, LGPL and BSD will be
available in the /usr/doc/copyright directory for you to refer to.
/usr/doc/copyright/<package> should not normally be compressed.

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


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


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


* All symbolic links should be relative, not absolute.  Absolute
links, in general, cause problems when a filesystem is not mounted
where it ``normally'' resides (for example, when mounted via NFS).  In
certain cases, however, relative links may also cause similar problems
(for example, if /usr is mounted on /foo/bar, and /foo/bar/spool is a
link to ../spool it will not find it); in this case, feel free to use
absolute links, but they should be used only when necessary.  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, do not do (even though it is easier):
        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; use
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
        LDFLAGS = -s (and -N, if appropriate; see below)

All installed binaries should be stripped, hence -s.  `-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 computational-
intensive programs) may function better with certain flags; 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.


===========================================================================

Creating the source package
---------------------------

* The source package should contain a file `debian.rules', containing
at least the following targets:
   build
   clean
   binary
They are to be invoked in the package top level directory.

+ The `build' target should do the noninteractive 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.

+ The `binary' target of debian.rules should be all that is necessary
for the user to build the binary package that is shipped as part of
the Debian system.  The binary package should be placed in a *.deb
file in the parent of the package's top level directory, and created
using dpkg.  See the below for details on how to construct binary
packages.

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

In the case of `binary' you must ensure that all binaries are
installed in the proper locations and with the correct permissions and
ownerships.  Ensure that any appropriate documentation is installed
along with any appropriate examples and that man pages and Info
documents are installed.

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.

+ Other targets may exist in debian.rules.  We recommend using
`source' and `diff' to generate the Debianised source tarfile and the
Debianisation patch file respectively (conventionally in
../foo-<version>.tar.gz and ../foo-<version>.diff.gz respectively).
The `install' target, for installing into a running system direct from
the Debianised source tree, is now no longer required.


* If you need to edit a package's top-level Makefile: edit the *.in
files in packages where `configure' scripts are used and generate the
Makefile, etc. from them rather than editing the generated files
directly.  This allows the user to reconfigure the package if
necessary.  Do _not_ simply configure the package and edit the
generated Makefile!  This makes it impossible for someone else to
reconfigure the package.


* Please document your changes to the source package so that future
package maintainers know what has been changed.  Record your changes
for Debian in a file called debian.README in the source package's
top-level directory, and include relevant information such as your
name, electronic mail address, date, etc.  If changes to the source
code are made, then please use a `define'.  If it is a change required
to compile or function under Linux in general, then use `LINUX'; if it
is a cosmetic or functional change, then use `DEBIAN'.


* Archive the source package using `tar'.  Use `gzip -9' to compress
it.  Source packages should be named in the form:
                 <package>-<version>.tar.gz
        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).

NOTE: Do not use the `z' option to `tar'!  This will not result in
optimal compression!  Instead, do this:

   # tar cvf foo-1.2.3-4.tar foo-1.2.3
   # gzip -9 foo-1.2.3-4.tar

* Make a context diff against the original package:

   # diff --context --recursive -P foo-1.0.orig/ foo-1.0/

Context diffs should compressed with `gzip -9' and be named in the
form:
                 <package>-<version>.diff.gz
        Example: `fileutils-3.9-3.diff.gz'

You may find the above two things easier to automate with the help of
targets in debian.rules.  If so, the targets to use are `source' and
`diff' for the debianised source tarfile and the debianisation patch,
respectively.

Note also that the package and patch filenames do NOT need to fit in
MSDOS 8+3.  They will be made available under an alternative 8+3 name
in the archive by the archive maintainer, using a symlink.


===========================================================================

Creating the binary package
---------------------------

The `binary' target of the source package's debian.rules file should
do the following things:

* Create an empty subdirectory of the source package's directory
(deleting it first if necessary), and install the files belonging to
this package in that directory.  For example, the subdirectory might
be called `debian-tmp' and would probably contain directories
debian-tmp/usr/bin, debian-tmp/usr/lib, etc.

* Ensure that all the files under debian-tmp have the correct
permissions and ownerships.

* 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'.  Please see below for
details of the syntax and semantics 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 debian-tmp.deb, from the debian-tmp directory.
Rename this file to ../<package>-<version>.deb.

When the `binary' target has done all this the <package>-<version>.deb
file in the containing directory is the binary distribution.  This
file may be uploaded to FTP sites, etc.


* If a single source package corresponds to several binary packages
there should usually be a debian.rules file with a single `binary'
target to generate all the binary packages involved, all as *.deb
files in the parent directory of that containing the sources.

In this case you should choose binary package names which are meant to
make clear the close relationship between the various binary package
and which source package the binary packages came from (e.g., texidoc,
texinfo).  Place the appropriate binary package name in the Name field
of the control file (not the source package name); you should consider
whether the other binary packages that come from the same source tree
should be mentioned in the Depends, Recommended or Optional fields.

You should retain the source package version numbering in the VERSION
field - ie, the version number should be the same for the Debianised
source tree and all the binary packages generated from it.  See below
for details of version numbers.


Meanings of the binary package control information files
--------------------------------------------------------

Each binary package contains, as well as the files which make up the
package itself, a set of text files that control the way the packaging
tools handle the package.  When creating the package using the tools
these files are placed in a DEBIAN directory as described above.  See
the packaging tools spec for details of how these files are stored in
the .deb package file.

The control information files are:

        control         Master package control information file
        conffiles       List of package configuration files
        preinst         Package pre-installation script
        postinst        Package post-installation script
        prerm           Package pre-removal script
        postrm          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.


* Master control file format:

The `control' file contains a number of fields.  Each field begins
with a tag, such as `PACKAGE' or `VERSION' (case insensitive),
followed by a colon, and the body of the field. Fields are delimited
only by field tags.  In other words, field text may be multiple lines
in length, but the installation tools will generally join lines when
processing the body of the field.

The required fields in the control file are the following:

        PACKAGE: <Short name of package>
        VERSION: <Original version number `original_version'>
        PACKAGE_REVISION: <Debian package revision number `debian_revision'>
        MAINTAINER: <Name and e-mail address of package maintainer>
        DESCRIPTION: <Description of package> 

There is but one restriction on the format of control file fields:
The value of `PACKAGE' will be used to generate filenames by the 
installation tools, and therefore should be a valid filename prefix
(i.e., no embedded slashes), and not contain any whitespace.

The MAINTAINER should be in the format  Joe Bloggs <jbloggs@foo.com>.

The VERSION and PACKAGE_REVISION fields 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>
   PACKAGE_REVISION: <debian_revision>
where <original_version> is the original portable package's version
number in whatever form the program's author uses, and
<debian_revision> indicates which `debianisation' this is (this should
usually be a plain number, or perhaps two numbers separated by a full
stop).

The optional fields in the control file are the following:

        DEPENDS: <Short names of prerequisite packages>
        RECOMMENDED: <Short names of related, recommended packages>
        OPTIONAL: <Short names of related, optional packages>
        CONFLICTS: <Short names of packages which conflict with this one>

See below for details of the syntax and semantics of these fields.

An example of a `control' file would be:

        PACKAGE: emacs
        VERSION: 19.22
        PACKAGE_REVISION: 2
        MAINTAINER: Daniel Quinlan <quinlan@bucknell.edu>
        DESCRIPTION: The extensible, customizable, self-documenting, 
                     real-time display editor
        DEPENDS: emcsmisc, emcselc1, emcselc2
        RECOMMENDED: emcselz1, emcselz2, emcsinfo
        OPTIONAL: emcsetc
        CONFLICTS: emacs_nox

In this case, the `emacs' package will contain the binary with X support,
and `emacs_nox' contains the binary without X support. The control
file for `emacs_nox' would contain a `CONFLICTS: emacs' line accordingly.


* Configuration file list format:

The contents of `conffiles' is simply a list of files in the package.
When installing the package the installation tools frontend will
update these using a ``foolproof'' upgrade mechanism.  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.

The exact procedure used for configuration file updates is covered in
the binary package tools specification.  This information will
probably only be of interest to the maintainers of packages with
sophisticated configuration requirements, including those involving
prompting the user for information.

Maintainers of packages whose configuration files will be functional
as shipped and will probably need little or no local editing should
simply list the configuration files in the `conffiles' control file
and need read no further.

conffiles should almost certainly list all the files your package has
in /etc.  There may also be other files somewhere that the user is
expected to edit, which should also be included.  Note, though, that
the FSSTND specifies that configuration files must be in /etc.

For example, the TCP/IP package might use a conffiles which contains
  /etc/hosts
  /etc/networks
  /etc/host.conf
  /etc/resolv.conf
and so on.

* Installation script format:

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

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.

These scripts should avoid producing output which it is unecessary for
the user to see, and should rely on the frontend 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.

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.

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

* The meaning of DEPENDS, RECOMMENDED, OPTIONAL and CONFLICTS

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.

The RECOMMENDED field lists packages that would be found together with
this one in all but unusual installations.  The package maintenance
software will warn the user if they install a package without those
listed in its RECOMMENDED field.

The syntax of DEPENDS and RECOMMENDED 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 any later version will match, and may
specify or omit the Debian packaging revision (separated by a hyphen).
Commas are to be read as `AND', and pipes as `OR', with pipes binding
more tightly.

The OPTIONAL 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 OPTIONAL related packages,
but may use the information in the OPTIONAL field to assist the user
during package selection.

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 OPTIONAL and CONFLICTS is a list of package names,
separated by commas (and optional whitespace).  In the CONFLICTS
field, the comma should be read as `OR'.
