Debian Policy Manual
Footnotes

Informally, the criteria used for inclusion is that the material meet one of
the following requirements:

Standard interfaces

The material presented represents an interface to the packaging system that is
mandated for use, and is used by, a significant number of packages, and
therefore should not be changed without peer review. Package maintainers can
then rely on this interface not changing, and the package management software
authors need to ensure compatibility with this interface definition. (Control
file and changelog file formats are examples.)

Chosen Convention

If there are a number of technically viable choices that can be made, but one
needs to select one of these options for inter-operability. The version number
format is one example.

Please note that these are not mutually exclusive; selected conventions often
become parts of standard interfaces.

The Debian archive software uses the term "component" internally and
in the Release file format to refer to the division of an archive. The Debian
Social Contract simply refers to "areas." This document uses
terminology similar to the Social Contract.

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.

Essential is needed in part to avoid unresolvable dependency loops on upgrade.
If packages add unnecessary dependencies on packages in this set, the chances
that there will be an unresolvable dependency loop caused by
forcing these Essential packages to be configured first before they need to be
is greatly increased. It also increases the chances that frontends will be
unable to calculate an upgrade path, even if one exists.

Also, functionality is rarely ever removed from the Essential set, but
packages have been removed from the Essential set when the
functionality moved to a different package. So depending on these packages
just in case they stop being essential does way more harm than good.

This allows maintaining the list separately from the policy documents (the list
does not need the kind of control that the policy documents do).

Having a separate package allows one to install the build-essential packages on
a machine, as well as allowing other packages such as tasks to require
installation of the build-essential packages using the depends relation.

The separate package allows bug reports against the list to be categorized
separately from the policy management process in the BTS.

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.

Although there is nothing stopping an author who is also the Debian maintainer
from using this changelog 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.

In the case of a sponsored upload, the uploader signs the files, but the
changelog maintainer name and address are those of the person who prepared this
release. If the preparer of the release is not one of the usual maintainers of
the package (as listed in the Maintainer or Uploaders control
fields of the package), the first line of the changelog is conventionally used
to explain why a non-maintainer is uploading the package. The Debian
Developer's Reference (see Related documents,
Section 1.4) documents the conventions used.

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.

This split allows binary-only builds to not install the dependencies required
for the build-indep target and skip any resource-intensive build
tasks that are only required when building architecture-independent binary
packages.

Having multiple copies of the same code in Debian is inefficient, often creates
either static linking or shared library conflicts, and, most importantly,
increases the difficulty of handling security vulnerabilities in the duplicated
code.

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.

Completely empty lines will not be rendered as blank lines. Instead, they will
cause the parser to think you're starting a whole new record in the control
file, and will therefore likely abort with an error.

Example distribution names in the Debian archive used in .changes
files are:

unstable

This distribution value refers to the developmental part of the Debian
distribution tree. Most new packages, new upstream versions of packages and
bug fixes go into the unstable directory tree.

experimental

The packages with this distribution value are deemed by their maintainers to be
high risk. Oftentimes they represent early beta or developmental packages from
various sources that the maintainers want people to try, but are not ready to
be a part of the other parts of the Debian distribution tree.

Others are used for updating stable releases or for security uploads. More
information is available in the Debian Developer's Reference, section "The
Debian archive".

Other urgency values are supported with configuration changes in the archive
software but are not used in Debian. The urgency affects how quickly a package
will be considered for inclusion into the testing distribution and
gives an indication of the importance of any fixes included in the upload.
Emergency and critical are treated as synonymous.

For example, suppose packages foo and bar are "Installed" with foo
depending on bar. If an upgrade of bar were started and then aborted, and then
an attempt to remove foo failed because its prerm script failed,
foo's postinst abort-remove would be called with bar only
"Half-Installed".

