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

Debian Linux Packaging Guidelines
*********************************

This file documents the steps that must be taken in the preparation of a Debian 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 Linux archive.

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

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 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 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 (see Appendix).

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

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.

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 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 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; shared libraries should be mode 755.  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.

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

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 unified context diff against the original package using diff -uNr, and use gzip -9 to compress it.  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.

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 (see 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 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.

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 (see 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.

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 see 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)  (The characters @ : = % _ (at, colon, equals, percent and underscore) used to be legal and are still accepted when found in a package file, but may not be used in new packages). They are sort of case sensitive - please try to get the case right first time.

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 before they are upgraded.  This feature is for expert use only.

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.

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 packageconfig, and then run that if appropriate from the post-installation script.  The packageconfig 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.

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 arguments and how dpkg does things 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 #!/usr/bin/perl for a Perl script (see above).

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

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.

Appendix
********

configuration files -- /etc/skel vs /usr/doc/examples
=====================================================

There seems to be a certain amount of confusion about /etc/skel and /usr/doc/examples. The most important thing to remember is the following:

Files in /etc/skel will automatically be copied into new user accounts by adduser.  They should not be referenced there by any program. Files in /usr/doc/examples should not be installed automatically.

Therefore, if the program in question need a dotfile to exist in advance in $HOME to work sensibly that dotfile should be installed in /etc/skel (and listed in conffiles; see conffiles).

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 that programs should be configured by the Debian default installation as close to normal as possible.

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 /etc (and that file should be listed in conffiles).  Only if the program doesn't support a site-wide default configuration should a default per-user file be placed in /etc/skel (and listed in conffiles; see conffiles).

The idea is as follows:

The sysadmin should ideally not have to do any configuration other than that done (semi-)automatically by the postinst script.

However, if they wish to change their configuration themselves (because the configuration they want is beyond the scope of the autoconfiguration, or because the autoconfiguration doesn't exist yet, or because they just want to do it themselves for any reason) then /usr/doc/examples exists as documentation for their benefit.

The only time these files should be read are by the sysadmin using their favourite editor or pager, or perhaps (in very complex packages) by the postinst as a template to build on or modify.

/etc/skel is part of the implementation of this configuration.  It contains the files that are copied into new user accounts.  It should probably be as empty as we can make it.

Examples:

.profile
     /etc/skel should not contain a .profile file.  Anything that needs to be done there should be done in /etc/profile. Anything that should not go in /etc/profile (users can't avoid running /etc/profile) probably should not be in the default configuration.  bash has generally good default behaviour.

.bash_logout
     Likewise, bash functions perfectly happily without a .bash_logout, so none should be provided, since anything in it is a deviation from the sensible default behaviour.

.xsession
     /etc/skel should not contain a .xsession.  xdm's system-wide startup file /usr/lib/X11/xdm/Xsession supports a system-wide default user configuration (which should probably be /etc/X11/Xsession or some such) which may be overridden by .xsession in the user's home directory.  Therefore there is no need for a .xsession to be installed by default and none should be provided.

     Instead, a sensible /etc/X11/Xsession should be provided, and if desired this can be used as a template by users who wish to install their own configuration, or alternatively a more comprehensive example with much commented-out interesting stuff could be put in /usr/doc/examples.

     If the sysadmin wishes to change the system-wide default they should probably do this by editing /etc/X11/Xsession rather than creating the file in /etc/skel, because the former will affect all user accounts that haven't explicitly overridden things by creating their own file while the latter will only affect new accounts.

     All the configuration necessary for a program to function should be provided.  Therefore sysadmins will not need to go through /usr/doc/examples while editing configuration files in /etc except in extreme cases (like INN) where the configuration was too difficult to do automatically.

site-wide defaults
     Site-wide defaults should not go in /etc/skel.  In the case of twm, for example, the system-wide default should be in /etc/X11/system.twmrc.  (The default location for this in X11R5, btw, is in /usr/lib/X11 somewhere, but we can't put it on /usr because of CDROM distributions, etc - hence the FSSTND's mandate to put configuration files in /etc.)

.twmrc
     There should be no .twmrc file in /etc/skel.  You can have one in /usr/doc/examples if you like, but why bother if system.twmrc is a good example (and indeed is the one the user is using before they create their own)?

m4
     /usr/doc/examples isn't mainly for example configuration files.  It's for any kind of example file distributed with a package. For example, GNU m4 comes with a whole pile of example m4 macro scripts, which is exactly what /usr/doc/examples is for.

Summary

Files that should be installed in new user accounts should be in /etc/skel, as that will ensure that they are installed in new user accounts!  However, we should try to avoid the need for this.

/usr/doc/examples is just what it says: documentation in the form of examples.  If a sysadmin is required to go and read these files for their system to work they should be told about it.  For example, here is what the Smail postinst script says right at the start:

     I can do certain kinds of automatic configuration of your
     mail system, by asking you a number of questions.  Later you
     may to confirm and/or correct your answers.  In any case,
     comprehensive information on configuring Smail is in
     smail(5) and in /usr/doc/examples/smail and
     /usr/doc/smail-admin-guide.

How to write the Description control file field
===============================================

The format of the Description field is as follows:

     Description: <single line synopsis>
      <extended description over several lines>

Every package should have an extended description.

The extended description has several kinds of line:

  * Those starting with a single space are part of a paragraph.  Successive lines of this form will be word-wrapped when displayed.  The leading space will usually be stripped off.

  * Those starting with two or more spaces.  These will be displayed verbatim.  If the display cannot be panned horizontally the displaying program will linewrap them `hard' (ie, without taking account of word breaks).  If it can they will be allowed to trail off to the right. None, one or two initial spaces may be deleted, but the number of spaces deleted from each line will be the same (so that you can have indenting work correctly, for example).

  * Those containing a single space followed by a single full stop character.  These are rendered as blank lines.  This is the only way to get a blank line - see below.

  * Those containing a space, a full stop and some more characters.  These are for future expansion.  Do not use them.

IMPORTANT and not so important TIPS:

  * Always start extended description lines with at least one whitespace character.  Fields in the control file and in the Packages file are separated by field names starting in the first column, just as in RFC822.  Forgetting the whitespace will cause dpkg-deb (>=0.93.23) to produce a syntax error when trying to build the package. If you force it to build anyway dpkg will refuse to install the resulting mess.

  * Do not include any completely empty lines. These separate different records in the Packages file, and are forbidden in control files.  See the previous paragraph for what happens if you get this wrong.

  * The single line synopsis should be kept brief - certainly under 80 characters.  dselect displays the first 49 characters if you're using an 80-column terminal.

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

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

     The blurb that comes with a program in its announcements and/or README files is rarely suitable for use in a description field. It is usually aimed at people who are already in the community where the package is used.  The Description field needs to make sense to anyone, even people who have no idea about any of the things the package deals with.

  * Put important information first, both in the synopis 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.

  * You may include information about dependencies and so forth in the extended description, if you wish.

  * Do not use tab characters.  Their effect is not predictable.

Example control file for Smail:

     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.

Configuration of init
=====================

The /etc/init.d directory contains the scripts executed by init(8) when init state (or "runlevel") is changed.  This includes the boot process, when the multi-user state begins.  Several of these scripts are included with init and are intended to be executed once, usually at boot time.  An example is /etc/init.d/boot, which is executed at boot time to check and mount file systems, activate swap, load kernel modules, etc.--everything that needs to be done before the multi-user state begins. /etc/init.d also contains the scripts that are executed when entering runlevel 0 (halt), runlevel 1 (single-user) and runlevel 6 (reboot).

Packages can (and should) place scripts in /etc/init.d to start or stop services at boot time or during a change of runlevel.  These scripts should be named /etc/init.d/<package>, and they should accept one of two arguments: "start", which starts the services, or "stop", which stops the services.  These scripts should ensure that they will behave sensibly if invoked with "start" when the service is already running, or with "stop" when it isn't---the best way to achieve this is often to use start-stop-daemon.

This script should not fail obscurely when the configuration files remain but the package has been removed, as the default in dpkg is to leave configuration files on the system after the package has been removed.  Only when it is executed with the `--purge' option will dpkg remove configuration files.  Therefore, you should include a `test' statement at the top of the script, like this:

     test -f <program-executed-later-in-script> || exit 0

These scripts should be referenced, when appropriate, by symbolic links in the /etc/rc?.d directories, as below.

When changing runlevels, init looks in the directory /etc/rc<n>.d for the scripts it should execute, where <n> is the runlevel that is being changed to.  Please note that the "scripts" in /etc/rc?.d are not actually scripts; they are symbolic links, referencing actual scripts in /etc/init.d.  For simplicity, we refer to them as "scripts".

First, the scripts prefixed with a "K" are executed, followed by the scripts prefixed with an "S".  The "K" scripts are responsible for killing certain services and the "S" scripts for starting certain services upon entering the runlevel.  For example, if we are changing from runlevel 2 to runlevel 3, init will first execute all of the "K" prefixed scripts it finds in /etc/rc3.d (to kill services), and then all of the "S" prefixed scripts it finds in /etc/rc3.d (to start services).  The "K" scripts will execute the file it references with an argument of "stop", and the "S" scripts will execute this file with an argument of "start".

After the "K" or "S" prefix, there should be a number specified, and this number should be between 00 and 99.  The number determines the order in which the scripts are run.  For example, the "K20" scripts will be executed before the "K30" scripts.  You can use this number to make sure that a certain service is started before another.  For example, on some machines, the program setserial may need to properly set an IRQ before the ppp program uses a modem to connect to a network. In this case, the script that runs setserial should have a lower number than the script that starts ppp so that it runs first:

     /etc/rc2.d/S10setserial
     /etc/rc2.d/S20ppp

If it does not matter when or in which order the script is run, use the number "20".  If it does, then you should talk to the maintainer of the sysvinit package or post to debian-devel, and they will help you choose a number.

In Debian Linux, we try to ship our software in as much of a "default" state as possible.  Therefore, unless there is a good reason for doing differently, we ask that you start the 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 /etc/rc?.d.  This is why we default to running everything in the multi-user state--a reasonable default--and the administrator can easily customize init to be as complex and sophisticated as he or she wants it to be beyond this.

We provide a script, update-rc.d, to make it easier for package maintainers to arrange for the proper creation and removal of /etc/rc?.d symbolic links from their postinst and postrm scripts. You should use this script to make changes to /etc/rc?.d and never include any /etc/rc.?.d symbolic links in the actual archive.

  * In the postinst script, you need only do the following to setup /etc/rc?.d.  You should redirect standard output to /dev/null, as update-rc.d produces insignificant output:

          update-rc.d <package> default >/dev/null

     where <package> is the name of the file as it appears in /etc/init.d.  It will use the default number of "20", as mentioned above.  If you need to use a different number, you can specify it after "default":

          update-rc.d <package> default 30 >/dev/null

  * In the postrm script, you need only do the following if and only if it is called with the `purge' argument:

          if [ purge = "$1" ]
          then
            update-rc.d <package> remove >/dev/null
          fi

Important Note:
---------------

Do not include the /etc/rc?.d/* symbolic links in the archive!  This will cause problems!  You should create them with update-rc.d, as above.

Do not include the /etc/rc?.d/* symbolic links in conffiles!  This will cause problems!  Do, however, include the /etc/init.d scripts in conffiles.

Example:
--------

The process accounting package wants to make sure that process accounting is started at boot time and that it is stopped before the system is halted, enters the single-user state, or is rebooted (so that the /var file system can be properly unmounted).  It puts a script that does this in /etc/init.d, naming the script appropriately "acct".  This script accepts one of two arguments: either "start", which starts process accounting, or "stop", which stops it.  To ensure that it does not fail obscurely when the configuration files remain but the package has been removed, we include a `test' statement at the top of the script:

     #! /bin/sh
     #
     # Start process accounting.
     . /etc/init.d/functions
     test -f /usr/sbin/accton || exit 0
     case "$1" in
       start)
         echo "Starting process accounting"
         /usr/sbin/accton /var/account/pacct
         ;;
       stop)
         echo "Stopping process accounting"
         /usr/sbin/accton
         ;;
       *)
         echo "Usage: /etc/init.d/acct {start|stop}"
         exit 1
     esac
     exit 0

