Debian Policy Manual - chapter 2
The Debian Archive

The Debian GNU/Linux system is maintained and distributed as a collection of packages. Since there are so many of them (over 2600) they are split into sections and priorities to simplify handling of them.

The effort of the Debian project is to build a free operating system, but not every package we want to make accessible is free in our sense (see Debian Free Software Guidelines, below), or may be imported/exported without restrictions. Thus, the archive is split into the sections main, non-us, non-free, and contrib.

The main section forms the Debian GNU/Linux distribution.

Packages in the other sections are not considered as part of the Debian distribution, though we support their use, and we provide infrastructure for them (such as our bug-tracking system and mailing lists). This Debian Policy Manual applies to these packages as well.


2.1 Package copyright and sections

The aims of this policy are:

2.1.1 The Debian Free Software Guidelines

The Debian Free Software Guidelines (DFSG) as is our definition of `free' software.
>Free Redistribution
The license of a Debian component may not restrict any party from selling or giving away the software as a component of an aggregate software distribution containing programs from several different sources. The license may not require a royalty or other fee for such sale.

Source Code
The program must include source code, and must allow distribution in source code as well as compiled form.

Derived Works
The license must allow modifications and derived works, and must allow them to be distributed under the same terms as the license of the original software.

Integrity of The Author's Source Code
The license may restrict source-code from being distributed in modified form only if the license allows the distribution of ``patch files'' with the source code for the purpose of modifying the program at build time. The license must explicitly permit distribution of software built from modified source code. The license may require derived works to carry a different name or version number from the original software. (This is a compromise. The Debian group encourages all authors to not restrict any files, source or binary, from being modified.)

No Discrimination Against Persons or Groups
The license must not discriminate against any person or group of persons.

No Discrimination Against Fields of Endeavor
The license must not restrict anyone from making use of the program in a specific field of endeavor. For example, it may not restrict the program from being used in a business, or from being used for genetic research.

Distribution of License
The rights attached to the program must apply to all to whom the program is redistributed without the need for execution of an additional license by those parties.

License Must Not Be Specific to Debian
The rights attached to the program must not depend on the program's being part of a Debian system. If the program is extracted from Debian and used or distributed without Debian but otherwise within the terms of the program's license, all parties to whom the program is redistributed should have the same rights as those that are granted in conjunction with the Debian system.

License Must Not Contaminate Other Software
The license must not place restrictions on other software that is distributed along with the licensed software. For example, the license must not insist that all other programs distributed on the same medium must be free software.

Example Licenses
The ``GPL,'' ``BSD,'' and ``Artistic'' licenses are examples of licenses that we consider free.


2.1.2 The main section

Every package in "main" must comply with the DFSG (Debian Free Software Guidelines).

In addition, the packages in "main"


2.1.3 The contrib section

Every package in "contrib" must comply with the DFSG.

Examples of packages which would be included in "contrib" are


2.1.4 The non-free section

`Non-free' contains packages which are not compliant with the DFSG or which are encumbered by patents or other legal issues that make their distribution problematic.

All packages in `non-free' must be electronically distributable across international borders.


2.1.5 The non-us server

Some programs with cryptographic program code must be stored on the "non-us" server because of export restrictions of the U.S.

This applies only to packages which contain cryptographic code. A package containing a program with an interface to a cryptographic program or a program that's dynamically linked against a cryptographic library can be distributed if it is capable of running without the cryptography library or program.


2.1.6 Further copyright considerations

Every package must be accompanied by a verbatim copy of its copyright and distribution license in the file /usr/doc/<package-name>/copyright (see Copyright information, section 6.5 for details).

We reserve the right to restrict files from being included anywhere in our archives if

Programs whose authors encourage the user to make donations are fine for the main distribution, provided that the authors do not claim that not donating is immoral, unethical, illegal or something similar; otherwise they must go in contrib (or non-free, if even distribution is restricted by such statements).

Packages whose copyright permission notices (or patent problems) do not allow redistribution even of only binaries, and where no special permission has been obtained, cannot be placed on the Debian FTP site and its mirrors at all.

Note, that under international copyright law (this applies in the United States, too) no distribution or modification of a work is allowed without an explicit notice saying so. Therefore a program without a copyright notice is copyrighted and you may not do anything to it without risking being sued! Likewise if a program has a copyright notice but no statement saying what is permitted then nothing is permitted.

Many authors are unaware of the problems that restrictive copyrights (or lack of copyright notices) can cause for the users of their supposedly-free software. It is often worthwhile contacting such authors diplomatically to ask them to modify their license terms. However, this is a politically difficult thing to do and you should ask for advice on debian-devel first.

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


2.1.7 Subsections

The packages in the main, contrib, and non-free sections are grouped further into subsections to simplify handling of them.

The section for each package is specified in the package's control record. However, the maintainer of the Debian archive may override this selection to assure the consistency of the Debian distribution.

Please check the current Debian distribution to see which sections are available.


2.2 Priorities

Each package is given a certain priority value, which is included in the package's control record. This information is used in the Debian package management tool to separate high-priority packages from less-important packages.

The following priority levels are supported by the Debian package management system, dpkg.

required
required packages are necessary for the proper functioning of the system. You must not remove these packages or your system may become totally broken and you may not even be able to use dpkg to put things back. Systems with only the required packages are probably unusable, but they do have enough functionality to allow the sysadmin to boot and install more software.

important
Important programs, including those which one would expect to find on any Unix-like system. If the expectation is that an experienced Unix person who found it missing would say `What the F*!@<+ is going on, where is foo', it should be in important. This is an important criterion because we are trying to produce, amongst other things, a free Unix. Other packages without which the system will not run well or be usable should also be here. This does not include Emacs or X11 or TeX or any other large applications. The important packages are just a bare minimum of commonly-expected and necessary tools.