Historical note: Truly ancient (pre-1997) versions of dpkg passed
<unknown> (including the angle brackets) in this case. Even
older ones did not pass a second argument at all, under any circumstance. Note
that upgrades using such an old dpkg version are unlikely to work for other
reasons, even if this old argument behavior is handled by your postinst script.

This approach makes dependency resolution easier. If two packages A and B are
being upgraded, the installed package A depends on exactly the installed
package B, and the new package A depends on exactly the new package B (a common
situation when upgrading shared libraries and their corresponding development
packages), satisfying the dependencies at every stage of the upgrade would be
impossible. This relaxed restriction means that both new packages can be
unpacked together and then configured in their dependency order.

It is possible that a future release of dpkg may add the ability
to specify a version number for each virtual package it provides. This feature
is not yet present, however, and is expected to be used only infrequently.

To see why Breaks is normally needed in addition to
Replaces, consider the case of a file in the package
foo being taken over by the package foo-data.
Replaces will allow foo-data to be installed and take
over that file. However, without Breaks, nothing requires
foo to be upgraded to a newer version that knows it does not
include that file and instead depends on foo-data. Nothing would
prevent the new foo-data package from being installed and then
removed, removing the file that it took over from foo. After that
operation, the package manager would think the system was in a consistent
state, but the foo package would be missing one of its files.

There is no Build-Depends-Arch; this role is essentially met with
Build-Depends. Anyone building the build-indep and
binary-indep targets is assumed to be building the whole package,
and therefore installation of all build dependencies is required.

The autobuilders use dpkg-buildpackage -B, which calls
build, not build-arch since it does not yet know how
to check for its existence, and binary-arch. The purpose of the
original split between Build-Depends and
Build-Depends-Indep was so that the autobuilders wouldn't need to
install extra packages needed only for the binary-indep targets. But without a
build-arch/build-indep split, this didn't work, since most of the work is done
in the build target, not in the binary target.

This is a convention of shared library versioning, but not a requirement. Some
libraries use the SONAME as the full library file name instead and
therefore do not need a symlink. Most, however, encode additional information
about backwards-compatible revisions as a minor version number in the file
name. The SONAME itself only changes when binaries linked with
the earlier version of the shared library may no longer work, but the filename
may change with each release of the library. See Run-time shared libraries, Section 8.1 for
more information.

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. Since version 1.7.0, dpkg reorders the files itself
as necessary when building a package. Thus it is no longer important to
concern oneself with the order of file creation.

During install or upgrade, the preinst is called before the new files are
unpacked, so calling "ldconfig" is pointless. The preinst of an
existing package can also be called if an upgrade fails. However, this happens
during the critical time when a shared libs may exist on-disk under a temporary
name. Thus, it is dangerous and forbidden by current policy to call
"ldconfig" at this time.

When a package is installed or upgraded, "postinst configure" runs
after the new files are safely on-disk. Since it is perfectly safe to invoke
ldconfig unconditionally in a postinst, it is OK for a package to simply put
ldconfig in its postinst without checking the argument. The postinst can also
be called to recover from a failed upgrade. This happens before any new files
are unpacked, so there is no reason to call "ldconfig" at this point.

For a package that is being removed, prerm is called with all the files intact,
so calling ldconfig is useless. The other calls to "prerm" happen in
the case of upgrade at a time when all the files of the old package are
on-disk, so again calling "ldconfig" is pointless.

postrm, on the other hand, is called with the "remove" argument just
after the files are removed, so this is the proper time to call
"ldconfig" to notify the system of the fact that the shared libraries
from the package are removed. The postrm can be called at several other times.
At the time of "postrm purge", "postrm abort-install", or
"postrm abort-upgrade", calling "ldconfig" is useless
because the shared lib files are not on-disk. However, when "postrm"
is invoked with arguments "upgrade", "failed-upgrade", or
"disappear", a shared lib may exist on-disk under a temporary
filename.

This wording allows the development files to be split into several packages,
such as a separate architecture-independent
libraryname-headers, provided that the development
package depends on all the required additional packages.

