[ Abstract ] [ Copyright Notice ] [ Contents ]

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 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 and changelog file formats are one example)

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

Also see RFC 2119.

3

2.5% of Debian packages [http://kitenet.net/programs/debconf/stats/] use debconf to prompt the user at install time, and this number is growing daily. The benefits of using debconf are briefly explained at http://kitenet.net/doc/debconf-doc/introduction.html; 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.

4

Debconf or another tool that implements the Debian Configuration management specification will also be installed, and any versioned dependancies on it will be satisfied before preconfiguration begins.

5

In the past, people specified 4 digits in the Standards-Version field, like `2.3.0.0'. Since any `patch-level changes' don't introduce new policy, it was thought it would be better to relax policy and only require that the first 3 digits are specified. (4 digits may still be used if someone wants to do so.)

6

Rationale:

7

Current distribution values are:

stable
This is the current `released' version of Debian GNU/Linux. Once the distribution is stable only major bug fixes are allowed. When changes are made to this distribution, the release number is increased (for example: 1.2r1 becomes 1.2r2 then 1.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.

frozen
From time to time, the unstable 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.

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.

There are several sections in each distribution. Currently, these sections are:

contrib
The packages in this section do not meet the criteria for inclusion in the main Debian distribution as defined by the Policy Manual, but are otherwise free, as defined by the Debian free software guidelines.

non-free
Packages in non-free do not meet the criteria of free software, as defined by the Debian free software guidelines. Again, use your best judgment in downloading from this Distribution.

You should list all distributions that the package should be installed into. Except in unusual circumstances, installations to stable should also go into frozen (if it exists) and unstable. Likewise, installations into frozen should also go into unstable.

8

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.

9

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.

10

This is generated by the 822-date program.

11

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

12

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

13

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

14

Setgid directories are allowed.

15

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.

16

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.

17

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

18

Currently, it calls ldd, but in a forthcoming version it shall call objdump to to this. This however changes will need a couple of changes in the way that packages are build.

Suppose a binary foo directly use a library libbar if it is linked with that library. Other libraries that are needed by libbar are linked indirectly to foo, and the dynamic linker will load the automatically when it loads libbar. Using ldd lists all the libraries, used directly and indirectly; but objdump only lists the directly linked libraries. A package only needs to depend on the libraries it is directly linked to, since the dependencies for those libraries should automatically pull in the other libraries.

This change does mean a change in the way packages are build though: currently dpkg-shlibdeps is only run on binaries. But since we will now depend on the libraries to depend on the libraries they need the packages containing those libraries will need to run dpkg-shlibdeps on the libraries.

A good example where this would help us is the current mess with multiple version of the mesa library. With the ldd-based system every package that uses mesa need to add a dependency on svgalib|svgalib-dummy in order to handle the glide mesa variant. With an objdump-based system this isn't necessary anymore and would have saved everyone a lot of work.

Another example: we could update libimlib with a new version that supports a new graphics format called dgf. If we use 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 depend on libimlib itself having the dependency on libgdh and wouldn't need to be updated.

19

Rationale: Building by default with -g causes more wasted CPU cycles since the information is stripped away anyway. The package can by default build without -g if it also provides a mechanism to easily be rebuilt with debugging information. This can be done by providing a "build-debug" make target, or allowing the user to specify "DEB_BUILD_OPTIONS=debug" in the environment while compiling that package.

Now this has several added benefits:

20

Debian policy specifies POSIX behavior for /bin/sh, but echo -n has widespread use in the Linux community (including especially debian 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.

21

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 different. The second is that dpkg might break the hard link while upgrading conffiles.

22

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

23

for backward compatibility, see Accessing the documentation, Section 13.4

24

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.

25

liblockfile version >>1.01

26

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.

27

Note: This shall change very shortly.

28

Rationale: clarifies the language to properly address the package maintainer, not the system administrator, as to how to manage /etc/X11/Xresources.

29

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.

30

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

31

Why "licenses" and not "copyright"? Because /usr/doc/copyright used to contain all the copyright files, plus the four common licenses GPL, LGPL, Artistic and BSD. Now individual copyright files for packages are no longer in a common directory. Once /usr/doc/copyright is almost empty it makes sense to rename "copyright" to "licenses"

Why "common-licenses" and not "licenses"? Because if I put just "licenses" I'm sure I will receive a bug report saying "license foo is not included in the licenses directory. They are not all the licenses, just a few common ones. I could use /usr/share/doc/common-licenses but I think this is too long, and, after all, the GPL does not "document" anything, it is merely a license.

32

Rationale: People should not have to look into two places for upstream changelogs merely because they are in HTML format.


[ Abstract ] [ Copyright Notice ] [ Contents ]
Debian Policy Manual
version 3.5.0.0, 2001-01-28
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