From d9a33058fc14d3ff659864b3f494b82f095aa894 Mon Sep 17 00:00:00 2001 From: Manoj Srivastava Date: Thu, 16 Jun 2005 05:26:40 +0000 Subject: [PATCH] * Improving 11.1 -- 11.6 Author: jdg Date: 2001/05/16 22:55:22 * Improving 11.1 -- 11.6 * Small improvements to upgrading-checklist git-archimport-id: srivasta@debian.org--etch/debian-policy--devel--3.0--patch-123 --- debian/changelog | 2 + policy.sgml | 480 ++++++++++++++++++++------------------- upgrading-checklist.html | 9 +- 3 files changed, 255 insertions(+), 236 deletions(-) diff --git a/debian/changelog b/debian/changelog index 2559145..c5d6e6a 100644 --- a/debian/changelog +++ b/debian/changelog @@ -14,6 +14,8 @@ debian-policy (3.5.4.1) unstable; urgency=low patches are incorporated upstream * Versioned Build-Depend on debiandoc-sgml for fixed Text.pm * Improved mkdir example in 10.1.2 closes: Bug#92744 + * Made the "where examples live" entry in the upgrading-checklist + clearer (add "for use by scripts") -- diff --git a/policy.sgml b/policy.sgml index e90c37c..8d0b210 100644 --- a/policy.sgml +++ b/policy.sgml @@ -579,7 +579,7 @@

Every package must be accompanied by a verbatim copy of its copyright and distribution license in the file - /usr/share/doc/<package>/copyright + /usr/share/doc/package/copyright (see for further details).

@@ -1027,7 +1027,7 @@

- + Maintainer scripts

@@ -1054,19 +1054,20 @@ belonging to another package without consulting the maintainer of that package first.

+

All packages which supply an instance of a common command name (or, in general, filename) should generally use update-alternatives, so that they may be installed together. If update-alternatives is not used, then each package must use - Conflicts to ensure that other packages are + Conflicts to ensure that other packages are de-installed. (In this case, it may be appropriate to specify a conflict against earlier versions of something that previously did not use update-alternatives; this is an exception to the usual rule that versioned conflicts should be - avoided). + avoided.)

@@ -1442,7 +1443,7 @@ Obsolete constructs and libraries

- The include file <varargs.h> is + The include file <varargs.h> is provided to support end-users compiling very old software; the library libtermcap is provided to support the execution of software which has been linked against it @@ -1451,7 +1452,7 @@

Debian packages should be patched to use - <stdarg.h> and ncurses + <stdarg.h> and ncurses instead.

@@ -1684,7 +1685,7 @@ Package: libc6

The version number format is: - &lsqbepoch:]upstream_version[-debian_revision] + [epoch:]upstream_version[-debian_revision]

@@ -2310,13 +2311,12 @@ Package: libc6 dpkg-genchanges and dpkg-source generate control files they perform variable substitutions on their output just before writing it. Variable - substitutions have the form - ${variable-name}. The optional file - debian/substvars contains variable substitutions to - be used; variables can also be set directly from - debian/rules using the -V option to the - source packaging commands, and certain predefined variables - are also available. + substitutions have the form ${variable}. + The optional file debian/substvars contains + variable substitutions to be used; variables can also be set + directly from debian/rules using the -V + option to the source packaging commands, and certain + predefined variables are also available.

@@ -4632,14 +4632,14 @@ test -f program-executed-later-in-script || exit 0 the burden on the system administrator, such configurable values should not be placed directly in the script. Instead, they should be placed in a file in - /etc/default, which typically will have the same + /etc/default, which typically will have thesame base name as the init.d script. This extra file should be sourced by the script when the script runs. It must contain only variable settings and comments in POSIX sh format. It should not be a conffile, but a configuration file maintained by - the package maintainer scripts. See for more details. + the package maintainer scripts. See + for more details.