A shlibs file represents an SONAME as a library name and version
number, such as libfoo VERSION, instead of recording the actual
SONAME. If the SONAME doesn't match one of the two expected formats
(libfoo-VERSION.so or libfoo.so.VERSION), it cannot
be represented.

The easiest way to call dpkg-shlibdeps correctly is to use a
package helper framework such as debhelper. If you are using
debhelper, the dh_shlibdeps program will do this work
for you. It will also correctly handle multi-binary packages.

Again, dh_shlibdeps and dh_gencontrol will handle
everything except the addition of the variable to the control file for you if
you're using debhelper, including generating separate
substvars files for each binary package and calling
dpkg-gencontrol with the appropriate flags.

A good example of where this helps is the following. We could update
libimlib with a new version that supports a new revision of a
graphics format called dgf (but retaining the same major version number) and
depends on a new library package libdgf4 instead of the older
libdgf3. If we used ldd to add dependencies for
every library directly or indirectly linked with a binary, every package that
uses libimlib would need to be recompiled so it would also depend
on libdgf4 in order to retire the older libdgf3
package. Since dependencies are only added based on ELF NEEDED
attribute, packages using libimlib can rely on
libimlib itself having the dependency on an appropriate version of
libdgf and do not need rebuilding.

An example of an "unreasonable" program is one that uses library
interfaces that are documented as internal and unsupported. If the only
programs or libraries affected by a change are "unreasonable" ones,
other techniques, such as declaring Breaks relationships with
affected packages or treating their usage of the library as bugs in those
packages, may be appropriate instead of changing the SONAME. However, the
default approach is to change the SONAME for any change to the ABI that could
break a program.

An example may clarify. Suppose the source package foo generates
two binary packages, libfoo2 and foo-runtime. When
building the binary packages, the contents of the packages are staged 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 contain a symbols file, which will be installed in
debian/libfoo2/DEBIAN/symbols, eventually to be included as a
control file in that package. When dpkg-shlibdeps is run on the
executable debian/foo-runtime/usr/bin/foo-prog, it will examine
the debian/libfoo2/DEBIAN/symbols file to determine whether
foo-prog's library dependencies are satisfied by any of the
libraries provided by libfoo2. Since those binaries were linked
against the just-built shared library as part of the build process, the
symbols file for the newly-built libfoo2 must take
precedence over a symbols file for any other libfoo2
package already installed on the system.

An example of where this may be needed is with a library that implements the
libGL interface. All GL implementations provide the same set of base
interfaces, and then may provide some additional interfaces only used by
programs that require that specific GL implementation. So, for example,
libgl1-mesa-glx may use the following symbols file:

Binaries or shared libraries using only publicGlSymbol would
depend only on libgl1 (which may be provided by multiple
packages), but ones using implementationSpecificSymbol would get a
dependency on libgl1-mesa-glx (>= 6.5.2-7)

This field should normally not be necessary, since if the behavior of any
symbol has changed, the corresponding symbol minimal-version should
have been increased. But including it makes the symbols system
more robust by tightening the dependency in cases where the package using the
shared library specifically requires at least a particular version of the
shared library development package for some reason.

This is what dh_makeshlibs in the debhelper suite
does. If your package also has a udeb that provides a shared library,
dh_makeshlibs can automatically generate the udeb:
lines if you specify the name of the udeb with the --add-udeb
option.

Creating, modifying or removing a file in /usr/lib/mime/packages/
using maintainer scripts will not activate the trigger. In that case, it can
be done by calling dpkg-trigger --no-await /usr/lib/mime/packages
from the maintainer script after creating, modifying, or removing the file.

If you are using GCC, -fPIC produces code with relocatable
position independent code, which is required for most architectures to create a
shared library, with i386 and perhaps some others where non position
independent code is permitted in a shared library.

Position independent code may have a performance penalty, especially on
i386. However, in most cases the speed penalty must be measured
against the memory wasted on the few architectures where non position
independent code is even possible.