You may find a skeletal script from which to base your /etc/init.d scripts in /etc/init.d/skeleton.

We want to stop then (re)start process accounting when entering a multi-user state--runlevels 2, 3, 4, and 5--and we want to stop it when leaving such a state--runlevels 0 (halt), 1 (single) and 6 (reboot). These are good defaults, and we accomplish this by including the following in the postinst:

     update-rc.d acct default >/dev/null

When the user removes the acct packages with the `--purge' option, we want to make sure the /etc/rc?.d symbolic links are properly removed, so we include the following in the postrm:

     update-rc.d acct remove >/dev/null

Otherwise, the /etc/rc?.d symbolic links will remain on the system along with /etc/init.d/acct script.

Maintainer script arguments and how dpkg does things
====================================================

This appendix describes exactly how maintainer scripts are called, with what arguments, in what order, and what dpkg does in between.

In all cases version numbers are <version>-<revision>, if the package has both, or just <version>.  upgrade is used even when the new version number looks lower than the old.  If there is no appropriate version then the argument may be the empty string (or, in versions of dpkg before 1.2.1, <unknown>).

Summary
-------

     <new preinst> install
     <new preinst> install <old-version>
     <new preinst> upgrade <old-version>
     <old preinst> abort-upgrade <new-version>

     <postinst> configure <most-recently-configured-version>
     <old postinst> abort-upgrade <new version>
     <conflictor's postinst> abort-remove in-favour <package> <new version>
     <deconfigured's postinst> abort-deconfigure \
                   in-favour <package-being-installed-but-failed> <version>
                   removing <conflicting-package> <version>

     <prerm> remove
     <old prerm> upgrade <new version>
     <new prerm> failed-upgrade <old-vppersion>
     <conflictor's prerm> remove in-favour <package> <new version>
     <deconfigured's prerm> deconfigure \
                   in-favour <package-being-installed> <version> \
                   removing <conflicting-package> <version>

     <postrm> remove
     <postrm> purge
     <old postrm> upgrade <new-version>
     <new postrm> failed-upgrade <old-version>
     <new postrm> abort-install
     <new postrm> abort-install <old-version>
     <new postrm> abort-upgrade <old-version>
     <disappearer's postrm> disappear <overwriter> <new version>

Details of unpack phase of installation or upgrade
--------------------------------------------------

The procedure on installation/upgrade/overwrite/disappear (ie, when running dpkg --unpack, or the unpack stage of dpkg --install) is as follows.  In each case if an error occurs the actions in are 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.

 1. a

 2. If a version the package is already installed, call

          <old prerm> upgrade <new version>

 3. If this gives an error (ie, a non-zero exit status), dpkg will attempt instead:

          <new prerm> failed-upgrade <old-version>

     error unwind, for both the above cases:

          <old postinst> abort-upgrade <new version>

If a `conflicting' package is being removed at the same time: a
If any packages depended on that conflicting package and --auto-deconfigure is specified, call, for each such package:

     <deconfigured's prerm> deconfigure \
      in-favour <package-being-installed> <version> \
      removing <conflicting-package> <version>

