The Debian GNU/Linux system is maintained and distributed as a collection of packages. Since there are so many of them (currently well over 6000), they are split into sections and given priorities to simplify the 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 the Debian Free Software Guidelines, below), or may be imported/exported without restrictions. Thus, the archive is split into the sections main, non-free, contrib, non-US/main, non-US/non-free, and non-US/contrib. The sections are explained in detail below.
The main and the non-US/main sections together form the Debian GNU/Linux distribution.
Packages in the other sections are not considered to be part of the Debian distribution, although we support their use and provide infrastructure for them (such as our bug-tracking system and mailing lists). This Debian Policy Manual applies to these packages as well.
The aims of this section are:
The Debian Free Software Guidelines (DFSG) form our definition of `free software'. These are:
Every package in main and non-US/main must comply with the DFSG (Debian Free Software Guidelines).
In addition, the packages in main
Similarly, the packages in non-US/main
Every package in contrib and non-US/contrib must comply with the DFSG.
In addition, the packages in contrib and non-US/contrib
Furthermore, packages in contrib must not require a package in a non-US section for compilation or execution.
Examples of packages which would be included in contrib or non-US/contrib are:
Packages must be placed in non-free or non-US/non-free if they are not compliant with the DFSG or are encumbered by patents or other legal issues that make their distribution problematic.
In addition, the packages in non-free and non-US/non-free
Some programs with cryptographic program code need to be stored on the non-US server because of United States export restrictions. Such programs must be distributed in the appropriate non-US section, either non-US/main, non-US/contrib or non-US/non-free.
This applies only to packages which contain cryptographic code. A package containing a program with an interface to a cryptographic program or a program that's dynamically linked against a cryptographic library should not be distributed via the non-US server if it is capable of running without the cryptographic library or program.
Every package must be accompanied by a verbatim copy of its copyright and distribution license in the file /usr/share/doc/package/copyright (see Copyright information, Section 13.6 for further 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; in such a case they must go in non-free.
Packages whose copyright permission notices (or patent problems) do not even allow redistribution of binaries only, and where no special permission has been obtained, must not be placed on the Debian FTP site and its mirrors at all.
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 can be a politically difficult thing to do and you should ask for advice on the debian-legal mailing list first, as explained below.
When in doubt about a copyright, send mail to debian-legal@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'.
The packages in the sections main, contrib and non-free are grouped further into subsections to simplify handling.
The section and subsection for each package should be specified in the package's Section control record. However, the maintainer of the Debian archive may override this selection to ensure the consistency of the Debian distribution. The Section field should be of the form:
The Debian archive maintainers provide the authoritative list of subsections. At present, they are: admin, base, comm, contrib, devel, doc, editors, electronics, games, graphics, hamradio, interpreters, libs, mail, math, misc, net, news, non-US, non-free, oldlibs, otherosfs, science, shells, sound, tex, text, utils, web, x11.
Each package should have a priority value, which is included in the package's control record. This information is used by the Debian package management tools to separate high-priority packages from less-important packages.
The following priority levels are recognised by the Debian package management tools.
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.
foo?', it must be an important package.[4] Other packages without which the
system will not run well or be usable must also have priority
important. This does not include Emacs, the X Window
System, TeX or any other large applications. The important
packages are just a bare minimum of commonly-expected and necessary tools.
Packages must not depend on packages with lower priority values (excluding build-time dependencies). In order to ensure this, the priorities of one or more packages may need to be adjusted.
The Debian GNU/Linux distribution is based on the Debian package management
system, called dpkg. Thus, all packages in the Debian
distribution must be provided in the .deb file format.
Every package must have a name that's unique within the Debian archive.
Package names must consist of lower case letters (a-z), digits (0-9), plus (+) and minus (-) signs, and periods (.). They must be at least two characters long and must contain at least one letter.
The package name is part of the file name of the .deb file and is included in the control field information.
Every package must have a Debian maintainer (the maintainer may be one person or a group of people reachable from a common email address, such as a mailing list). The maintainer is responsible for ensuring that the package is placed in the appropriate distributions.
The maintainer must be specified in the Maintainer control field with their correct name and a working email address. If one person maintains several packages, he/she should try to avoid having different forms of their name and email address in the Maintainer fields of those packages.
If the maintainer of a package quits from the Debian project, "Debian QA
Group" packages@qa.debian.org takes
over the maintainership of the package until someone else volunteers for that
task. These packages are called orphaned packages.[5]
Every Debian package must have an extended description stored in the appropriate field of the control record.
The description should be written so that it gives the system administrator enough information to decide whether to install the package. This description should not just be copied verbatim from the program's documentation. Instructions for configuring or using the package should not be included (that is what installation scripts, manual pages, info files, etc., are for). Copyright statements and other administrivia should not be included either (that is what the copyright file is for).
Every package must specify the dependency information about other packages that are required for the first to work correctly.
For example, a dependency entry must be provided for any shared libraries required by a dynamically-linked executable binary in a package.
Packages are not required to declare any dependencies they have on other packages which are marked Essential (see below), and should not do so unless they depend on a particular version of that package.
Sometimes, a package requires another package to be installed and configured before it can be installed. In this case, you must specify a Pre-Depends entry for the package.
You should 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.
Sometimes, there are several packages which offer more-or-less the same functionality. In this case, it's useful to define a virtual package whose name describes that common functionality. (The virtual packages only 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 should use virtual package names where appropriate, and arrange to create new ones if necessary. They should not use virtual package names (except privately, amongst a cooperating group of packages) unless they have been agreed upon and appear in the list of virtual package names.
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.txt
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.
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 will 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.
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 cannot be easily removed (one has to specify an extra
force option to dpkg to do so), this flag must not be
used unless absolutely necessary. A shared library package must not be tagged
essential; dependencies will prevent its premature removal, and we
need to be able to remove it when it has been superseded.
Since dpkg will not prevent upgrading of other packages while an essential package is in an unconfigured state, all essential packages must supply all of their core functionality even when unconfigured. If the package cannot satisfy this requirement it must not be tagged as essential, and any packages depending on this package must instead have explicit dependency fields as appropriate.
You must not tag any packages essential before this has been discussed on the debian-devel mailing list and a consensus about doing that has been reached.
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.
Errors which occur during the execution of an installation script must be checked and the installation must not continue after an error.
Note that in general Scripts, Section 11.4 applies to package maintainer scripts, too.
You should not use dpkg-divert on a file belonging to another package without consulting the maintainer of that package first.
All packages which supply an instance of a common command name (or, in general,
filename) should generally use update-alternatives, so that they
may be installed together. If update-alternatives is not used,
then each package must use Conflicts to ensure that other packages
are de-installed. (In this case, it may be appropriate to specify a conflict
against earlier versions of something that previously did not use
update-alternatives; this is an exception to the usual rule that
versioned conflicts should be avoided.)
Package maintainer scripts may prompt the user if necessary. Prompting may be
accomplished by hand, or by communicating with a program, such as
debconf, which conforms to the Debian Configuration management
specification, version 2 or higher. These are included in the
debconf_specification files in the debian-policy
package. You may also find this file on the FTP site
ftp.debian.org in /debian/doc/package-developer/debconf_specification.txt.gz
or on your local mirror.[6]
Packages which use the Debian Configuration management specification may
contain an additional config script and a templates
file in their control archive. The config script might be run
before the preinst script, and before the package is unpacked or
any of its dependencies or pre-dependancies are satisfied. Therefore it must
work using only the tools present in essential packages.[7]
Packages should try to minimize the amount of prompting they need to do, and
they should ensure that the user will only ever be asked each question once.
This means that packages should try to use appropriate shared configuration
files (such as /etc/papersize and /etc/news/server),
and shared debconf variables 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 config or 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/share/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
config or postinst script. If it is done in the
postinst, it 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.
In the source package's Standards-Version control field, you should specify the most recent version number of this policy document with which your package complied when it was last updated. The current version number is 3.5.6.1.
This information may be used to file bug reports automatically if your package becomes too much out of date.
The version number has four components: major and minor version number and major and minor patch level. When the standards change in a way that requires every package to change the major number will be changed. Significant changes that will require work in many packages will be signaled by a change to the minor number. The major patch level will be changed for any change to the meaning of the standards, however small; the minor patch level will be changed when only cosmetic, typographical or other edits are made which neither change the meaning of the document nor affect the contents of packages.
Thus only the first three components of the policy version are significant in the Standards-Version control field, and so either these three components or the all four components may be specified.[8]
You should regularly, and especially if your package has become out of date, check for the newest Policy Manual available and update your package, if necessary. When your package complies with the new standards you should update the Standards-Version source package field and release it.[9]
Source packages should specify which binary packages they require to be installed or not to be installed in order to build correctly. For example, if building a package requires a certain compiler, then the compiler should be specified as a build-time dependency.
It is not necessary to explicitly specify build-time relationships on a minimal set of packages that are always needed to compile, link and put in a Debian package a standard "Hello World!" program written in C or C++. The required packages are called build-essential, and an informational list can be found in /usr/share/doc/build-essential/list (which is contained in the build-essential package).[10]
When specifying the set of build-time dependencies, one should list only those packages explicitly required by the build. It is not necessary to list packages which are required merely because some other package in the list of build-time dependencies depends on them.[11]
If build-time dependencies are specified, it must be possible to build the package and produce working binaries on a system with only essential and build-essential packages installed and also those required to satisfy the build-time relationships (including any implied relationships). In particular, this means that version clauses should be used rigorously in build-time relationships so that one cannot produce bad or inconsistently configured packages when the relationships are properly satisfied.
If changes to the source code are made that are not specific to the needs of the Debian system, they should be sent to the upstream authors in whatever form they prefer so as to be included in the upstream version of the package.
If you need to configure the package differently for Debian or for Linux, and
the upstream source doesn't provide a way to do so, you should add such
configuration facilities (for example, a new 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.
You should make sure that the configure utility detects the
correct architecture specification string (refer to Architecture specification
strings, Section 12.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.
You should document your changes and updates to the source package properly in the debian/changelog file. (Note that mistakes in changelogs are usually best rectified by making a new changelog entry rather than "rewriting history" by editing old changelog entries.)
In non-experimental packages you must use a format for
debian/changelog which is supported by the most recent released
version of dpkg.[12]
When make invokes a command in a makefile (including your
package's upstream makefiles and 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 should include a separate set -e command at the start of every makefile command that's actually one of these miniature shell scripts.
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 patched to use <stdarg.h> and ncurses instead.
Debian Policy Manual
version 3.5.6.1, 2002-03-14ijackson@gnu.ai.mit.eduschwarz@debian.orgbweaver@debian.orgdebian-policy@lists.debian.org