Some of the reasons why this might be required is if the library contains hand
crafted assembly code that is not relocatable, the speed penalty is excessive
for compute intensive libs, and similar reasons.

Some of the reasons for linking static libraries with the -fPIC
flag are if, for example, one needs a Perl API for a library that is under
rapid development, and has an unstable API, so shared libraries are pointless
at this phase of the library's development. In that case, since Perl needs a
library with relocatable code, it may make sense to create a static library
with relocatable code. Another reason cited is if you are distilling various
libraries into a common shared library, like mklibs does in the
Debian installer project.

These files store, among other things, all libraries on which that shared
library depends. Unfortunately, if the .la file is present and
contains that dependency information, using libtool when linking
against that library will cause the resulting program or library to be linked
against those dependencies as well, even if this is unnecessary. This can
create unneeded dependencies on shared library packages that would otherwise be
hidden behind the library ABI, and can make library transitions to new SONAMEs
unnecessarily complicated and difficult to manage.

This is necessary to allow top-level directories to be symlinks. If linking
/var/run to /run were done with the relative symbolic
link ../run, but /var were a symbolic link to
/srv/disk1, the symbolic link would point to /srv/run
rather than the intended target.

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

When a package is upgraded, and the owner or permissions of a file included in
the package has changed, dpkg arranges for the ownership and permissions to be
correctly set upon installation. However, this does not extend to directories;
the permissions and ownership of directories already on the system does not
change on install or upgrade of packages. This makes sense, since otherwise
common directories like /usr would always be in flux. To
correctly change permissions of a directory the package owns, explicit action
is required, usually in the postinst script. Care must be taken
to handle downgrades as well, in that case.

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

Internally, the package system normalizes the GNU triplets and the Debian
arches into Debian arch triplets (which are kind of inverted GNU triplets),
with the first component of the triplet representing the libc and ABI in use,
and then does matching against those triplets. However, such triplets are an
internal implementation detail that should not be used by packages directly.
The libc and ABI portion is handled internally by the package system based on
the os and cpu.

There are two traditional permission schemes for mail spools: mode 600 with all
mail delivery done by processes running as the destination user, or mode 660
and owned by group mail with mail delivery done by a process running as a
system user in group mail. Historically, Debian required mode 660 mail spools
to enable the latter model, but that model has become increasingly uncommon and
the principle of least privilege indicates that mail systems that use the first
model should use permissions of 600. If delivery to programs is permitted,
it's easier to keep the mail system secure if the delivery agent runs as the
destination user. Debian Policy therefore permits either scheme.

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 renderer, 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.

Note that this mechanism is not the same as using app-defaults; app-defaults
are tied to the client binary on the local file system, whereas X resources are
stored in the X server and affect all connecting clients.

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 file system. This support is
therefore deprecated and will cease to be present in the future.

Please note that this does not override the section on changelog files below,
so the file /usr/share/doc/package/changelog.Debian.gz
must refer to the changelog for the current version of package in
question. In practice, this means that the sources of the target and the
destination of the symlink must be the same (same source package and version).

In particular, /usr/share/common-licenses/Apache-2.0,
/usr/share/common-licenses/Artistic,
/usr/share/common-licenses/GPL-1,
/usr/share/common-licenses/GPL-2,
/usr/share/common-licenses/GPL-3,
/usr/share/common-licenses/LGPL-2,
/usr/share/common-licenses/LGPL-2.1,
/usr/share/common-licenses/LGPL-3,
/usr/share/common-licenses/GFDL-1.2, and
/usr/share/common-licenses/GFDL-1.3 respectively. The University
of California BSD license is also included in base-files as
/usr/share/common-licenses/BSD, but given the brevity of this
license, its specificity to code whose copyright is held by the Regents of the
University of California, and the frequency of minor wording changes, its text
should be included in the copyright file rather than referencing this file.