Debian Policy Manual
Footnotes

1

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 interfaces not changing, and the package management software authors need to ensure compatibility with these interface definitions. (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.

2

Compare RFC 2119. Note, however, that these words are used in a different way in this document.

3

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.

4

This is an important criterion because we are trying to produce, amongst other things, a free Unix.

5

The detailed procedure for doing this gracefully can be found in the Debian Developer's Reference, see Related documents, Section 1.4.

6

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.

7

From the Jargon file: by hand 2. By extension, writing code which does something in an explicit or low-level way for which a presupplied library (debconf, in this instance) routine ought to have been available.

8

The control.tar.gz inside the .deb. See deb(5).

9

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.

10

See the file upgrading-checklist for information about policy which has changed between different versions of this document.

11

Rationale:

12

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.

13

Mistakes in changelogs are usually best rectified by making a new changelog entry rather than "rewriting history" by editing old changelog entries.

14

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.

15

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

16

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.

17

This is generated by the 822-date program.

18

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 man page may be distributed under the GNU GPL, just as the rest of dpkg is.)

19

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.

20

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.

21

Setgid directories are allowed.

22

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.

23

The fakeroot package often allows one to build a package correctly even without being root.

24

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.

25


dpkg's internal databases are in a similar format.

26

The paragraphs are also sometimes referred to as stanzas.

27

It is customary to leave a space after the package name if a version number is specified.

28

This is the most often used setting, and is recommended for new packages that aren't Architecture: all.

29

This is a setting used for a minority of cases where the program is not portable. Generally, it should not be used for new packages.

30

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.

31

Alphanumerics are A-Za-z0-9 only.

32

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.

33

Current distribution names are:

stable
This is the current "released" version of Debian GNU/Linux. Once the distribution is stable only security fixes and other major bug fixes are allowed. When changes are made to this distribution, the release number is increased (for example: 2.2r1 becomes 2.2r2 then 2.2r3, etc).
unstable
This distribution value refers to the developmental part of the Debian distribution tree. New packages, new upstream versions of packages and bug fixes go into the unstable directory tree. Download from this distribution at your own risk.
testing
This distribution value refers to the testing part of the Debian distribution tree. It receives its packages from the unstable distribution after a short time lag to ensure that there are no major issues with the unstable packages. It is less prone to breakage than unstable, but still risky. It is not possible to upload packages directly to testing.
frozen
From time to time, the testing distribution enters a state of "code-freeze" in anticipation of release as a stable version. During this period of testing only fixes for existing or newly-discovered bugs will be allowed. The exact details of this stage are determined by the Release Manager.
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. Download at your own risk.

You should list all distributions that the package should be installed into.

More information is available in the Debian Developer's Reference, section "The Debian archive".

34

A space after each comma is conventional.

35

That is, the parts which are not the .dsc.

36

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.

37

Part of the problem is due to what is arguably a bug in dpkg.

38

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.

39

Replaces is a one way relationship -- you have to install the replacing package after the replaced package.

40

If you make "build-arch" or "binary-arch", you need Build-Depends. If you make "build-indep" or "binary-indep", you need Build-Depends and Build-Depends-Indep. If you make "build" or "binary", you need both.

There is no Build-Depends-Arch; the autobuilders will only need the Build-Depends if they know how to build only build-arch and binary-arch. Anyone building the build-indep/binary-indep targets is basically assumed to be building the whole package and so installs all build dependencies.

The purpose of the original split, I recall, 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.

41

Since it is common place to install several versions of a package that just provides shared libraries, it is a good idea that that the library package should not contain any extraneous non-versioned files, unless they happen to be in versioned directories.

42

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.

43

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.

44

These are currently

45

During install or upgrade, the preinst is called before the new files are installed, 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 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.

46

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.

47

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.

48

If you are using debhelper, the dh_shlibdeps program will do this work for you. It will also correctly handle multi-binary packages.

49

This can be determined using the command

     objdump -p /usr/lib/libz.so.1.1.3 | grep SONAME

50

This is what dh_makeshlibs in the debhelper suite does.

51

In the future, the use of invoke-rc.d to invoke initscripts shall be made mandatory. Maintainers are advised to switch to invoke-rc.d as soon as possible.

52

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.

53

A common example are the so-called "plug-ins", internal shared objects that are dynamically loaded by programs using dlopen(3).

54

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.

55

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.

56

This notification could be done via a (low-priority) debconf message, or an echo (printf) statement.

57

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.

58

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

59

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.

60

The following architectures and operating systems are currently recognized by dpkg-architecture. 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.

61

The Debian base system already provides an editor and a pager program.

62

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.

63

You will need to depend on liblockfile1 (>>1.01) to use these functions.

64

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.

65

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

66

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.

67

This is because the X server may retrieve fonts from the local file system or over the network from an X font server; the Debian package system is empowered to deal only with the local file system.

68

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.

69

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.

70

OSF/Motif and OpenMotif are collectively referred to as "Motif" in this policy document.

71

It is not very hard to write a man page. See the Man-Page-HOWTO, man(7), the examples created by debmake or dh_make, the helper programs help2man, or the directory /usr/share/doc/man-db/examples.

72

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.

73

The system administrator should be able to delete files in /usr/share/doc/ without causing any programs to break.

74

Please note that this does not override the section on changelog files below, so the file /usr/share/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).

75

At this phase of the transition, we no longer require a symbolic link in /usr/doc/. At a later point, policy shall change to make the symbolic links a bug.

76

The rationale: The important thing here is that HTML docs should be available in some package, not necessarily in the main binary package.

77

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.

78

dpkg is targeted primarily at Debian GNU/Linux, but may work on or be ported to other systems.

79

This is so that the control file which is produced has the right permissions

80

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.

81

At the time of writing, an example for this was the xmms package, with Depends used for the xmms executable, Recommends for the plug-ins and Suggests for even more optional features provided by unzip.

82

Support for Unicode, and specifically UTF-8, is steadily increasing among popular applications in Debian. For example, in unstable, GNOME 2 has excellent support (almost level 2) in almost all its applications; the big remaining one is gnome-terminal, of which one requires development versions in order to support UTF-8 (available in Debian experimental now if you want to play). I think that by the time Sarge is released, UTF-8 support will start to hit critical mass.

I think it is fairly obvious that we need to eventually transition to UTF-8 for our package infrastructure; it is really the only sane char-set in an international environment. Now, we can't switch to using UTF-8 for package control fields and the like until dpkg has better support, but one thing we can start doing today is requesting that Debian changelogs are UTF-8 encoded. At some point in time, we can start requiring them to do so.

Checking for non-UTF8 characters in a changelog is trivial. Dump the file through

     iconv -f utf-8 -t ucs-4

discard the output, and check the return value. If there are any characters in the stream which are invalid UTF-8 sequences, iconv will exit with an error code; and this will be the case for the vast majority of other character sets.

83

This is not currently detected when building source packages, but only when extracting them.

84

Hard links may be permitted at some point in the future, but would require a fair amount of work.

85

Setgid directories are allowed.

86

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.


Debian Policy Manual

version 3.6.2.1, 2005-07-21

The Debian Policy Mailing List