standard
These packages provide a reasonably small but not too limited character-mode system. This is what will install by default if the user doesn't select anything else. It doesn't include many large applications, but it does include Emacs (this is more of a piece of infrastructure than an application) and a reasonable subset of TeX and LaTeX (if this is possible without X).

optional
(In a sense everything is optional that isn't required, but that's not what is meant here.) This is all the software that you might reasonably want to install if you didn't know what it was or don't have specialised requirements. This is a much larger system and includes X11, a full TeX distribution, and lots of applications.

extra
This contains packages that conflict with others with higher priorities, or are only likely to be useful if you already know what they are or have specialised requirements.

Packages may not depend on packages with lower priority values. If this should happen, one of the priority values will have to be adapted.


2.3 Binary packages

The Debian GNU/Linux distribution is based on the Debian package management system, called dpkg. Thus, all packages in the Debian distribution have to be provided in the .deb file format.

2.3.1 The package name

Every package must have a name that's unique within the Debian archive.

Package names may only consist of lower case letters, digits (0-9), plus (+) or minus (-) signs, and periods (.).

The package name is part of the file name of the .deb file and is included in the control field information.


2.3.2 The maintainer of a package

Every package must have exactly one maintainer at a time. This person is responsible that the license of the package's software complies with the policy of the distribution this package is included in.

The maintainer must be specified in the Maintainer control field with the correct name and a working email address for the Debian maintainer of the package. If one person maintains several packages he/she should try to avoid having different forms of their name and email address in different Maintainer fields.

If the maintainer of a package quits from the Debian project the Debian QA Group takes over the maintainership of the package until someone else volunteers for that task. These packages are called orphaned packages.


2.3.3 The description of a package

Every Debian package should have an extended description stored in the appropriate field of the control record.

The description should be written so that it tells the user what they need to know to decide whether to install the package. This description should not just be copied from the blurb for the program. Instructions for configuring or using the package should not be included--that is what installation scripts, manual pages, Info files, etc. are for. Copyright statements and other administrivia should not be included--that is what the copyright file is for.


2.3.4 Dependencies

Every package has to specify the dependency information about other packages, that are required for the first to work correctly.

For example, for any shared libraries required by dynamically-linked executable binary in a package a dependency entry has to be provided.

It is not necessary for other packages to declare any dependencies they have on other packages which are marked Essential (see below).

Sometimes, a package requires another package to be installed and configured before it can be installed. In this case, you'll have to specify a Pre-Depends entry for the package.

You must not specify a Pre-Depends entry for a package before this has been discussed on the debian-devel mailing list and a consensus about doing that has been reached.


2.3.5 Virtual packages