error unwind:

     <deconfigured's postinst> abort-deconfigure \
      in-favour <package-being-installed-but-failed> <version>
      removing <conflicting-package> <version>

The deconfigured packages are marked as requiring configuration, so that if --install is used they will be configured again if possible.
To prepare for removal of the conflicting package, call:

     <conflictor's prerm> remove in-favour <package> <new version>

error unwind:

     <conflictor's postinst> abort-remove in-favour <package> <new version>

a
If the package is being upgraded, call

     <new preinst> upgrade <old-version>

otherwise, if the package had some configuration files from a previous version installed (ie, it is in the conffiles-only state):

     <new preinst> install <old-version>

otherwise (ie, the package was completely purged):

     <new preinst> install

error unwind versions, respectively:

     <new postrm> abort-upgrade <old-version>
     <new postrm> abort-install <old-version>
     <new postrm> abort-install

The new package's files are unpacked, overwriting any that may be on the system already, for example any from the old package or from another package (backups of the old files are left around, and if anything goes wrong dpkg will attempt to put them back as part of the error unwind).
a
If the package is being upgraded, call

     <old postrm> upgrade <new-version>

If this fails, dpkg will attempt:

     <new postrm> failed-upgrade <old-version>

error unwind, for both cases:

     <old preinst> abort-upgrade <new-version>

