Philip Hands
Julian Gilbey
Manoj Srivastava
This document assumes familiarity with these other two @@ -136,10 +141,10 @@
The current version of this document is always accessible from the
Debian FTP server
In addition, this manual is distributed via the Debian package @@ -587,8 +592,9 @@
Packages may not depend on packages with lower priority - values (excluding build-time dependencies). If this does - happen, one of the priority values will have to be adapted. + values (excluding build-time dependencies). In order to + ensure this, the priorities of one or more packages may have + to be adjusted.
@@ -706,7 +712,7 @@
Sometimes, there are several packages doing more-or-less
the same job. In this case, it's useful to define a
- virtual package who's name describes the function
+ virtual package whose name describes the function
the packages have. (The virtual packages just exist
logically, not physically--that's why they are called
virtual.) The packages with this particular
@@ -2065,53 +2071,109 @@
- It is not allowed that two packages install programs with
- different functionality but with the same filenames. (The
- case of two programs having the same functionality but
- different implementations is handled via `alternatives.')
- If this case happens, one of the programs has to be
- renamed. The maintainers should report this to the
- developers' mailing and try to find a consensus about
- which package will have to be renamed. If a consensus can
- not be reached, both programs must be
- renamed.
- Generally the following compilation parameters should be used:
-
- Note that all installed binaries should be stripped,
- either by using the -s flag to
-
- The -g flag is useful on compilation so that you
- have available a full set of debugging symbols in your
- built source tree, in case anyone should file a bug report
- involving (for example) a core dump.
- The -N flag should not be used. On a.out systems
- it may have been useful for some very small binaries, but
- for ELF it has no good effect.
+
+ It is not allowed that two packages install programs with
+ different functionality but with the same filenames. (The
+ case of two programs having the same functionality but
+ different implementations is handled via `alternatives.')
+ If this case happens, one of the programs has to be
+ renamed. The maintainers should report this to the
+ developers' mailing and try to find a consensus about
+ which package will have to be renamed. If a consensus can
+ not be reached, both programs must be
+ renamed.
+ Generally the following compilation parameters should be used:
+
+ Note that by default all installed binaries should be stripped,
+ either by using the -s flag to
+
+ The -N flag should not be used. On a.out systems
+ it may have been useful for some very small binaries, but
+ for ELF it has no good effect.
+ Debugging symbols are useful for error diagnosis, investigation
+ of core dumps (which may be submitted by users in bug reports),
+ or testing and developing the software. Therefore it is
+ recommended to support building the package with
+ debugging information through the following interface:
+ If the environment variable DEB_BUILD_OPTIONS
+ contains the string debug, compile the software with
+ debugging information (usually this involves adding the
+ -g flag to CFLAGS). This allows to generate
+ a build tree with debugging information. If the environment
+ variable DEB_BUILD_OPTIONS contains the
+ string nostrip, do not strip the files at installation
+ time. This allows to generate a package with debugging
+ information included. The following makefile snippet
+ is only an example how to test for either
+ condition:
+
+ 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 "BUILD_DEBUG=yes" in the environment while
+ compiling that package.
+ Now this has several added benefits:
+
+ It is actually easier to build debugging bins and
+ libraries this way (no more editing debian/rules
+ or similar) since it provides a documented way of
+ getting this type of build.
+ There will be much less wasted cpu time for the
+ autobuilders since not having debugging
+ information (and hence also not having to strip
+ it) will increase the speed of compiles. This
+ skips an entire pass of the compiler,
+
It is up to the package maintainer to decide what
compilation options are best for the package. Certain
binaries (such as computationally-intensive programs) may
@@ -2501,6 +2563,21 @@
maintainer scripts during installation (or at any other
time).
+ In order to ensure that local changes are preserved
+ correctly, no package may contain or make hard links to
+ conffiles.
+
+ 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
+
The other way to do it is to via the maintainer scripts.
In this case, the configuration file must not be listed as
@@ -2542,6 +2619,7 @@
not be mixed, for that way lies madness:
+
+
Note: With the release of the new X window System + version (4.X), there probably shall be a sweeping change + in the X Window System Policy in the future.
+Do not create two versions (one with X support and one without) of your package.
- Application defaults files have to be installed in
- the directory /usr/X11R6/lib/X11/app-defaults/.
- They are considered as part of the program code. Thus, they
- should not be modified and should not be tagged as
- conffiles nor otherwise treated as configuration
- files. If the local system administrator wants
- to customize X applications globally, a file with the same
- name as that of the package should be placed in the
- /etc/X11/Xresources/ directory instead.
+ Packages which provide an X server that, directly or
+ indirectly, communicates with real input and display hardware
+ should declare in their control data that they provide the
+ virtual package xserver.
+
+ Rationale: implement current practice, and provide 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.
+
+ Packages that provide a terminal emulator for the X + Window System which support a terminal type with a terminfo + description provided in the ncurses-base package + should declare in their control data that they provide the + virtual package x-terminal-emulator. They should + also register themselves as an alternative for + /usr/bin/x-terminal-emulator, with a priority of + 20. +
+ +
+ Packages that provide window managers should declare in
+ their control data that they provide the virtual package
+ x-window-manager. They should also register themselves as an
+ alternative for /usr/bin/x-window-manager, with a priority
+ calculated as follows:
+
+
+
+ Packages that provide fonts for the X Window System
+ must do a number of things to ensure that they are both
+ available without modification of the X or font server
+ configuration, and that they do not corrupt files used by
+ other font packages to register information about themselves.
+
+
+
+
+
+ Application defaults files must be installed in the + directory /usr/X11R6/lib/X11/app-defaults/. They should + not be registered as conffiles or otherwise treated as + configuration files. Customization of programs' X resources may + be supported with the provision of a file with the same name as + that of the package placed in the /etc/X11/Xresources/ + directory, which should be registered as a conffile. Important: packages that install files into the - /etc/X11/Xresources/ directory must - declare a conflict with xbase (<< - 3.3.2.3a-2); if this is not done it is possible for the - package to destroy a previously-existing - /etc/X11/Xresources file.
- -- No package should ever install files into the directories - /usr/bin/X11/, /usr/share/doc/X11/, - /usr/include/X11/, or /usr/lib/X11/; these - directories are actually symbolic links, which dpkg - does not follow when unpacking a package. Instead, use - /usr/X11R6/bin/, /usr/share/doc/package/ - (i.e., place files with the rest of your package's - documentation), /usr/X11R6/include/, and - /usr/X11R6/lib/. This restriction governs only the - paths used by the package as it is unpacked onto the system; - it is permissible, and even preferable, for files within a - package (shell scripts, for instance) to refer to the - /usr/{bin,include,lib}/X11/ directories rather than - their /usr/X11R6/ counterparts -- this way they do - not have to be modified in the event that the X Window - System packages install their files into a different - directory in the future.
+ /etc/X11/Xresources/ directory must declare a + conflict with xbase (<< 3.3.2.3a-2); if this is + not done it is possible for the installing package to destroy a + previously-existing /etc/X11/Xresources file + which had been customized by the system administrator. +Rationale: clarifies the language to properly + address the package maintainer, not the system + administrator, as to how to manage + /etc/X11/Xresources.
++ Packages using the X Window System should abide by the FHS + standard whenever possible; they should install binaries, + libraries, manual pages, and other files in FHS-mandated + locations wherever possible. This means that files should + not be installed into /usr/X11R6/bin/, + /usr/X11R6/lib/, or /usr/X11R6/man/ unless + this is necessary for the package to operate properly. + Configuration files for window managers and display managers + should be placed in a subdirectory of /etc/X11/ + corresponding to the package name due to these programs' + tight integration with the mechanisms of the X Window + System. Application-level programs should use the + /etc/ directory unless otherwise mandated by + policy. The installation of files into subdirectories of + /usr/X11R6/include/X11/ and + /usr/X11R6/lib/X11/ is permitted but discouraged; + package maintainers should determine if subdirectories of + /usr/lib/ and /usr/share/ can be used + instead (symlinks from the X11R6 directories to + FHS-compliant locations is encouraged if the program is not + easily configured to look elsewhere for its files). + Packages must not provide -- or install files into -- the + directories /usr/bin/X11/, + /usr/include/X11/, or /usr/lib/X11/. + Files within a package should, however, make reference to + these directories, rather than their X11R6-named + counterparts /usr/X11R6/bin/, + /usr/X11R6/include/X11/, and + /usr/X11R6/lib/X11/, if the resources being + referred to have not been moved to FHS-compliant locations. +
- If you package a program that requires the (non-free) - OSF/Motif library, you should try to determine whether the - programs works reasonably well with the free - re-implementation of Motif called LessTif. If so, build the - package using the LessTif libraries; it can then go into the - main section of the package repository and become an - official part of the Debian distribution.
- -- If however, the Motif-based program works insufficiently - well with LessTif, you should instead provide "-smotif" and "-dmotif" - versions (appending these identifiers to the name of the - package), which are statically and dynamically linked - against the Motif libraries, respectively. (All known - versions of OSF/Motif permit redistribution of - statically-linked binaries using the library, but check the - license on your copy of Motif to be sure.) This two-package - approach allows users without Motif to use the package, - whereas users with Motif installed can enjoy the advantages - of the dynamically-linked version (a considerable savings in - disk space usage, download time, etc.). Neither "-smotif" - nor "-dmotif" packages can go into the main section; if the - licensing on the package is compatible with the Debian Free - Software Guidelines, it may go into the contrib section; - otherwise it must go into the non-free section. - + Programs that require the non-DFSG-compliant OSF/Motif + library should be compiled against and tested with + LessTif (a free re-implementation of Motif) instead. If the + maintainer judges that the program or programs do not work + sufficiently well with LessTif to be distributed and + supported, but do so when compiled against Motif, then two + versions of the package should be created; one linked + statically against Motif and with -smotif appended + to the package name, and one linked dynamically against + Motif and with -dmotif appended to the package + name. Both Motif-linked versions are dependent upon + non-DFSG-compliant software and thus cannot be uploaded to + the main distribution; if the software is itself + DFSG-compliant it may be uploaded to the contrib + distribution. While known existing versions of OSF/Motif + permit unlimited redistribution of binaries linked against + the library (whether statically or dynamically), it is the + package maintainer's responsibility to determine whether + this is permitted by the license of the copy of OSF/Motif in + his or her possession.
@@ -3546,7 +3837,15 @@ changelog files do not already conform to this naming convention, then this may be achieved by either renaming the files or adding a symbolic link at the packaging developer's - discretion. + discretion. ++ Rationale: People should not have to look into two + places ofr upstream changelogs merely because they are + in HTML format. +
+Both should be installed compressed using gzip -9,