Sometimes, there are several packages doing more-or-less the same job. In this case, it's useful to define a virtual package who's name describes the function the packages have. (The virtual packages just exist logically, not physically--that's why they are called virtual.) The packages with this particular function will then provide the virtual package. Thus, any other package requiring that function can simply depend on the virtual package without having to specify all possible packages individually.

All packages must use virtual package names where appropriate, and arrange to create new ones if necessary. They must not use virtual package names (except privately, amongst a cooperating group of packages) unless they have been agreed upon and appear in the list of virtual package names.

The latest version of the authoritative list of virtual package names can be found on ftp.debian.org in /debian/doc/package-developer/virtual-package-names-list.text or your local mirror. In addition, it is included in the debian-policy package. The procedure for updating the list is described at the top of the file.


2.3.6 Base packages

The packages included in the base section have a special function. They form a minimum subset of the Debian GNU/Linux system that is installed before everything else on a new system. Thus, only very few packages are allowed to go into the base section to keep the required disk usage very small.

Most of these packages should have the priority value required or at least important, and many of them will be tagged essential (see below).

You must not place any packages into the base section before this has been discussed on the debian-devel mailing list and a consensus about doing that has been reached.


2.3.7 Essential packages

Some packages are tagged essential. (They have Essential: yes in their package control record.) This flag is used for packages that are essential for a system.

Since these packages can not easily be removed (you'll have to specify an extra force option to dpkg) this flag should only be used where absolutely necessary. A shared library package should not be tagged essential--the dependencies will prevent its premature removal, and we need to be able to remove it when it has been superseded.

You must not tag any packages essential before this has been discussed on the debian-devel mailing and a consensus about doing that has been reached.


2.3.8 Maintainer scripts

The package installation 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 ever be asked each question once. This means that packages should try to use appropriate shared configuration files (such as /etc/papersize and /etc/nntpserver), 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/package/copyright); neither do instructions on how to use a program (these should be in on line documentation, where all the users can see them).

Any necessary prompting should almost always be confined to the post-installation script, and should be protected with a conditional so that unnecessary prompting doesn't happen if a package's installation fails and the postinst is called with abort-upgrade, abort-remove or abort-deconfigure.

Errors which occur during the execution of an installation script must be checked and the installation must not continue after an error.

Note, that Scripts, section 4.4, in general applies to package maintainer scripts, too.

Do not use dpkg-divert on a file belonging to another package without consulting the maintainer of that package first.

In order for update-alternatives to work correctly all the packages which supply an instance of the `shared' command name (or, in general, filename) must use it. You can use Conflicts to force the deinstallation of other packages supplying it which do not (yet) use update-alternatives. It may in this case be appropriate to specify a conflict on earlier versions on something--this is an exception to the usual rule that this is not allowed.


2.4 Source packages


2.4.1 Standards conformance

You should specify the most recent version of the packaging standards with which your package complies in the source package's Standards-Version field.

This value will be used to file bug reports automatically if your package becomes too much out of date.

The value corresponds to a version of the Debian manuals, as can be found on the title page or page headers and footers (depending on the format).

The version number has four components--major and minor number and major and minor patch level. When the standards change in a way that requires every package to change the major number will be changed. Significant changes that will require work in many packages will be signaled by a change to the minor number. The major patch level will be changed for any change to the meaning of the standards, however small; the minor patch level will be changed when only cosmetic, typographical or other edits which do not change the meaning are made, or changes which do not affect the contents of packages.

You should regularly, and especially if your package has become out of date, check for the newest Policy Manual available and update your package, if necessary. When your package complies with the new standards you may update the Standards-Version source package field and release it.


2.4.2 Changes to the upstream sources

If changes to the source code are made that are generally applicable please try to get them included in the upstream version of the package by supplying the upstream authors with the changes in whatever form they prefer.

If you need to configure the package differently for Debian or for Linux, and the upstream source doesn't provide a way to configure it the way you need to, please add such configuration facilities (for example, a new autoconf test or #define) and send the patch to the upstream authors, with the default set to the way they originally had it. You can then easily override the default in your debian/rules or wherever is appropriate.

Please make sure that the configure utility detects the correct architecture specification string (refer to Architecture specification strings, section 5.1 for details).

If you need to edit a Makefile where GNU-style 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.


2.4.3 Documenting your changes

Document your changes and updates to the source package properly in the debian/changelog file.

A copy of the file which will be installed in /usr/doc/package/copyright should be in debian/copyright.

In non-experimental packages you may only use a format for debian/changelog which is supported by the most recent released version of dpkg. If your format is not supported and there is general support for it you should contact the dpkg maintainer to have the parser script for your format included in the dpkg package. (You will need to agree that the parser and its manpage may be distributed under the GNU GPL, just as the rest of dpkg is.)


2.4.4 Error trapping in makefiles

When make invokes a command in a makefile (including your package's upstream makefiles and the debian/rules) it does so using sh. This means that sh's usual bad error handling properties apply: if you include a miniature script as one of the commands in your makefile you'll find that if you don't do anything about it then errors are not detected and make will blithely continue after problems.

Every time you put more than one shell command (this includes using a loop) in a makefile command you must make sure that errors are trapped. For simple compound commands, such as changing directory and then running a program, using && rather than semicolon as a command separator is sufficient. For more complex commands including most loops and conditionals you must include a separate set -e command at the start of every makefile command that's actually one of these miniature shell scripts.


2.4.5 Obsolete constructs and libraries

The include file <varargs.h> is provided to support end-users compiling very old software; the library libtermcap is provided to support the execution of software which has been linked against it (either old programs or those such as Netscape which are only available in binary form).

Debian packages should be ported to include <stdarg.h> and ncurses when they are built.


Debian Policy Manual - Copyright ©1996,1997,1998 Ian Jackson and Christian Schwarz.
Contents; abstract; next; back.
version 2.5.0.0, 1998-10-30
Ian Jackson ijackson@gnu.ai.mit.edu
Christian Schwarz schwarz@debian.org
revised: David A. Morris bweaver@debian.org
The Debian Policy mailing List debian-policy@lists.debian.org