This is the point of no return - if dpkg 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 reinstallation to clear up, but it's when dpkg starts doing things that are irreversible.
Any files which were in the old version of the package but not in the new are removed.
The new file list replaces the old.
The new maintainer scripts replace the old.
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, a
dpkg calls:

     <disappearer's postrm> disappear <overwriter> <new version>

The package's maintainer scripts are removed.
It is noted in the status database as being in a sane state, namely not installed (any conffiles it may have are ignored).  Note that disappearing packages do not have their prerm called, because dpkg doesn't know in advance that the package is going to vanish.

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 lobotomise the file list of the `conflicting' package if there is one.)
The backup files made at 4. are deleted.
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.
If there was a conflicting package we go and do the removal actions, starting from point 2. of the removal, below.

Details of configuration
------------------------

When we configure a package (this happens with dpkg --install, or with --configure), we first update the conffiles and then call:

     <postinst> configure <most-recently-configured-version>

No attempt is made to unwind after errors during configuration.

Details of removal and/or configration purging
----------------------------------------------

 1. <prerm> remove

 2. The package's files are removed (except conffiles).

 3. <postrm> remove

 4. All the maintainer scripts except the postrm are removed.

     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 dpkg status.

 5. The conffiles and any backup files (~-files, #*# files, %-files, .dpkg-{old,new,tmp}, etc.) are removed.

 6. <postrm> purge

 7. The package's file list is removed.

No attempt is made to unwind after errors during removal.

Mail processing packages
========================

Debian packages which process electronic mail (whether mail-user-agents (MUA) or alternative mail-transport-agents (MTA)) must make sure that they are compatible with the configuration decisions below. Failure to do this may result in lost mail, broken From: lines, and other serious brain damage!

  * The mail spool is /var/spool/mail and the interface to send a mail message is /usr/sbin/sendmail (as per the FSSTND).  The mail spool is part of the base and not part of the MTA package.

  * Mailboxes are locked using the .lock lockfile convention, rather than fcntl, flock or lockf.

  * Mailboxes are generally 660 <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 writeable by group mail.

  * The mail spool is 2775 mail.mail, and MUA's need to be setgid mail to do the locking mentioned above (and obviously need to avoid accessing other users' mailboxes using this privilege).

  * /etc/aliases is the source file for the system mail aliases (e.g. postmaster, usenet, etc.) - it is the one which the sysadmin and postinst scripts may edit.

  * The convention of writing `forward to <address>' in the mailbox itself is not supported.  Use a .forward file instead.

  * The location for the rmail program used by UUCP for incoming mail is /usr/sbin/rmail, as per the FSSTND.  Likewise, rsmtp, for receiving batch-SMTP-over-UUCP, is in /usr/sbin/rsmtp if it is supported.

  * Smail is not using HoneyDanBer UUCP, whose uux apparently accepts -a and -g options.

  * 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 /etc/mailname.  It will contain the portion after the username and @ sign for email addresses of users on the machine (followed by a newline).

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 /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.  E.g., in the same situation the INN package says:

     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 `$syshostname', your system's host name.
     Mail name [`$syshostname']:

