Informally, the criteria used for inclusion is that the material meet one of the following requirements:
Please note that these are not mutually exclusive; selected conventions often become parts of standard interfaces.
Compare RFC 2119. Note, however, that these words are used in a different way in this document.
It is possible that there are policy requirements which the package is unable to meet, for example, if the source is unavailable. These situations will need to be handled on a case-by-case basis.
This is an important criterion because we are trying to produce, amongst other things, a free Unix.
The detailed procedure for doing this gracefully can be found in the Debian
Developer's Reference, either in the developers-reference package,
or on the Debian FTP server ftp.debian.org as /debian/doc/package-developer/developers-reference.txt.gz
or from the Debian
Developer's Reference webpage.
4% of Debian packages [see Debconf stats]
currently use debconf to prompt the user at install time, and this
number is growing daily. The benefits of using debconf are briefly explained
at Debconf
introduction; they include preconfiguration, (mostly) noninteractive
installation, elimination of redundant prompting, consistency of user
interface, etc.
With this increasing number of packages using debconf, plus the
existance of a nascent second implementation of the Debian configuration
management system (cdebconf), and the stabalization of the
protocol these things use, the time has finally come to reflect the use of
these things in policy.
Debconf or another tool that implements the Debian Configuration
management specification will also be installed, and any versioned dependencies
on it will be satisfied before preconfiguration begins.
In the past, people specified the full version number in the Standards-Version field, for example `2.3.0.0'. Since minor patch-level changes don't introduce new policy, it was thought it would be better to relax policy and only require the first 3 components to be specified, in this example `2.3.0'. All four components may still be used if someone wishes to do so.
See the file upgrading-checklist for information about policy which has changed between different versions of this document.
Rationale:
The reason for this is that dependencies change, and you should list all those
packages, and only those packages that you need directly.
What others need is their business. For example, if you only link against
libimlib, you will need to build-depend on
libimlib2-dev but not against any libjpeg* packages,
even though libimlib2-dev currently depends on them: installation
of libimlib2-dev will automatically ensure that all of its
run-time dependencies are satisfied.
If you wish to use an alternative format, you may do so as long as you include
a parser for it in your source package. The parser must have an API compatible
with that expected by dpkg-genchanges and
dpkg-gencontrol. If there is general interest in the new format,
you should contact the dpkg maintainer to have the parser script
for it 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.)
Current distribution names are:
You should list all distributions that the package should be installed into.
Alphanumerics are A-Za-z0-9 only.
The rationale is that there is some information conveyed by knowing the age of the file, for example, you could recognize that some documentation is very old by looking at the modification time, so it would be nice if the modification time of the upstream source would be preserved.
Another common way to do this is for build to depend on
build-stamp and to do nothing else, and for the
build-stamp target to do the building and to touch
build-stamp on completion. This is especially useful if the build
routine creates a file or directory called build; in such a case,
build will need to be listed as a phony target (i.e., as a
dependency of the .PHONY target). See the documentation of
make for more information on phony targets.
The fakeroot package often allows one to build a package correctly
even without being root.
Though there is nothing stopping an author who is also the Debian maintainer from using it for all their changes, it will have to be renamed if the Debian and upstream maintainers become different people. In such a case, however, it might be better to maintain the package as a non-native package.
Recognised urgency values are low, medium, high and emergency. They have an effect on how quickly a package will be considered for inclusion into the testing distribution, and give an indication of the importance of any fixes included in this upload.
To be precise, the string should match the following Perl regular expression:
/closes:\s*(?:bug)?\#?\s?\d+(?:,\s*(?:bug)?\#?\s?\d+)*/i
Then all of the bug numbers listed will be closed by the archive maintenance
script (katie), or in the case of an NMU, marked as fixed.
This is generated by the 822-date program.
files.new is used as a temporary file by
dpkg-gencontrol and dpkg-distaddfile - they write a
new version of files here before renaming it, to avoid leaving a
corrupted copy if an error occurs
This is not currently detected when building source packages, but only when extracting them.
Hard links may be permitted at some point in the future, but would require a fair amount of work.
Setgid directories are allowed.
The blurb that comes with a program in its announcements and/or
README files is rarely suitable for use in a description. It is
usually aimed at people who are already in the community where the package is
used.
This is so that if an error occurs, the user interrupts dpkg or
some other unforeseen circumstance happens you don't leave the user with a
badly-broken package when dpkg attempts to repeat the action.
Part of the problem is due to what is arguably a bug in dpkg.
The package management system requires the library to be placed before the
symbolic link pointing to it in the .deb file. This is so that
when dpkg comes to install the symlink (overwriting the previous
symlink pointing at an older version of the library), the new shared library is
already in place. In the past, this was achieved by creating the library in
the temporary packaging directory before creating the symlink. Unfortunately,
this was not always effective, since the building of the tar file in the
.deb depended on the behavior of the underlying file system. Some
file systems (such as reiserfs) reorder the files so that the order of creation
is forgotten. Starting with release 1.7.0, dpkg will
reorder the files itself as necessary when building a package. Thus it is no
longer important to concern oneself with the order of file creation.
These are currently
In the past, the shared libraries linked to were determined by calling
ldd, but now objdump is used to do this. The only
change this makes to package building is that dpkg-shlibdeps must
also be run on shared libraries, whereas in the past this was unnecessary. The
rest of this footnote explains the advantage that this method gives.
We say that a binary foo directly uses a library libbar if it is explicitly linked with that library (that is, it uses the flag -lbar during the linking stage). Other libraries that are needed by libbar are linked indirectly to foo, and the dynamic linker will load them automatically when it loads libbar. A package should depend on the libraries it directly uses, and the dependencies for those libraries should automatically pull in the other libraries.
Unfortunately, the ldd program shows both the directly and
indirectly used libraries, meaning that the dependencies determined included
both direct and indirect dependencies. The use of objdump avoids
this problem by determining only the directly used libraries.
A good example of where this helps is the following. We could update
libimlib with a new version that supports a new graphics format
called dgf (but retaining the same major version number). If we used the old
ldd method, every package that uses libimlib would
need to be recompiled so it would also depend on libdgf or it
wouldn't run due to missing symbols. However with the new system, packages
using libimlib can rely on libimlib itself having the
dependency on libdgf and so they would not need rebuilding.
An example may help here. Let us say that the source package foo
generates two binary packages, libfoo2 and
foo-runtime. When building the binary packages, the two packages
are created in the directories debian/libfoo2 and
debian/foo-runtime respectively. (debian/tmp could
be used instead of one of these.) Since libfoo2 provides the
libfoo shared library, it will require a shlibs file,
which will be installed in debian/libfoo2/DEBIAN/shlibs,
eventually to become /var/lib/dpkg/info/libfoo2.shlibs. Then when
dpkg-shlibdeps is run on the executable
debian/foo-runtime/usr/bin/foo-prog, it will examine the
debian/libfoo2/DEBIAN/shlibs file to determine whether
foo-prog's library dependencies are satisfied by any of the
libraries provided by libfoo2. For this reason,
dpkg-shlibdeps must only be run once all of the individual binary
packages' shlibs files have been installed into the build
directory.
If you are using debhelper, the dh_shlibdeps program
will do this work for you. It will also correctly handle multi-binary
packages.
This can be determined using the command
objdump -p /usr/lib/libz.so.1.1.3 | grep SONAME
This is what dh_makeshlibs in the debhelper suite
does.
Rationale: Using -g by default causes wasted CPU cycles since the information is stripped away anyway; this can have a significant impact on the efficiency of the autobuilders. Having a standard way to build a debugging variant also makes it easier to build debugging bins and libraries since it provides a documented way of getting this type of build; one does not have to manually edit debian/rules or Makefiles.
You might also want to use the options --remove-section=.comment and --remove-section=.note on both shared libraries and executables, and --strip-debug on static libraries.
A common example are the so-called ``plug-ins'', internal shared objects that
are dynamically loaded by programs using dlopen(3).
Although libtool is fully capable of linking against shared
libraries which don't have .la files, as it is a mere shell script
it can add considerably to the build time of a libtool-using
package if that shell script has to derive all this information from first
principles for each library every time it is linked. With the advent of
libtool version 1.4 (and to a lesser extent libtool
version 1.3), the .la files also store information about
inter-library dependencies which cannot necessarily be derived after the
.la file is deleted.
The soname is the shared object name: it's the thing that has to match exactly between building an executable and running it for the dynamic linker to be able run the program. For example, if the soname of the library is libfoo.so.6, the library package would be called libfoo6.
Debian policy specifies POSIX behavior for /bin/sh, but echo -n has widespread use in the Linux community (in particular including this policy, the Linux kernel source, many Debian scripts, etc.). This echo -n mechanism is valid but not required under POSIX, hence this explicit addition. Also, rumour has it that this shall be mandated under the LSB anyway.
It can also be found on http://www.cpan.org/doc/FMTEYEWTK/versus/csh.whynot
or on the ftp site ftp.cpan.org as /pub/perl/CPAN/doc/FMTEYEWTK/versus/csh.whynot.
Rationale: There are two problems with hard links. The first is that some
editors break the link while editing one of the files, so that the two files
may unwittingly become unlinked and different. The second is that
dpkg might break the hard link while upgrading
conffiles.
The traditional approach to log files has been to set up ad hoc log rotation schemes using simple shell scripts and cron. While this approach is highly customizable, it requires quite a lot of sysadmin work. Even though the original Debian system helped a little by automatically installing a system which can be used as a template, this was deemed not enough.
The use of logrotate, a program developed by Red Hat, is better,
as it centralizes log management. It has both a configuration file
(/etc/logrotate.conf) and a directory where packages can drop
their individual log rotation configurations (/etc/logrotate.d).
Ordinary files installed by dpkg (as opposed to
conffiles and other similar objects) normally have their
permissions reset to the distributed permissions when the package is
reinstalled. However, the use of dpkg-statoverride overrides this
default behaviour. If you use this method, you should remember to describe
dpkg-statoverride in the package documentation; being a relatively
new addition to Debian, it is probably not yet well-known.
The following architectures and operating systems are currently recognised by
dpkg-archictecture. The architecture,
arch, is one of the following: alpha,
arm, hppa, i386, ia64,
m68k, mips, mipsel,
powerpc, s390, sh, sheb,
sparc and sparc64. The operating system,
os, is one of: linux, gnu,
freebsd and openbsd. Use of gnu in this
string is reserved for the GNU/Hurd operating system.
The Debian base system already provides an editor and a pager program,
If it is not possible to establish both locks, the system shouldn't wait for the second lock to be established, but remove the first lock, wait a (random) time, and start over locking again.
You will need to depend on liblockfile1 (>>1.01) to use these functions.
This implements current practice, and provides an actual policy for usage of the xserver virtual package which appears in the virtual packages list. In a nutshell, X servers that interface directly with the display and input hardware or via another subsystem (e.g., GGI) should provide xserver. Things like Xvfb, Xnest, and Xprt should not.
"New terminal window" does not necessarily mean a new top-level X window directly parented by the window manager; it could, if the terminal emulator application were so coded, be a new "view" in a multiple-document interface (MDI).
For the purposes of Debian Policy, a "font for the X Window System" is one which is accessed via X protocol requests. Fonts for the Linux console, for PostScript renderers, or any other purpose, do not fit this definition. Any tool which makes such fonts available to the X Window System, however, must abide by this font policy.
This is because the X server may retrieve fonts from the local filesystem or over the network from an X font server; the Debian package system is empowered to deal only with the local filesystem.
Note that this mechanism is not the same as using app-defaults; app-defaults are tied to the client binary on the local filesystem, whereas X resources are stored in the X server and affect all connecting clients.
Imake-using programs are exempt because, as long as they are
written correctly, the pathnames they use to locate resources and install
themselves are derived wholly from the X Window System configuration. Thus, in
the event that the X Window System moves to /usr/X11R7/,
/usr/X12/, or just plain /usr/, all that is required
for these programs is a recompile against the corresponding X Window System
library development packages.
OSF/Motif and OpenMotif are collectively referred to as "Motif" in this policy document.
Supporting this in man often requires unreasonable processing time
to find a manual page or to report that none exists, and moves knowledge into
man's database that would be better left in the filesystem. This support is
therefore deprecated and will cease to be present in the future.
These symlinks will be removed in the future, but they have to be there for compatibility reasons until all packages have moved and the policy is changed accordingly.
The debhelper script dh_installdocs does this
automatically.
The rationale: The important thing here is that HTML docs should be available in some package, not necessarily in the main binary package.
Rationale: People should not have to look in places for upstream changelogs merely because they are given different names or are distributed in HTML format.
dpkg is targetted primarily at Debian GNU/Linux, but may work on
or be ported to other systems.
That means that if it runs successfully or fails and then you call it again it doesn't bomb out, but just ensures that everything is the way it ought to be.
This field should appear in all packages, though dpkg doesn't
require it yet so that old packages can still be installed.
The rationale is that there is some information conveyed by knowing the age of the file, for example, you could recognize that some documentation is very old by looking at the modification time, so it would be nice if the modification time of the upstream source would be preserved.
This is so that the control file which is produced has the right permissions
In a forthcoming dpkg version, dpkg-shlibdeps would be required to
be called on shared libraries as well.
They may be specified either in the locations in the source tree where they are created or in the locations in the temporary build tree where they are installed prior to binary package creation.
Though there is nothing stopping an author who is also the Debian maintainer from using it for all their changes, it will have to be renamed if the Debian and upstream maintainers become different people.
This is generated by the 822-date program.
files.new is used as a temporary file by
dpkg-gencontrol and dpkg-distaddfile - they write a
new version of files here before renaming it, to avoid leaving a
corrupted copy if an error occurs
This is not currently detected when building source packages, but only when extracting them.
Hard links may be permitted at some point in the future, but would require a fair amount of work.
Setgid directories are allowed.
Renaming a file is not treated specially - it is seen as the removal of the old file (which generates a warning, but is otherwise ignored), and the creation of the new one.
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
This is a bug.
It is usual to leave a space after the package name if a version number is specified.
A space after each comma is conventional.
That is, the parts which are not the .dsc.
Debian Policy Manual
version 3.5.6.1, 2002-03-14ijackson@gnu.ai.mit.eduschwarz@debian.orgbweaver@debian.orgdebian-policy@lists.debian.org