@@ -5351,21 +5351,22 @@ exec /usr/lib/foo/foo "$@" Files - Binaries

Two different packages must not install programs with - different functionality but with the same filenames. (The + 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 must 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.

+ different implementations is handled via `alternatives' or + the `Conflicts' mechanism. See and + respectively.) If this case happens, + one of the programs must be renamed. The maintainers should + report this to the debian-devel mailing list and + try to find a consensus about which program will have to be + renamed. If a consensus cannot be reached, both + programs must be renamed. +

Generally the following compilation parameters should be used: @@ -5385,61 +5386,41 @@ install -s # (or use strip on the files in debian/tmp) package.

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

+ 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 the generation of 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 one to generate a package with debugging - information included. The following makefile snippet is only - an example of how one may test for either condition: + 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 the + generation of 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 one to generate a package + with debugging information included.

- 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: - - -

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

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

- - + The following makefile snippet is an example of how one may + test for either condition; you will probably have to massage + this example in order to make it work for your package. CFLAGS = -O2 -Wall INSTALL = install @@ -5455,11 +5436,6 @@ ifeq (,$(findstring nostrip,$(DEB_BUILD_OPTIONS))) INSTALL_PROGRAM += -s endif - - Please note that the above example is merely informative, - and is not a policy mandate. You may have to massage this - example in order to make it work for your package. -

@@ -5479,11 +5455,12 @@ endif Libraries

- All libraries must have a shared version in the lib - package and a static version in the lib-dev package. The - shared version must be compiled with -fPIC, and - the static version must not be. In other words, each - *.c file will need to be compiled twice.

+ All libraries must have a shared version in the + lib* package and a static version in the + lib*-dev package. The shared version must be + compiled with -fPIC, and the static version must + not be. In other words, each *.c file will need to + be compiled twice.

You must specify the gcc option -D_REENTRANT @@ -5494,14 +5471,24 @@ endif Note that all installed shared libraries should be stripped with -strip --strip-unneeded <your-lib> +strip --strip-unneeded your-lib (The option --strip-unneeded makes strip remove only the symbols which aren't needed for relocation processing.) Shared libraries can function perfectly well when stripped, since the symbols for dynamic linking are in a separate part of the ELF object - file.

+ file. + +

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

+ +

Note that under some circumstances it may be useful to @@ -5510,38 +5497,43 @@ strip --strip-unneeded <your-lib>

- An ever increasing number of packages are using libtool to - do their linking. The latest GNU libtools (>= 1.3a) can take - advantage of the metadata in the installed libtool archive - files (`*.la'). The main advantage of libtool's .la files is - that it allows libtool to store and subsequently access - metadata with respect to the libraries it builds. libtool - will search for those files, which contain a lot of useful - information about a library (e.g. dependency libraries for - static linking). Also, they're essential for - programs using libltdl. -

- -

- Certainly libtool is fully capable of linking against shared - libraries which don't have .la files, but being 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-1.4 (and to a - lesser extent libtool-1.3), the .la files will also store - information about inter-library dependencies which cannot - necessarily be derived after the .la file is deleted. + An ever increasing number of packages are using + libtool to do their linking. The latest GNU + libtools (>= 1.3a) can take advantage of the metadata in the + installed libtool archive files (*.la + files). The main advantage of libtool's + .la files is that it allows libtool to + store and subsequently access metadata with respect to the + libraries it builds. libtool will search for + those files, which contain a lot of useful information about + a library (such as library dependency information for static + linking). Also, they're essential for programs + using libltdl. + +

+ 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 will also store information about + inter-library dependencies which cannot necessarily be + derived after the .la file is deleted. +

+

- Packages that use libtool to create shared libraries should - include the .la files in the -dev - packages, with the exception that if the package relies on - libtool's libltdl library, in which case the .la - files must go in the run-time library package. This is a - good idea in general, and especially for static linking - issues. + Packages that use libtool to create shared + libraries should include the .la files in the + -dev package, unless the package relies on + libtool's libltdl library, in which case + the .la files must go in the run-time library + package.

@@ -5554,7 +5546,6 @@ strip --strip-unneeded <your-lib>

- Shared libraries @@ -5566,69 +5557,74 @@ strip --strip-unneeded <your-lib> For a straightforward library which has a development environment and a runtime kit including just shared libraries you need to create two packages: - librarynamesoname - (soname is the shared object name of the shared - library: 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; usually the - soname is the major number of the library) and - librarynamesoname-dev.

+ librarynamesoversion, where + soversion is the version number in the + soname of the shared library + +

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

+ + and librarynamesoversion-dev. +

If you prefer only to support one development version at a time you may name the development package - libraryname-dev; otherwise you may - wish to use dpkg's conflicts mechanism to - ensure that the user only installs one development version - at a time (after all, different development versions are - likely to have the same header files in them, causing a - filename clash if both are installed). Typically the - development version should also have an exact version - dependency on the runtime library, to make sure that - compilation and linking happens correctly.

+ libraryname-dev; otherwise you may need + to use dpkg's Conflicts mechanism (see ) to ensure that the user only installs one + development version at a time (as different development + versions are likely to have the same header files in them, + which would cause a filename clash if both were installed). + Typically the development version should also have an exact + version dependency on the runtime library, to make sure that + compilation and linking happens correctly. The + ${Source-Version} substitution variable can be + useful for this purpose. +

Packages which use the shared library should have a dependency on the name of the shared library package, - librarynamesoname. When - the soname changes you can have both versions - of the library installed while moving from the old library - to the new.

+ librarynamesoversion. When + the soname changes you can have both versions of the library + installed while migrating from the old library to the new. +

- If your package has some run-time support programs which - use the shared library you must not put them in - the shared library package. If you do that then you won't - be able to install several versions of the shared library - without getting filename clashes. Instead, either create - a third package for the runtime binaries (this package - might typically be named - libraryname-runtime; note the absence - of the soname in the package name) or if the - development package is small include them in there.

+ If your package has some run-time support programs which use + the shared library you must not put them in the shared + library package. If you do that then you won't be able to + install several versions of the shared library without + getting filename clashes. Instead, either create a third + package for the runtime binaries (this package might + typically be named libraryname-runtime; + note the absence of the soversion in the package + name), or if the development package is small you may + include them in there. +

If you have several shared libraries built from the same source tree you may lump them all together into a single - shared library package, provided that you change all their - sonames at once (so that you don't get filename + shared library package, provided that you change all of + their sonames at once (so that you don't get filename clashes if you try to install different versions of the - combined shared libraries package).

- -

- You should follow the directions in the Debian Packaging - Manual (or other documentation of the Debian - packaging tools) for putting the shared library in its - package, and you must include a shlibs control area - file with details of the dependencies for packages which use - the library.

+ combined shared libraries package). +

- Shared libraries should not be installed - executable, since ld.so does not require this - and trying to execute a shared library results in a core - dump.

 - + Shared libraries should not be installed executable, since + the dynamic linker does not require this and trying to + execute a shared library usually results in a core dump. +

+ Scripts @@ -5651,56 +5647,64 @@ strip --strip-unneeded <your-lib> command.

- The standard shell interpreter `/bin/sh' can be a + The standard shell interpreter /bin/sh can be a symbolic link to any POSIX compatible shell, if echo - -n does not generate a newline. + -n does not generate a newline.

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

- Thus, shell scripts - specifying `/bin/sh' as interpreter should only - use POSIX features. If a script requires non-POSIX - features from the shell interpreter, the appropriate shell - must be specified in the first line of the script (e.g., - `#!/bin/bash') and the package must depend on the - package providing the shell (unless the shell package is - marked `Essential', e.g., in the case of + Thus, shell scripts specifying /bin/sh as + interpreter should only use POSIX features. If a script + requires non-POSIX features from the shell interpreter, the + appropriate shell must be specified in the first line of the + script (e.g., #!/bin/bash) and the package must + depend on the package providing the shell (unless the shell + package is marked `Essential', as in the case of bash).

- You may wish to restrict your script to POSIX features when possible so - that it may use /bin/sh as its interpreter. If - your script works with ash, it's probably - POSIX compliant, but if you are in doubt, use - /bin/bash.

+ You may wish to restrict your script to POSIX features when + possible so that it may use /bin/sh as its + interpreter. If your script works with ash, + it's probably POSIX compliant, but if you are in doubt, use + /bin/bash. +

Perl scripts should check for errors when making any system calls, including open, print, - close, rename and system.

+ close, rename and system. +

- csh and tcsh should be avoided - as scripting languages. See Csh Programming - Considered Harmful, one of the comp.unix.* - FAQs. It can be found on - , or - - or even on ftp.cpan.org - /pub/perl/CPAN/doc/FMTEYEWTK/versus/csh.whynot. + csh and tcsh should be avoided as + scripting languages. See Csh Programming Considered + Harmful, one of the comp.unix.* FAQs, which + can be found at . + +

+ It can also be found on + + or on the ftp site ftp.cpan.org as + /pub/perl/CPAN/doc/FMTEYEWTK/versus/csh.whynot. +

+ If an upstream package comes with csh scripts then you must make sure that they start with #!/bin/csh and make your package depend on the - c-shell virtual package.

+ c-shell virtual package. +

Any scripts which create files in world-writeable @@ -5722,27 +5726,27 @@ strip --strip-unneeded <your-lib> should be relative, and symbolic links pointing from one top-level directory into another should be absolute. (A top-level directory is a sub-directory of the root - directory `/'.)

+ directory /.)

- In addition, symbolic links should be specified as short - as possible, i.e., link targets like `foo/../bar' are + In addition, symbolic links should be specified as short as + possible, i.e., link targets like foo/../bar are deprecated.

Note that when creating a relative link using ln it is not necessary for the target of the link to exist relative to the working directory you're - running ln from; nor is it necessary to - change directory to the directory where the link is to be - made. Simply include the string that should appear as the - target of the link (this will be a pathname relative to - the directory in which the link resides) as the first - argument to ln.

+ running ln from, nor is it necessary to change + directory to the directory where the link is to be made. + Simply include the string that should appear as the target + of the link (this will be a pathname relative to the + directory in which the link resides) as the first argument + to ln.

For example, in your Makefile or - debian/rules, do things like: + debian/rules, you can do things like: ln -fs gcc $(prefix)/bin/cc ln -fs gcc debian/tmp/usr/bin/cc @@ -5751,13 +5755,13 @@ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq

- A symbolic link pointing to a compressed file should - always have the same file extension as the referenced - file. (For example, if a file `foo.gz' is - referenced by a symbolic link, the filename of the link - has to end with `.gz' too, as in - `bar.gz.')

 - + A symbolic link pointing to a compressed file should always + have the same file extension as the referenced file. (For + example, if a file foo.gz is referenced by a + symbolic link, the filename of the link has to end with + `.gz' too, as in bar.gz.) +

+ Device files @@ -5916,9 +5920,9 @@ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq configuration file does not already exist. In certain cases it is useful for there to be an example or template file which the maintainer scripts use. Such files should - be in /usr/share/<package> or - /usr/lib/<package> with a symbolic link - from /usr/share/doc/<package>/examples + be in /usr/share/package or + /usr/lib/package with a symbolic link + from /usr/share/doc/package/examples if they are examples, and should be perfectly ordinary dpkg-handled files (not conffiles). @@ -6204,20 +6208,25 @@ endscript If a program needs to specify an architecture specification string in some place, the following format should be used: -<arch>-<os> +arch-os - where `<arch>' is one of the following: i386, alpha, arm, m68k, - powerpc, sparc and `<os>' is one of: linux, gnu. Use - of gnu in this string is reserved for the GNU/Hurd - operating system.

-

- Note, that we don't want to use `<arch>-debian-linux' - to apply to the rule `architecture-vendor-os' since this - would make our programs incompatible to other Linux - distributions. Also note, that we don't use - `<arch>-unknown-linux', since the `unknown' does not - look very good.

 + where arch is one of the following: + i386, alpha, arm, m68k, + powerpc, sparc and os + is one of: linux, gnu. Use of + gnu in this string is reserved for the GNU/Hurd + operating system. +

+

+ Note, that we don't want to use + arch-debian-linux to apply to the rule + `architecture-vendor-os' since this would make our programs + incompatible with other Linux distributions. Also note that + we don't use arch-unknown-linux, since + the unknown does not look very good. +

+ Daemons @@ -6343,11 +6352,11 @@ endscript

Cgi-bin executable files are installed in the directory -/usr/lib/cgi-bin/<cgi-bin-name> +/usr/lib/cgi-bin/cgi-bin-name and should be referred to as -http://localhost/cgi-bin/<cgi-bin-name> +http://localhost/cgi-bin/cgi-bin-name

@@ -6362,7 +6371,7 @@ http://localhost/cgi-bin/<cgi-bin-name> backward compatibility, see and can be referred to as -http://localhost/doc/<package>/<filename> +http://localhost/doc/package/filename

@@ -6372,9 +6381,10 @@ http://localhost/doc/<package>/<filename>

Web Applications should try to avoid storing files in the Web Document Root. Instead they should use the - /usr/share/doc/<package> directory for documents and - register the Web Application via the menu package. If - access to the web-root is unavoidable then use + /usr/share/doc/package directory for + documents and register the Web Application via the + menu package. If access to the web-root is unavoidable + then use /var/www @@ -7012,8 +7022,8 @@ install-info --quiet --remove /usr/share/info/foobar.info delete them without causing any programs to break. Any files that are referenced by programs but are also useful as standalone documentation should be installed under - /usr/share/<package>/ and symlinked in - /usr/share/doc/<package>/. + /usr/share/package/ and symlinked in + /usr/share/doc/package/.

@@ -7087,7 +7097,7 @@ fi

Every package must be accompanied by a verbatim copy of its copyright and distribution license in the file - /usr/share/doc/<package>/copyright. This file must + /usr/share/doc/package/copyright. This file must neither be compressed nor be a symbolic link.

@@ -7105,7 +7115,7 @@ fi

- /usr/share/doc/<package> may be a symbolic link to a + /usr/share/doc/package may be a symbolic link to a directory in /usr/share/doc only if two packages both come from the same source and the first package has a "Depends" relationship on the second. These rules are important diff --git a/upgrading-checklist.html b/upgrading-checklist.html index 7e27c66..8ea7413 100644 --- a/upgrading-checklist.html +++ b/upgrading-checklist.html @@ -53,6 +53,13 @@ picking your way through this list.

The checklist

+3.5.5.0                    May 01
+
+     - [Clarified note in 3.5.3.0 upgrading checklist regarding
+        examples and templates: this refers only to those examples used
+        by scripts; see section 11.7.3 for the whole story]
+
+
 3.5.4.0                    Apr 01
 
      - The system-wide mail directory is now /var/mail, no longer
@@ -96,7 +103,7 @@ picking your way through this list.
 
      - Daemon startup scripts in /etc/init.d/ should not contain
        modifiable parameters; these should be moved to a file in
-      /etc/default/; see [10.3.2] for details
+       /etc/default/; see [10.3.2] for details
      - Files in /usr/share/doc must not be referenced by any
        program.  If such files are needed, they must be placed in
        /usr/share/<package>/, and symbolic links created as required
-- 
2.39.2