($syshostname is the output of `hostname --fqdn').

Virtual dependencies
====================

Virtual packages are in the same namespace as real packages, and may have the same name.  The meaning of a virtual package in a dependency/conflicts list is exactly that of listing all the real packages which state that they are an instantiation of that virtual package.

This is done with a new Provides field in the control file, with a syntax much like the Conflicts field.

The idea is that we can have something like:

     Package: elm
     Depends: mta

     Package: smail
     Provides: mta
     Conflicts: mta

     Package: sendmail
     Provides: mta
     Conflicts: mta

The result is equivalent to elm having said

     Package: elm
     Depends: smail | sendmail

(There'll be a special case to say that a package may conflict with a virtual package which it provides - clearly ...)

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

     Package: lout
     Optional: ghostview

(this is a fictional example - the Lout package should not mention ghostview), and someone else comes up with a nice PostScript previewer, then they can just say

     Package: marvelpostview
     Provides: ghostview

and all will work in the interim (until, say, the Lout maintainer changes things).

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 prohibited, for a conflict) - it is assumed that a real package which provides virtual package is not of the `right' version. If there is demand it can be arranged that a package which provides a virtual package may mention a version number, though this is unlikely to be helpful:

     Provides: mta (2.0)

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 can simply list the real package as alternative before the virtual one:

     Package: xbaseR6
     Recommended: xsvga | x-server
     Provides: x-base, xr6shlib

     Package: xsvga
     Recommended: x-base
     Provides: x-server

     Package: x8514
     Recommended: x-base
     Provides: x-server

Virtual package names should generally not be used in the names of /etc/init.d scripts, configuration files, logfiles, and so on, so that several programs providing the same virtual package name can be installed.