From d38e4cccecb6ea6dcc00433882a1d5c4449aa999 Mon Sep 17 00:00:00 2001 From: Manoj Srivastava Date: Thu, 16 Jun 2005 05:33:38 +0000 Subject: [PATCH] * Fixed some broken hrefs in links Author: srivasta Date: 2002/08/31 07:20:11 * Fixed some broken hrefs in links * No longer use local debiandoc stuff (it's been fixed upstream) * Added table of contents (index.html) to policy-process.sgml, fixing the new error reported to bug #137521 closes: Bug#137521 * Fixed a couple of typos closes: Bug#139832 * Ran through the policy document looking for long instances of text in the tag, and changed it to where appropriate. This is since the tag can handle line breaking, but the flag does not. closes: Bug#139820 * Change the requirement to ask permission to make devices to merely requiring a notification. closes: Bug#106280 * Added a build dependson docbook utils. closes: Bug#154660 * Since this is being built with a newer version of debiandoc-sgml, this should display better with lynx. closes: Bug#153704 * Add in the crypto-in-main amendment. closes: Bug#81852, Bug#144411 * we no longer have task packages, instead, we define tasks using a special field in the control file (and these should be added only after discussion on the mailing lists) closes: Bug#97755 * Clarify wording in the section for packages providing fonts. closes: Bug#109672 * Fix the doc base file for policy process closes: Bug#137521, Bug#147554 closes: Bug#146756 * using set -e is not dubious advice. Rejecting this. closes: Bug#139969 * Make the directory one is building under ./debian/ be up to the maintainer, instead of mandating ./debian/tmp/ closes: Bug#144297 * Add a standards version closes: Bug#145067 * Added virtual package debconf-2.0 closes: Bug#151328 * Added The Window Manager Specification Project support to the default window manager selection mechanism closes: Bug#155680 * The confusion between /var/mail and /var/spool/mail seems to have been disambiguated. closes: Bug#114949 * Mention the new Build-Depend-Indep semantic and the new build-indep/build-arch rules in upgrading checklist closes: Bug#116134 * Made package naming rules in policy consistent. I did not eliminate the duplication, since I don't want to make major changes to the flow, since we are supposed to be re-writing policy anyway. closes: Bug#131441 * Clarified wording about cases where we may have concrete and virtual packages with the same name. closes: Bug#134977 * Fixed typo 'be be' closes: Bug#138681 * Fixed typo in appendix G -- example of diversion closes: Bug#140697 * fix typo shlib: -> shlibs: closes: Bug#141903 * Provide a link between two sections dealing with virtual packages. closes: Bug#143770 * Fixed xtifr's email address in the menu policy closes: Bug#152965 * Allow shared library names to be have a hyphen between library name and soversion if the library name ends in a number. closes: Bug#100472 * Permit some libraries to only install static libs. closes: Bug#100346 * Remove the debug option, add noopt closes: Bug#157131, Bug#113525 * provide dhcp-client virtual package. closes: Bug#154142 * We do not need bits in policy that ``should not be enforced''. closes: Bug#150456 * We are building this with the latest debianndoc-sgml. closes: Bug#146703 * Finish incorporating all of the accepted changes in Bug#72335, and this closes: Bug#141307, Bug#156546 * Added virtual package aspell-dictionary closes: Bug#139067 * Added virtual package radius-server closes: Bug#118608 * Clarifying manual pages is not a policy issue. closes: Bug#112828 * Corrected the ldconfig handling instructions. closes: Bug#111025 * Not a policy issue. closes: Bug#106826 * Removed the /usr/doc/ symlink clause. closes: Bug#47298, Bug#69311 git-archimport-id: srivasta@debian.org--etch/debian-policy--devel--3.0--patch-140 --- debian-policy-process.desc | 1 - debian/changelog | 59 +- debian/control | 2 +- menu-policy.sgml | 2 +- perl-policy.sgml | 7 +- policy.sgml | 1301 ++++++++++++++++++-------------- upgrading-checklist.html | 29 +- virtual-package-names-list.txt | 12 +- 8 files changed, 851 insertions(+), 562 deletions(-) diff --git a/debian-policy-process.desc b/debian-policy-process.desc index 205c4aa..d6dcb65 100644 --- a/debian-policy-process.desc +++ b/debian-policy-process.desc @@ -11,5 +11,4 @@ Format: text Files: /usr/share/doc/debian-policy/policy-process.txt.gz Format: HTML -Index: /usr/share/doc/debian-policy/policy-process.html/index.html Files: /usr/share/doc/debian-policy/policy-process.html/*.html diff --git a/debian/changelog b/debian/changelog index e7ccdf4..77506fa 100644 --- a/debian/changelog +++ b/debian/changelog @@ -1,16 +1,67 @@ -debian-policy (3.5.6.2) unstable; urgency=low +debian-policy (3.5.7.0) unstable; urgency=low * Fixed some broken hrefs in links * No longer use local debiandoc stuff (it's been fixed upstream) * Added table of contents (index.html) to policy-process.sgml, fixing the new error reported to bug #137521 closes: Bug#137521 * Fixed a couple of typos closes: Bug#139832 - * Ran through the policy docukent looking for long instances pf text in + * Ran through the policy document looking for long instances of text in the tag, and changed it to where appropriate. This is since the tag can handle line breaking, but the flag does not. closes: Bug#139820 - - -- + * Change the requirement to ask permission to make devices to merely + requiring a notification. closes: Bug#106280 + * Added a build dependson docbook utils. closes: Bug#154660 + * Since this is being built with a newer version of debiandoc-sgml, this + should display better with lynx. closes: Bug#153704 + * Add in the crypto-in-main amendment. closes: Bug#81852, Bug#144411 + * we no longer have task packages, instead, we define tasks using a + special field in the control file (and these should be added only + after discussion on the mailing lists) closes: Bug#97755 + * Clarify wording in the section for packages providing fonts. + closes: Bug#109672 + * Fix the doc base file for policy process closes: Bug#137521, Bug#147554 + closes: Bug#146756 + * using set -e is not dubious advice. Rejecting this. closes: Bug#139969 + * Make the directory one is building under ./debian/ be up to the + maintainer, instead of mandating ./debian/tmp/ closes: Bug#144297 + * Add a standards version closes: Bug#145067 + * Added virtual package debconf-2.0 closes: Bug#151328 + * Added The Window Manager Specification Project support to the default + window manager selection mechanism closes: Bug#155680 + * The confusion between /var/mail and /var/spool/mail seems to have been + disambiguated. closes: Bug#114949 + * Mention the new Build-Depend-Indep semantic and the new + build-indep/build-arch rules in upgrading checklist closes: Bug#116134 + * Made package naming rules in policy consistent. I did not eliminate + the duplication, since I don't want to make major changes to the flow, + since we are supposed to be re-writing policy anyway. closes: Bug#131441 + * Clarified wording about cases where we may have concrete and virtual + packages with the same name. closes: Bug#134977 + * Fixed typo 'be be' closes: Bug#138681 + * Fixed typo in appendix G -- example of diversion closes: Bug#140697 + * fix typo shlib: -> shlibs: closes: Bug#141903 + * Provide a link between two sections dealing with virtual packages. + closes: Bug#143770 + * Fixed xtifr's email address in the menu policy closes: Bug#152965 + * Allow shared library names to be have a hyphen between library name + and soversion if the library name ends in a number. closes: Bug#100472 + * Permit some libraries to only install static libs. closes: Bug#100346 + * Remove the debug option, add noopt closes: Bug#157131, Bug#113525 + * provide dhcp-client virtual package. closes: Bug#154142 + * We do not need bits in policy that ``should not be enforced''. + closes: Bug#150456 + * We are building this with the latest debianndoc-sgml. closes: Bug#146703 + * Finish incorporating all of the accepted changes in Bug#72335, and + this closes: Bug#141307, Bug#156546 + * Added virtual package aspell-dictionary closes: Bug#139067 + * Added virtual package radius-server closes: Bug#118608 + * Clarifying manual pages is not a policy issue. closes: Bug#112828 + * Corrected the ldconfig handling instructions. closes: Bug#111025 + * Not a policy issue. closes: Bug#106826 + * Removed the /usr/doc/ symlink clause. closes: Bug#47298, Bug#69311 + + -- Manoj Srivastava Sat, 31 Aug 2002 02:18:02 -0500 debian-policy (3.5.6.1) unstable; urgency=low diff --git a/debian/control b/debian/control index 49ac6e8..ef44414 100644 --- a/debian/control +++ b/debian/control @@ -4,7 +4,7 @@ Priority: optional Maintainer: Debian Policy List Uploaders: Julian Gilbey , Manoj Srivastava Standards-Version: ${debian-policy:Version} -Build-Depends-Indep: links, debiandoc-sgml (>= 1.1.47), sp, liburi-perl, libpaperg, tetex-bin, tetex-extra, latex2html, libi18n-langtags-perl, groff, bsdmainutils, pstoedit, tidy, jade, docbook-xml +Build-Depends-Indep: links, debiandoc-sgml (>= 1.1.47), sp, liburi-perl, libpaperg, tetex-bin, tetex-extra, latex2html, libi18n-langtags-perl, groff, bsdmainutils, pstoedit, tidy, jade, docbook-xml, docbook-utils Package: debian-policy Architecture: all diff --git a/menu-policy.sgml b/menu-policy.sgml index b288af0..d2096d6 100644 --- a/menu-policy.sgml +++ b/menu-policy.sgml @@ -22,7 +22,7 @@ The Debian Menu sub-policy Chris Waters - xtifr@dsp.net + xtifr@debian.org Joey Hess diff --git a/perl-policy.sgml b/perl-policy.sgml index 8edf3d7..d16f465 100644 --- a/perl-policy.sgml +++ b/perl-policy.sgml @@ -299,8 +299,11 @@ $(MAKE) OPTIMIZE="-O2 -g -Wall" and this one to install the results into the temporary tree: -$(MAKE) install PREFIX=$(CURDIR)/debian/tmp/usr - +$(MAKE) install PREFIX=$(CURDIR)/debian/<tmp>/usr + +

Replace <tmp> with the appropriate directory + (nominally just tmp)

+

A Build-Depends on perl (>= 5.6.0-16) is diff --git a/policy.sgml b/policy.sgml index c9828ac..8f6746c 100644 --- a/policy.sgml +++ b/policy.sgml @@ -555,21 +555,20 @@ The non-US sections

- Some programs with cryptographic program code need to be - stored on the non-US server because of United - States export restrictions. Such programs must be - distributed in the appropriate non-US section, - either non-US/main, non-US/contrib or - non-US/non-free. -

-

- This applies only to packages which contain cryptographic - code. A package containing a program with an interface to - a cryptographic program or a program that's dynamically - linked against a cryptographic library should not be - distributed via the non-US server if it is - capable of running without the cryptographic library or - program. + Non-free programs with cryptographic program code need to + be stored on the non-us server because of export + restrictions of the U.S. +

+

+ Programs which use patented algorithms that have a + restrictied license also need to be stored on "non-us", + since that is located in a country where it is not allowed + to patent algorithms. +

+

+ A package depends on another package which is distributed + via the non-us server has to be stored on the non-us + server as well.

@@ -820,8 +819,8 @@ Package names must consist of lower case letters (a-z), digits (0-9), plus (+) and minus (-) signs, and periods (.). - They must be at least two characters long and must contain - at least one letter. + They must be at least two characters long and must start + with an alphanumeric character.

@@ -926,7 +925,7 @@ doing that has been reached.

 - + Virtual packages

@@ -947,7 +946,7 @@ They should not use virtual package names (except privately, amongst a cooperating group of packages) unless they have been agreed upon and appear in the list of virtual package - names.

+ names. (See also )

The latest version of the authoritative list of virtual @@ -1019,9 +1018,42 @@ reached.

+ + Tasks + +

+ The Debian install process allows the user to choose from + a number of common tasks which a Debian system can be used to + perform. Selecting a task with tasksel causes + a set of packages that are useful in performing that task to be + installed. +

+ +

+ This set of packages is all available packages which have the + name of the selected task in the Task field of their + control file. The format of this field is a list of tasks, + separated by commas. +

+ +

+ You should not tag any packages as belonging to a task + before this has been discussed on the + debian-devel mailing list and a consensus about + doing that has been reached. +

+ +

+ For third parties (and historical reasons), tasksel also + supports constructing tasks based on task + packages. These are packages whose names begin with + task-. Task packages should not be included in the + Debian archive. +

+ - Maintainer scripts + Maintainer Scripts

The package installation scripts should avoid producing @@ -1276,10 +1308,9 @@

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

@@ -1525,16 +1556,17 @@ Package: libc6

The name of the binary package. Package names consist of - the alphanumerics and + - . - (plus, minus and full stop). + lower case letters (a-z), digits (0-9), + plus (+) and minus (-) signs, and + periods (.).

They must be at least two characters long and must start - with an alphanumeric character and not be all digits. The - use of lowercase package names is strongly recommended - unless the package you're building (or referring to, in - other fields) is already using uppercase.

+ with an alphanumeric character. The use of lowercase + package names is required unless the package you're + building (or referring to, in other fields) is already + using uppercase characters.

 Version @@ -2536,7 +2568,7 @@ Package: libc6 aborted half way through for some reason, the second call should merely do the things that were left undone the first time, if any, and exit with a success status if everything - is OK. + is OK.

This is so that if an error occurs, the user interrupts dpkg or some other unforeseen circumstance @@ -3433,15 +3465,17 @@ Build-Depends: kernel-headers-2.2.10 [!hurd-i386], Provides control file field of another package. The effect is as if the package(s) which provide a particular virtual package name had been listed by name - everywhere the virtual package name appears. + everywhere the virtual package name appears. (See also )

- If there are both a real and a virtual package of the same - name then the dependency may be satisfied (or the conflict - caused) by either the real package or any of the virtual - packages which provide it. This is so that, for example, - supposing we have + If there are both concrete and virtual packages of the same + name, then the dependency may be satisfied (or the conflict + caused) by either the concrete package with the name in + question or any other concrete package which provides the + virtual package with the name in question. This is so that, + for example, supposing we have Package: foo Depends: bar @@ -3591,7 +3625,31 @@ Replaces: mail-transport-agent Build-Conflicts and Build-Conflicts-Indep. The dependencies and conflicts they define must be satisfied (as defined earlier for binary packages) in order to invoke - the targets in debian/rules, as follows: + the targets in debian/rules, as follows: +

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

+ Build-Depends, Build-Conflicts @@ -3600,17 +3658,20 @@ Replaces: mail-transport-agent The Build-Depends and Build-Conflicts fields must be satisfied when any of the following targets is invoked: - build, binary, binary-arch + build, binary, binary-arch, + build-arch, build-indep and binary-indep.

- Build-Depends-Indep, Build-Conflicts-Indep + Build-Depends-Indep, + Build-Conflicts-Indep

The Build-Depends-Indep and Build-Conflicts-Indep fields must be satisfied when any of the following targets is - invoked: binary and binary-indep. + invoked: build, build-indep, + binary and binary-indep.

@@ -3710,21 +3771,45 @@ Replaces: mail-transport-agent

- must call ldconfig in its postinst - script if the first argument is configure and should - call it in the postrm script if the first - argument is remove. -

- -

- However, postrm and preinst scripts - must not call ldconfig in the case where - the package is being upgraded (see for - details), as ldconfig will see the temporary - names that dpkg uses for the files while it is - installing them and will make the shared library links point - to them, just before dpkg continues the - installation and renames the temporary files! + must use ldconfig to update the shared library + system. The package must call ldconfig in the + postinst script if the first argument is + configure; the postinst script may + optionally invoke ldconfig at other times. The + package should call ldconfig in the + postrm script if the first argument is + remove. The maintainer scripts must not invoke + ldconfig under any circumstances other than those + described in this paragraph. +

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. + 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. If An installed + shared lib has been removed from the system just before + "postrm remove" is run. This is the proper time to call + "ldconfig" to notify the system of that fact. 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. +

+

@@ -4141,7 +4226,7 @@ libbar 1 bar1 (>= 1.0-1) version 2.1, except where doing so would violate other terms of Debian Policy. The version of this document referred here can be found in the debian-policy - package or on + package or on alongside this manual. The latest version, which may be a more recent version, may @@ -4149,9 +4234,9 @@ libbar 1 bar1 (>= 1.0-1) . Specific questions about following the standard may be asked on the debian-devel mailing list, or - referred to the FHS mailing list (see the + referred to the FHS mailing list (see the for - more information). + more information).

@@ -4601,8 +4686,8 @@ test -f program-executed-later-in-script || exit 0 must contain only variable settings and comments in POSIX sh format. It may either be a conffile or a configuration file maintained by - the package maintainer scripts. See - for more details. + the package maintainer scripts. See + for more details.

@@ -4618,68 +4703,142 @@ test -f program-executed-later-in-script || exit 0 - Managing the links - -

- The program update-rc.d is provided for - package maintainers to arrange for the proper creation and - removal of /etc/rcn.d symbolic links, - or their functional equivalent if another method is being - used. This may be used by maintainers in their packages' - postinst and postrm scripts.

+ Interfacing with the initscript system

- You must not include any /etc/rcn.d - symbolic links in the actual archive or manually create or - remove the symbolic links in maintainer scripts; you must - use the update-rc.d program instead. (The - former will fail if an alternative method of maintaining - runlevel information is being used.) You must not include - the /etc/rcn.d directories themselves - in the archive either. (Only the sysvinit - package may do so.) + Maintainers should use the abstraction layer provided by + the update-rc.d and invoke-rc.d + programs to deal with initscripts in their packages' + scripts such as postinst, prerm + and postrm.

-

- By default update-rc.d will start services in - each of the multi-user state runlevels (2, 3, 4, and 5) - and stop them in the halt runlevel (0), the single-user - runlevel (1) and the reboot runlevel (6). The system - administrator will have the opportunity to customize - runlevels by simply adding, moving, or removing the - symbolic links in /etc/rcn.d if - symbolic links are being used, or by modifying - /etc/runlevel.conf if the file-rc method - is being used. + Directly managing the /etc/rc?.d links and directly + invoking the /etc/init.d/ initscripts should + be done only by packages providing the initscript + subsystem (such as sysvinit and + file-rc). +

-

- To get the default behavior for your package, put in your - postinst script - -update-rc.d package defaults >/dev/null - - and in your postrm - -if [ "$1" = purge ]; then - update-rc.d package remove >/dev/null -fi -

+ + Managing the links -

- This will use a default sequence number of 20. If it does - not matter when or in which order the init.d - script is run, use this default. If it does, then you - should talk to the maintainer of the sysvinit - package or post to debian-devel, and they will - help you choose a number. -

+

+ The program update-rc.d is provided for + package maintainers to arrange for the proper creation and + removal of /etc/rcn.d symbolic links, + or their functional equivalent if another method is being + used. This may be used by maintainers in their packages' + postinst and postrm scripts.

-

- For more information about using update-rc.d, - please consult its manpage . -

+

+ You must not include any /etc/rcn.d + symbolic links in the actual archive or manually create or + remove the symbolic links in maintainer scripts; you must + use the update-rc.d program instead. (The + former will fail if an alternative method of maintaining + runlevel information is being used.) You must not include + the /etc/rcn.d directories themselves + in the archive either. (Only the sysvinit + package may do so.) +

+ +

+ By default update-rc.d will start services in + each of the multi-user state runlevels (2, 3, 4, and 5) + and stop them in the halt runlevel (0), the single-user + runlevel (1) and the reboot runlevel (6). The system + administrator will have the opportunity to customize + runlevels by simply adding, moving, or removing the + symbolic links in /etc/rcn.d if + symbolic links are being used, or by modifying + /etc/runlevel.conf if the file-rc method + is being used. +

+ +

+ To get the default behavior for your package, put in your + postinst script + + update-rc.d package defaults >/dev/null + + and in your postrm + + if [ "$1" = purge ]; then + update-rc.d package remove >/dev/null + fi +

+ +

+ This will use a default sequence number of 20. If it does + not matter when or in which order the init.d + script is run, use this default. If it does, then you + should talk to the maintainer of the sysvinit + package or post to debian-devel, and they will + help you choose a number. +

+ +

+ For more information about using update-rc.d, + please consult its manpage . +

+ + + + Running initscripts +

+ The program invoke-rc.d is provided to make + it easier for package maintainers to properly invoke an + initscript, obeying runlevel and other locally-defined + constraints that might limit a package's right to start, + stop and otherwise manage services. This program may be + used by maintainers in their packages' scripts. +

+

+ The use of invoke-rc.d to invoke the + /etc/init.d/* initscripts is strongly + recommended +

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

+ , instead of calling them directly. +

+ +

+ By default, invoke-rc.d will pass any + action requests (start, stop, reload, restart...) to the + /etc/init.d script, filtering out requests + to start or restart a service out of its intended + runlevels. +

+

+ Most packages will simply need to change: + /etc/init.d/<package> + <action> in their postinst + and prerm scripts to: + + if [ -x /usr/sbin/invoke-rc.d ] ; then + invoke-rc.d package <action> + else + /etc/init.d/package <action> + fi +

+

+ A package should register its initscript services using + update-rc.d before it tries to invoke them + using invoke-rc.d. Invocation of + unregistered services may fail. +

+

+ For more information about using + invoke-rc.d, please consult its manpage + . +

+ @@ -5333,13 +5492,21 @@ exec /usr/lib/foo/foo "$@"

- Generally the following compilation parameters should be used: + By default, when a package is being built, any binaries + created should include debugging information, as well as + being compiled with optimization. You should also turn on + as many reasonable compilation warnings as possible; this + makes life easier for porters, who can then look at build + logs for possible problems. For the C programming language, + this means the following compilation parameters should be + used: CC = gcc -CFLAGS = -O2 -Wall # sane warning options vary between programs +CFLAGS = -O2 -g -Wall # sane warning options vary between programs LDFLAGS = # none install -s # (or use strip on the files in debian/tmp) -

+ +

Note that by default all installed binaries should be stripped, @@ -5350,50 +5517,56 @@ 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.

- -

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

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

- + Although binaries in the build tree should be compiled with + debugging information by default, it can often be difficult + to debug programs if they are also subjected to compiler + optimization. For this reason, it is recommended to support + the standardized environment + variable DEB_BUILD_OPTIONS. This variable can + contain several flags to change how a package is compiled + and built. +

+

+ + noopt + +

+ The presence of this string means that the package + should be complied with a minimum of optimization. + For C programs, it is best to add -O0 + to CFLAGS (although this is usually the + default). Some programs might fail to build or run at + this level of optimization; it may be necessary to + use -O1, for example. +

+ + nostrip + +

+ This string means that the debugging symbols should + not be stripped from the binary during installation, + so that debugging information may be included in the + package. +

+ + +

+

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 + implement the build options; you will probably have to + massage this example in order to make it work for your + package. + +CFLAGS = -Wall -g INSTALL = install INSTALL_FILE = $(INSTALL) -p -o root -g root -m 644 INSTALL_PROGRAM = $(INSTALL) -p -o root -g root -m 755 INSTALL_SCRIPT = $(INSTALL) -p -o root -g root -m 755 INSTALL_DIR = $(INSTALL) -p -d -o root -g root -m 755 -ifneq (,$(findstring debug,$(DEB_BUILD_OPTIONS))) -CFLAGS += -g +ifneq (,$(findstring noopt,$(DEB_BUILD_OPTIONS))) +CFLAGS += -O0 +else +CFLAGS += -O2 endif ifeq (,$(findstring nostrip,$(DEB_BUILD_OPTIONS))) INSTALL_PROGRAM += -s @@ -5411,12 +5584,47 @@ endif if there is good reason to do so. Feel free to override the upstream author's ideas about which compilation options are best: they are often inappropriate for our - environment.

+ environment. +

+ Libraries - +

+ In general, libraries must have a shared version in the + library package and a static version in the development + package. The shared version must be compiled with + -fPIC, and the static version must not be. In + other words, each source unit ( *.c, for example, + for C files) will need to be compiled twice. +

+

+ In some cases, it is acceptable for a library to be + available in static form only; these cases include: + + +

libraries for languages whose shared library support + is immature or unstable

+ + +

+ libraries whose interfaces are in flux or under + development (commonly the case when the library's + major version number is zero, or where the ABI breaks + across patchlevels) +

+ + +

+ libraries which are explicitly intended to be + available only in static form by their upstream + author(s)

+ + + If a library is available only in static form, then it must follow + the conventions for a development package. +

All libraries must have a shared version in the lib* package and a static version in the @@ -5474,7 +5682,7 @@ strip --strip-unneeded your-lib

- +

Packages containing shared libraries that may be linked to by other packages' binaries, but which for some @@ -5559,7 +5767,13 @@ strip --strip-unneeded your-lib

and librarynamesoversion-dev. -

+ Alternatively, if it would be confusing to directly append + soversion to libraryname (e.g. because + libraryname itself ends in a number), you may use + libraryname-soversion and + libraryname-soversion-dev + instead. +

If you prefer only to support one development version at a @@ -5760,7 +5974,13 @@ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq If a package needs any special device files that are not included in the base system, it must call MAKEDEV in the postinst script, - after asking the user for permission to do so.

+ after notifying the user +

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

+ + .

Packages must not remove any device files in the @@ -6790,6 +7010,15 @@ name [`syshostname']: points.

+ +

+ If the window manager complies with , + written by the , add 20 points. +

+

@@ -6828,7 +7057,7 @@ name [`syshostname']:

Fonts of any type supported by the X Window System - must be be in a separate binary package from any + must be in a separate binary package from any executables, libraries, or documentation (except that specific to the fonts shipped, such as their license information). If one or more of the fonts @@ -6903,7 +7132,7 @@ name [`syshostname']:

Font packages may, instead of placing files directly in the X font directories listed above, provide - symbolic links in the font directory which point to + symbolic links in that font directory pointing to the files' actual location in the filesystem. Such a location must comply with the FHS.

@@ -7159,12 +7388,12 @@ name [`syshostname']: Perl programs and modules

- Perl programs and modules should follow the current Perl - policy as defined in the file found on - ftp.debian.org in - /debian/doc/package-developer/perl-policy.txt.gz - or your local mirror. In addition, it is included in the - debian-policy package. + Perl programs and modules should follow the current Perl + policy as defined in the file found on + ftp.debian.org in + /debian/doc/package-developer/perl-policy.txt.gz + or your local mirror. In addition, it is included in the + debian-policy package.

@@ -7186,7 +7415,7 @@ name [`syshostname']: The permissions on /var/games are mode 755, owner root and group root.

- +

Each game decides on its own security policy.

@@ -7389,40 +7618,14 @@ install-info --quiet --remove /usr/share/info/foobar.info

Former Debian releases placed all additional documentation - in /usr/doc/package. To realize a - smooth migration to - /usr/share/doc/package, each package - must maintain a symlink /usr/doc/package - that points to the new location of its documentation in - /usr/share/doc/packageThese - 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.. - The symlink must be created when the package is installed; - it cannot be contained in the package itself due to problems - with dpkg. One reasonable way to accomplish - this is to put the following in the package's - postinst -

- The debhelper script - dh_installdocs does this automatically. -

- : - -if [ "$1" = "configure" ]; then - if [ -d /usr/doc -a ! -e /usr/doc/package \ - -a -d /usr/share/doc/package ]; then - ln -sf ../share/doc/package /usr/doc/package - fi -fi - - and the following in the package's prerm: - -if [ \( "$1" = "upgrade" -o "$1" = "remove" \) \ - -a -L /usr/doc/package ]; then - rm -f /usr/doc/package -fi - + in /usr/doc/package. This has now + changed to /usr/share/doc/package, + and packages must not put documentation in the directory + /usr/doc/package. +

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.

+

@@ -7592,7 +7795,7 @@ fi precedence. The remaining chapters of the old Packaging Manual have also not been read in detail to ensure that there are not parts which have been left out. Both of these will be - done in due course. + done in due course.

@@ -7625,13 +7828,13 @@ fi dselect's core and the access method scripts it uses to actually install the selected packages, and describes how to create a new access method.

- +

This manual does not go into detail about the options and usage of the package building and installation tools. It should therefore be read in conjuction with those programs' manpages. -

+

The utility programs which are provided with dpkg @@ -7640,7 +7843,7 @@ fi install-info, are not described in detail here - please see their manpages.

- +

It does not describe the policy requirements imposed on Debian packages, such as the permissions on files and @@ -7650,13 +7853,13 @@ fi helpful even if you don't plan to upload your package and make it available as part of the distribution.)

- +

It is assumed that the reader is reasonably familiar with the dpkg System Administrators' manual. Unfortunately this manual does not yet exist.

- +

The Debian version of the FSF's GNU hello program is provided as an example for people wishing to create Debian @@ -7670,31 +7873,31 @@ fi Binary packages (from old Packaging Manual) - +

The binary package has two main sections. The first part consists of various control information files and scripts used by dpkg when installing and removing. See .

- +

The second part is an archive containing the files and directories to be installed.

- +

In the future binary packages may also contain other components, such as checksums and digital signatures. The format for the archive is described in full in the deb(5) manpage.

- - + + Creating package files - dpkg-deb - +

All manipulation of binary package files is done by dpkg-deb; it's the only program that has @@ -7704,7 +7907,7 @@ fi dpkg-deb and invoke that instead with the same arguments.)

- +

In order to create a binary package you must make a directory tree which contains all the files and directories @@ -7713,21 +7916,21 @@ fi debian/tmp, relative to the top of the package's source tree.

- +

They should have the locations (relative to the root of the directory tree you're constructing) ownerships and permissions which you want them to have on the system when they are installed.

- +

With current versions of dpkg the uid/username and gid/groupname mappings for the users and groups being used should be the same on the system where the package is built and the one where it is installed.

- +

You need to add one special directory to the root of the miniature filesystem tree you're creating: @@ -7735,20 +7938,20 @@ fi information files, notably the binary package control file (see ).

- +

The DEBIAN directory will not appear in the filesystem archive of the package, and so won't be installed by dpkg when the package is installed.

- +

When you've prepared the package, you should invoke: dpkg --build directory

- +

This will build the package in directory.deb. (dpkg knows @@ -7756,7 +7959,7 @@ fi it invokes dpkg-deb with the same arguments to build the package.)

- +

See the manpage for details of how to examine the contents of this newly-created file. You may find the @@ -7777,7 +7980,7 @@ fi Package control information files - +

The control information portion of a binary package is a collection of files with names known to dpkg. @@ -7786,23 +7989,23 @@ fi installing or removing the package; others are scripts which the package maintainer wants dpkg to run.

- +

It is possible to put other files in the package control area, but this is not generally a good idea (though they will largely be ignored).

- +

Here is a brief list of the control info files supported by dpkg and a summary of what they're used for.

- +

control - +

This is the key description file used by dpkg. It specifies the package's name @@ -7810,7 +8013,7 @@ fi states its relationships with other packages, and so forth. See .

- +

It is usually generated automatically from information in the source package by the @@ -7818,12 +8021,12 @@ fi assistance from dpkg-shlibdeps. See .

- + postinst, preinst, postrm, prerm - +

These are exectuable files (usually scripts) which dpkg runs during installation, upgrade @@ -7834,7 +8037,7 @@ fi how they are called are in .

- +

It is very important to make these scripts idempotent. @@ -7850,7 +8053,7 @@ fi unforeseen circumstance happens you don't leave the user with a badly-broken package.

- +

The maintainer scripts are guaranteed to run with a controlling terminal and can interact with the user. @@ -7866,27 +8069,27 @@ fi output is printed immediately rather than being buffered.

- +

Each script should return a zero exit status for success, or a nonzero one for failure.

 - + conffiles - +

This file contains a list of configuration files which are to be handled automatically by dpkg (see ). Note that not necessarily every configuration file should be listed here.

 - + shlibs - +

This file contains a list of the shared libraries supplied by the package, with dependency details for @@ -7898,7 +8101,7 @@ fi

- + The main control information file: control @@ -7910,7 +8113,7 @@ fi statistics'.

-

+

The binary package control files of packages built from Debian sources are made by a special tool, dpkg-gencontrol, which reads @@ -7919,7 +8122,7 @@ fi more details.

-

+

The fields in binary package control files are: @@ -7963,9 +8166,9 @@ fi

Installed-Size

- + - +

A description of the syntax of control files and the purpose of these fields is available in . @@ -7977,7 +8180,7 @@ fi

Maintainers are encouraged to preserve the modification times of the upstream source files in a package, as far as - is reasonably possible. + is reasonably possible.

The rationale is that there is some information conveyed @@ -7995,60 +8198,60 @@ fi Source packages (from old Packaging Manual) -

+

The Debian binary packages in the distribution are generated from Debian sources, which are in a special format to assist the easy and automatic building of binaries.

-

+

There was a previous version of the Debian source format, which is now being phased out. Instructions for converting an old-style package are given in the Debian policy manual.

- + - Tools for processing source packages + Tools for processing source packages -

+

Various tools are provided for manipulating source packages; they pack and unpack sources and help build of binary packages and help manage the distribution of new versions.

-

+

They are introduced and typical uses described here; see for full documentation about their arguments and operation.

-

+

For examples of how to construct a Debian source package, and how to use those utilities that are used by Debian source packages, please see the hello example package.

- + dpkg-source - packs and unpacks Debian source packages -

+

This program is frequently used by hand, and is also called from package-independent automated building scripts such as dpkg-buildpackage.

-

+

To unpack a package it is typically invoked with dpkg-source -x .../path/to/filename.dsc - +

-

+

with the filename.tar.gz and filename.diff.gz (if applicable) in the same directory. It unpacks into @@ -8058,7 +8261,7 @@ fi the current directory.

-

+

To create a packed source archive it is typically invoked: dpkg-source -b package-version @@ -8073,18 +8276,18 @@ fi required.

-

+

See also .

 - - + + dpkg-buildpackage - overall package-building control script -

+

dpkg-buildpackage is a script which invokes dpkg-source, the debian/rules targets clean, build and @@ -8093,7 +8296,7 @@ fi package upload.

-

+

It is usually invoked by hand from the top level of the built or unbuilt source directory. It may be invoked with no arguments; useful arguments include: @@ -8136,20 +8339,20 @@ fi

- + dpkg-gencontrol - generates binary package control files -

+

This program is usually called from debian/rules (see ) in the top level of the source tree.

-

+

This is usually done just before the files and directories in the temporary directory tree where the package is being built have their permissions and ownerships set and the package is constructed using @@ -8162,14 +8365,14 @@ fi .

-

+

dpkg-gencontrol must be called after all the files which are to go into the package have been placed in the temporary build directory, so that its calculation of the installed size of a package is correct.

-

+

It is also necessary for dpkg-gencontrol to be run after dpkg-shlibdeps so that the variable substitutions created by @@ -8177,14 +8380,14 @@ fi are available.

-

+

For a package which generates only one binary package, and which builds it in debian/tmp relative to the top of the source package, it is usually sufficient to call dpkg-gencontrol.

-

+

Sources which build several binaries will typically need something like: @@ -8195,32 +8398,32 @@ fi tells it which package's control file should be generated.

-

+

dpkg-gencontrol also adds information to the list of files in debian/files, for the benefit of (for example) a future invocation of dpkg-genchanges.

 - + dpkg-shlibdeps - calculates shared library dependencies -

+

This program is usually called from debian/rules just before dpkg-gencontrol (see ), in the top level of the source tree.

-

+

Its arguments are executables.

In a forthcoming dpkg version, dpkg-shlibdeps would be required to be - called on shared libraries as well. + called on shared libraries as well.

They may be specified either in the locations in the @@ -8232,7 +8435,7 @@ fi be included in the binary package's control file.

-

+

If some of the found shared libraries should only warrant a Recommends or Suggests, or if some warrant a Pre-Depends, this can be achieved @@ -8241,7 +8444,7 @@ fi takes effect until the next -d.)

-

+

dpkg-shlibdeps does not directly cause the output control file to be modified. Instead by default it adds to the debian/substvars file variable @@ -8251,7 +8454,7 @@ fi control file.

-

+

For example, the procps package generates two kinds of binaries, simple C binaries like ps which require a predependency and full-screen ncurses @@ -8270,11 +8473,11 @@ fi

-

+

Sources which produce several binary packages with different shared library dependency requirements can use the -pvarnameprefix option to override - the default shlib: prefix (one invocation of + the default shlibs: prefix (one invocation of dpkg-shlibdeps per setting of this option). They can thus produce several sets of dependency variables, each of the form @@ -8283,27 +8486,27 @@ fi binary package control files.

- - + + dpkg-distaddfile - adds a file to debian/files -

+

Some packages' uploads need to include files other than the source and binary package files.

-

+

dpkg-distaddfile adds a file to the debian/files file so that it will be included in the .changes file when dpkg-genchanges is run.

-

+

It is usually invoked from the binary target of debian/rules: @@ -8317,26 +8520,26 @@ fi dpkg-distaddfile.

-

+

The section and priority are passed unchanged into the resulting .changes file. See .

- - + + dpkg-genchanges - generates a .changes upload control file -

+

This program is usually called by package-independent automatic building scripts such as dpkg-buildpackage, but it may also be called by hand.

-

+

It is usually called in the top level of a built source tree, and when invoked with no arguments will print out a straightforward .changes file based on the @@ -8345,13 +8548,13 @@ fi been built.

- - + + dpkg-parsechangelog - produces parsed representation of a changelog -

+

This program is used internally by dpkg-source et al. It may also occasionally be useful in debian/rules and elsewhere. It @@ -8360,11 +8563,11 @@ fi information in it to standard output.

- + dpkg-architecture - - information about the build and host system + information about the build and host system - +

This program can be used manually, but is also invoked by dpkg-buildpackage or debian/rules to set @@ -8373,11 +8576,11 @@ fi

- + The Debianised source tree -

+

The source archive scheme described later is intended to allow a Debianised source tree with some associated control information to be reproduced and transported easily. The @@ -8388,23 +8591,23 @@ fi scripts.

-

+

The extra files created for Debian are in the subdirectory debian of the top level of the Debianised source tree. They are described below.

- + debian/rules - the main building script -

+

This file is an executable makefile, and contains the package-specific recipies for compiling the package and building binary package(s) out of the source.

-

+

It must start with the line #!/usr/bin/make -f, so that it can be invoked by saying its name rather than invoking make explicitly. @@ -8422,8 +8625,8 @@ fi targets depend on must also be non-interactive.

-

- The targets which are required to be present are: +

+ The targets which are required to be present are: build @@ -8435,7 +8638,7 @@ fi built after this has taken place, so that it can be built without rerunning the configuration.

- +

A package may also provide both of the targets build-arch and build-indep. The @@ -8456,8 +8659,8 @@ fi build-indep that are provided in the rules file.

- -

+ +

If one or both of the targets build-arch and build-indep are not provided, then invoking debian/rules with one of the not-provided @@ -8465,7 +8668,7 @@ fi of 2. Usually this is provided automatically by make if the target is missing.

- +

For some packages, notably ones where the same source tree is compiled in different ways to produce @@ -8480,18 +8683,18 @@ fi binary package out of each.

-

+

The targets build, build-arch and build-indep target must not do anything that might require root privilege.

-

+

The build target may need to run clean first - see below.

-

+

When a package has a configuration routine that takes a long time, or when the makefiles are poorly designed, or when build needs to run @@ -8501,10 +8704,10 @@ fi again it will not rebuild the whole program.

- + binary, binary-arch, binary-indep - +

The binary target should be all that is @@ -8517,14 +8720,14 @@ fi those which are not.

-

+

binary should usually be a target with no commands which simply depends on binary-arch and binary-indep.

-

+

Both binary-* targets should depend on the build target, above, so that the package is built if it has not been already. It @@ -8535,7 +8738,7 @@ fi directory.

-

+

If one of the binary-* targets has nothing to do (this will be always be the case if the source generates only a single binary package, @@ -8544,20 +8747,20 @@ fi succeed.

-

+

describes how to construct binary packages.

-

+

The binary targets must be invoked as root.

- + clean - +

This should undo any effects that the build and binary targets @@ -8567,7 +8770,7 @@ fi to be non-interactive.

-

+

If a build file is touched at the end of the build target, as suggested above, it must be removed as the first thing that @@ -8577,7 +8780,7 @@ fi already done.

-

+

The clean target must be invoked as root if binary has been invoked since the last clean, or if @@ -8586,10 +8789,10 @@ fi example).

- + get-orig-source (optional) - +

This target fetches the most recent version of the original source package from a canonical archive @@ -8599,32 +8802,32 @@ fi in the current directory.

-

+

This target may be invoked in any directory, and should take care to clean up any temporary files it may have left.

-

+

This target is optional, but providing it if possible is a good idea.

- +

The build, binary and clean targets must be invoked with a current directory of the package's top-level directory.

- -

+ +

Additional targets may exist in debian/rules, either as published or undocumented interfaces or for the package's internal use.

- +

The architecture we build on and build for is determined by make variables via dpkg-architecture (see ). You can @@ -8637,7 +8840,7 @@ fi

DEB_*_GNU_TYPE (the GNU style architecture - specification string)

+ specification string)

DEB_*_GNU_CPU (the CPU part of DEB_*_GNU_TYPE)

@@ -8647,20 +8850,20 @@ fi DEB_*_GNU_TYPE)

- +

where * is either BUILD for specification of the build machine or HOST for specification of the machine we build for.

- +

Backward compatibility can be provided in the rules file by setting the needed variables to suitable default values, please refer to the documentation of dpkg-architecture for details.

- +

It is important to understand that the DEB_*_ARCH string does only determine which Debian architecture we @@ -8669,17 +8872,17 @@ fi used for that.

- - + + debian/control -

+

This file contains version-independent details about the source package and about the binary packages it creates.

-

+

It is a series of sets of control fields, each syntactically similar to a binary package control file. The sets are separated by one or more blank lines. The @@ -8688,12 +8891,12 @@ fi that the source tree builds.

-

+

The syntax and semantics of the fields are described below in .

-

+

The general (binary-package-independent) fields are: @@ -8705,7 +8908,7 @@ fi

Section and - Priority + Priority (classification, mandatory)

@@ -8719,10 +8922,10 @@ fi

Standards-Version

- + -

+

The per-binary-package fields are: @@ -8752,7 +8955,7 @@ fi -

+

These fields are used by dpkg-gencontrol to generate control files for binary packages (see below), by dpkg-genchanges to generate the @@ -8761,7 +8964,7 @@ fi source control file as part of a source archive.

-

+

The fields here may contain variable references - their values will be substituted by dpkg-gencontrol, dpkg-genchanges @@ -8772,20 +8975,20 @@ fi

User-defined fields -

+

Additional user-defined fields may be added to the source package control file. Such fields will be ignored, and not copied to (for example) binary or source package control files or upload control files.

-

+

If you wish to add additional unsupported fields to these output files you should use the mechanism described here.

-

+

Fields in the main source control information file with names starting X, followed by one or more of the letters BCS and a hyphen -, will @@ -8798,7 +9001,7 @@ fi (.changes) files.

-

+

For example, if the main source information control file contains the field @@ -8811,13 +9014,13 @@ fi

- + debian/changelog -

+

This file records the changes to the Debian-specific parts of the package @@ -8831,38 +9034,38 @@ fi .

-

+

It has a special format which allows the package building tools to discover which version of the package is being built and find out other release-specific information.

- That format is a series of entries like this: + That format is a series of entries like this: package (version) distribution(s); urgency=urgency * change details more change details * even more change details - + -- maintainer name and email address date

-

+

package and version are the source package name and version number. -

+

-

+

distribution(s) lists the distributions where this version should be installed when it is uploaded - it is copied to the Distribution field in the .changes file. See .

-

+

urgency is the value for the Urgency field in the .changes file for the upload. See . It is not possible to specify an @@ -8873,7 +9076,7 @@ fi urgency).

-

+

The change details may in fact be any series of lines starting with at least two spaces, but conventionally each change starts with an asterisk and a separating space and @@ -8882,7 +9085,7 @@ fi used here to separate groups of changes, if desired.

-

+

The maintainer name and email address should not necessarily be those of the usual package maintainer. They should be the details of the person doing @@ -8892,7 +9095,7 @@ fi installed.

-

+

The date should be in RFC822 format

@@ -8904,7 +9107,7 @@ fi optionally present as a comment.

-

+

The first `title' line with the package name should start at the left hand margin; the `trailer' line with the maintainer and date details should be preceded by exactly @@ -8912,24 +9115,24 @@ fi separated by exactly two spaces.

-

+

An Emacs mode for editing this format is available: it is called debian-changelog-mode. You can have this mode selected automatically when you edit a Debian changelog by adding a local variables clause to the end of the changelog.

- + Defining alternative changelog formats -

+

It is possible to use a different format to the standard one, by providing a parser for the format you wish to use.

-

+

In order to have dpkg-parsechangelog run your parser, you must include a line within the last 40 lines of your file matching the Perl regular expression: @@ -8942,7 +9145,7 @@ fi Changelog format names are non-empty strings of alphanumerics.

-

+

If such a line exists then dpkg-parsechangelog will look for the parser as /usr/lib/dpkg/parsechangelog/format-name @@ -8954,7 +9157,7 @@ fi the dpkg package.

-

+

The parser will be invoked with the changelog open on standard input at the start of the file. It should read the file (it may seek if it wishes) to determine the @@ -8970,7 +9173,7 @@ fi changelog.

-

+

The fields are: @@ -8983,7 +9186,7 @@ fi

Distribution (mandatory) -

+

Urgency (mandatory)

@@ -9005,7 +9208,7 @@ fi -

+

If several versions are being returned (due to the use of -v), the urgency value should be of the highest urgency code listed at the start of any of the @@ -9015,42 +9218,42 @@ fi date should always be from the most recent version.

-

+

For the format of the Changes field see .

-

+

If the changelog format which is being parsed always or almost always leaves a blank line between individual change notes these blank lines should be stripped out, so as to make the resulting output compact.

-

+

If the changelog format does not contain date or package name information this information should be omitted from the output. The parser should not attempt to synthesise it or find it from other sources.

-

+

If the changelog does not have the expected format the parser should exit with a nonzero exit status, rather than trying to muddle through and possibly generating incorrect output.

-

+

A changelog parser may not interact with the user at all.

 - + debian/substvars and variable substitutions -

+

When dpkg-gencontrol, dpkg-genchanges and dpkg-source generate control files they do variable substitutions on @@ -9064,7 +9267,7 @@ fi variables are available.

-

+

The is usually generated and modified dynamically by debian/rules targets; in this case it must be removed by the clean target. @@ -9075,18 +9278,18 @@ fi details about source variable substitutions, including the format of debian/substvars.

 - + debian/files -

+

This file is not a permanent part of the source tree; it is used while building packages to record which files are being generated. dpkg-genchanges uses it when it generates a .changes file.

-

+

It should not exist in a shipped source package, and so it (and any backup files or temporary files such as files.new @@ -9105,7 +9308,7 @@ fi start of the binary target.

-

+

dpkg-gencontrol adds an entry to this file for the .deb file that will be created by dpkg-deb from the control file that it @@ -9113,7 +9316,7 @@ fi with this file is to delete it in clean.

-

+

If a package upload includes files besides the source package and any binary packages whose control files were made with dpkg-gencontrol then they should be @@ -9121,11 +9324,11 @@ fi and dpkg-distaddfile should be called to add the file to the list in debian/files.

 - + debian/tmp -

+

This is the canonical temporary location for the construction of binary packages by the binary target. The directory tmp serves as the root of @@ -9136,34 +9339,34 @@ fi id="pkg-bincreating">.

-

+

If several binary packages are generated from the same source tree it is usual to use several debian/tmpsomething directories, for example tmp-a or tmp-doc.

-

+

Whatever tmp directories are created and used by binary must of course be removed by the clean target.

 - - + + Source packages as archives -

+

As it exists on the FTP site, a Debian source package consists of three related files. You must have the right versions of all three to be able to use them.

-

+

Debian source control file - .dsc - +

This file contains a series of fields, identified and separated just like the fields in the control file of @@ -9200,7 +9403,7 @@ fi -

+

The source package control file is generated by dpkg-source when it builds the source archive, from other files in the source package, @@ -9208,16 +9411,16 @@ fi the files and directories in the other parts of the source package, as described below.

- + Original source archive - package_upstream-version.orig.tar.gz - + - +

This is a compressed (with gzip -9) tar file containing the source code from @@ -9227,15 +9430,15 @@ fi and does not contain files anywhere other than in there or in its subdirectories.

 - + Debianisation diff - package_upstream_version-revision.diff.gz - + - +

This is a unified context diff (diff -u) giving the changes which are required to turn the @@ -9247,21 +9450,21 @@ fi or renamed.

-

+

All the directories in the diff must exist, except the debian subdirectory of the top of the source tree, which will be created by dpkg-source if necessary when unpacking.

-

+

The dpkg-source program will automatically make the debian/rules file executable (see below).

 - -

+ +

If there is no original source code - for example, if the package is specially prepared for Debian or the Debian maintainer is the same as the upstream maintainer - the @@ -9272,17 +9475,17 @@ fi package-version.

- + Unpacking a Debian source package without dpkg-source -

+

dpkg-source -x is the recommended way to unpack a Debian source package. However, if it is not available it is possible to unpack a Debian source archive as follows: - +

Untar the tarfile, which will create a .orig directory.

@@ -9302,18 +9505,18 @@ fi source code alongside the Debianised version.

- -

+ +

It is not possible to generate a valid Debian source archive without using dpkg-source. In particular, attempting to use diff directly to generate the .diff.gz file will not work.

- + Restrictions on objects in source packages -

+

The source package may not contain any hard links

@@ -9337,7 +9540,7 @@ fi

-

+

The source packaging tools manage the changes between the original and Debianised source using diff and patch. Turning the original source tree as @@ -9386,7 +9589,7 @@ fi

-

+

The debian directory and debian/rules are handled specially by dpkg-source - before applying the changes it will create the debian @@ -9401,7 +9604,7 @@ fi fields (from old Packaging Manual) -

+

Many of the tools in the dpkg suite manipulate data in a common format, known as control files. Binary and source packages have control data as do the .changes @@ -9409,18 +9612,18 @@ fi dpkg's internal databases are in a similar format.

- + Syntax of control files -

+

A file consists of one or more paragraphs of fields. The paragraphs are separated by blank lines. Some control files only allow one paragraph; others allow several, in which case each paragraph often refers to a different package.

-

+

Each paragraph is a series of fields and values; each field consists of a name, followed by a colon and the value. It ends at the end of the line. Horizontal whitespace (spaces @@ -9429,14 +9632,14 @@ fi colon.

-

+

Some fields' values may span several lines; in this case each continuation line must start with a space or tab. Any trailing spaces or tabs at the end of individual lines of a field value are ignored.

-

+

Except where otherwise stated only a single line of data is allowed and whitespace is not significant in a field body. Whitespace may never appear inside names (of packages, @@ -9445,18 +9648,18 @@ fi relationships.

-

+

Field names are not case-sensitive, but it is usual to capitalise the field names using mixed case as shown below.

-

+

Blank lines, or lines consisting only of spaces and tabs, are not allowed within field values or between fields - that would mean a new paragraph.

-

+

It is important to note that there are several fields which are optional as far as dpkg and the related tools are concerned, but which must appear in every Debian @@ -9465,14 +9668,14 @@ fi the Debian policy manual in conjuction with the details below and the list of fields for the particular file.

 - + List of fields - + Package -

+

The name of the binary package. Package names consist of the alphanumerics and + - . (plus, minus and full stop). @@ -9487,7 +9690,7 @@ fi

-

+

They must be at least two characters and must start with an alphanumeric. In current versions of dpkg they are sort of case-sensitive

This is a @@ -9495,37 +9698,37 @@ fi the package you're building (or referring to, in other fields) is already using uppercase.

 - + Version -

+

This lists the source or binary package's version number - see .

- + Architecture -

+

This is the architecture string; it is a single word for the Debian architecture.

-

+

dpkg will check the declared architecture of a binary package against its own compiled-in value before it installs it.

-

+

The special value all indicates that the package is architecture-independent.

-

+

In the main debian/control file in the source package, or in the source package control file .dsc, a list of architectures (separated by @@ -9540,7 +9743,7 @@ fi whatever the current build architecture is.

-

+

In a .changes file the Architecture field lists the architecture(s) of the package(s) currently being uploaded. This will be a list; if the @@ -9548,22 +9751,22 @@ fi entry source is also present.

-

+

See for information how to get the - architecture for the build process. + architecture for the build process.

- + Maintainer -

+

The package maintainer's name and email address. The name should come first, then the email address inside angle brackets <> (in RFC822 format).

-

+

If the maintainer's name contains a full stop then the whole field will not work directly as an email address due to a misfeature in the syntax specified in RFC822; a @@ -9573,34 +9776,34 @@ fi end, and bringing the email address forward).

-

+

In a .changes file or parsed changelog data this contains the name and email address of the person responsible for the particular version in question - this may not be the package's usual maintainer.

-

+

This field is usually optional in as far as the dpkg are concerned, but its absence when building packages usually generates a warning.

 - + Source -

+

This field identifies the source package name.

-

+

In a main source control information or a .changes or .dsc file or parsed changelog data this may contain only the name of the source package.

-

+

In the control file of a binary package (or in a Packages file) it may be followed by a version number in parentheses. @@ -9617,30 +9820,30 @@ fi name and version as the binary package.

- + Package interrelationship fields: Depends, Pre-Depends, Recommends Suggests, Conflicts, Provides, Replaces -

+

These fields describe the package's relationships with other packages. Their syntax and semantics are described in .

 - + Description -

+

In a binary package Packages file or main source control file this field contains a description of the binary package, in a special format. See for details.

-

+

In a .changes file it contains a summary of the descriptions for the packages being uploaded. The part of the field before the first newline is empty; thereafter @@ -9648,30 +9851,30 @@ fi description line from that binary package. Each line is indented by one space.

 - + Essential -

+

This is a boolean field which may occur only in the control file of a binary package (or in the Packages file) or in a per-package fields paragraph of a main source control data file.

-

+

If set to yes then dpkg and dselect will refuse to remove the package (though it can be upgraded and/or replaced). The other possible value is no, which is the same as not having the field at all.

 - + Section and Priority -

+

These two fields classify the package. The Priority represents how important that it is that the user have it installed; the Section @@ -9679,7 +9882,7 @@ fi been classified.

-

+

When they appear in the debian/control file these fields give values for the section and priority subfields of the Files field of the .changes file, @@ -9687,7 +9890,7 @@ fi binary packages.

-

+

The section and priority are represented, though not as separate fields, in the information for each file in the -Filefield of a @@ -9696,7 +9899,7 @@ fi a package in the FTP archive.

-

+

These fields are not used by by dpkg proper, but by dselect when it sorts packages and selects defaults. See the Debian policy manual for the @@ -9705,7 +9908,7 @@ fi archive for a list of currently in-use priorities.

-

+

These fields may appear in binary package control files, in which case they provide a default value in case the Packages files are missing the information. @@ -9718,15 +9921,15 @@ fi the -isp, -is or -ip options to achieve this effect.

 - + Binary -

+

This field is a list of binary packages.

-

+

When it appears in the .dsc file it is the list of binary packages which a source package can produce. It does not necessarily produce all of these binary packages @@ -9735,12 +9938,12 @@ fi which of the binary packages.

-

+

When it appears in a .changes file it lists the names of the binary packages actually being uploaded.

-

+

The syntax is a list of binary packages separated by commas. @@ -9750,26 +9953,26 @@ fi Currently the packages must be separated using only spaces in the .changes file.

 - + Installed-Size -

+

This field appears in the control files of binary packages, and in the Packages files. It gives the total amount of disk space required to install the named package.

-

+

The disk space is represented in kilobytes as a simple decimal number.

 - + Files -

+

This field contains a list of files with information about each one. The exact information and syntax varies with the context. In all cases the the part of the field @@ -9779,7 +9982,7 @@ fi sub-fields separated by spaces.

-

+

In the .dsc (Debian source control) file each line contains the MD5 checksum, size and filename of the tarfile and (if applicable) diff file which make up the @@ -9793,7 +9996,7 @@ fi in .

-

+

In the .changes file this contains one line per file being uploaded. Each line contains the MD5 checksum, size, section and priority and the filename. The section @@ -9805,7 +10008,7 @@ fi be installed properly.

-

+

The special value byhand for the section in a .changes file indicates that the file in question is not an ordinary package file and must by installed by @@ -9813,7 +10016,7 @@ fi byhand the priority should be -.

-

+

If a new Debian revision of a package is being shipped and no new original source archive is being distributed the .dsc must still contain the Files field @@ -9825,13 +10028,13 @@ fi source archive which was used to generate the .dsc file and diff which are being uploaded.

 - - + + Standards-Version -

+

The most recent version of the standards (the dpkg programmers' and policy manuals and associated texts) with which the package complies. This @@ -9840,17 +10043,17 @@ fi tell when a package needs attention.

-

+

Its format is the same as that of a version number except that no epoch or Debian revision is allowed - see .

 - - + + Distribution -

+

In a .changes file or parsed changelog output this contains the (space-separated) name(s) of the distribution(s) where this version of the package should @@ -9858,12 +10061,12 @@ fi for package names. (See ).

-

+

Current distribution values are: stable -

+

This is the current `released' version of Debian GNU/Linux. A new version is released approximately every 3 months after the development code has @@ -9874,7 +10077,7 @@ fi (for example: 1.2r1 becomes 1.2r2 then 1.2r3, etc).

- + unstable

@@ -9885,7 +10088,7 @@ fi tree. Download from this distribution at your own risk.

 - + contrib

@@ -9899,7 +10102,7 @@ fi distributions. Use your best judgement in downloading from this Distribution.

 - + non-free

@@ -9908,7 +10111,7 @@ fi criteria for inclusion in the main Debian distribution as defined by the Policy Manual. Again, use your best judgement in downloading from this Distribution.

- + experimental

@@ -9920,7 +10123,7 @@ fi of the Debian distribution tree. Download at your own risk.

 - + frozen

@@ -9939,11 +10142,11 @@ fi unstable. Likewise, installations into frozen should also go into unstable.

 - + Urgency -

+

This is a description of how important it is to upgrade to this version from previous ones. It consists of a single keyword usually taking one of the values LOW, @@ -9955,29 +10158,29 @@ fi

-

+

This field appears in the .changes file and in parsed changelogs; its value appears as the value of the urgency attribute in a dpkg-style changelog (see ).

-

+

Urgency keywords are not case-sensitive.

 - + Date -

+

In .changes files and parsed changelogs, this gives the date the package was built or last edited.

 - + Format -

+

This field occurs in .changes files, and specifies a format revision for the file. The format described here is version 1.5. The syntax of the @@ -9985,42 +10188,42 @@ fi number except that no epoch or Debian revision is allowed - see .

 - + Changes -

+

In a .changes file or parsed changelog this field contains the human-readable changes data, describing the differences between the last version and the current one.

-

+

There should be nothing in this field before the first newline; all the subsequent lines must be indented by at least one space; blank lines must be represented by a line consiting only of a space and a full stop.

-

+

Each version's change information should be preceded by a `title' line giving at least the version, distribution(s) and urgency, in a human-readable way.

-

+

If data from several versions is being returned the entry for the most recent version should be returned first, and entries should be separated by the representation of a blank line (the `title' line may also be followed by the representation of blank line).

 - + Filename and MSDOS-Filename -

+

These fields in Packages files give the filename(s) of (the parts of) a package in the distribution directories, relative to the root of the @@ -10028,11 +10231,11 @@ fi several parts the parts are all listed in order, separated by spaces.

 - + Size and MD5sum -

+

These fields in Packages files give the size (in bytes, expressed in decimal) and MD5 checksum of the file(s) which make(s) up a binary package in the @@ -10040,11 +10243,11 @@ fi the values for the parts are listed in order, separated by spaces.

 - + Status -

+

This field in dpkg's status file records whether the user wants a package installed, removed or left alone, whether it is broken (requiring @@ -10052,35 +10255,35 @@ fi system is. Each of these pieces of information is a single word.

 - + Config-Version -

+

If a package is not installed or not configured, this field in dpkg's status file records the last version of the package which was successfully configured.

 - + Conffiles -

+

This field in dpkg's status file contains information about the automatically-managed configuration files held by a package. This field should not appear anywhere in a package!

 - + Obsolete fields -

+

These are still recognised by dpkg but should not appear anywhere any more. - + Revision Package-Revision Package_Revision @@ -10090,11 +10293,11 @@ fi at one point in a separate control file field. This field went through several names.

- + Recommended

Old name for Recommends

 - + Optional

Old name for Suggests.

 @@ -10111,18 +10314,18 @@ fi (from old Packaging Manual) -

+

dpkg can do a certain amount of automatic handling of package configuration files.

-

+

Whether this mechanism is appropriate depends on a number of factors, but basically there are two approaches to any particular configuration file.

-

+

The easy method is to ship a best-effort configuration in the package, and use dpkg's conffile mechanism to handle updates. If the user is unlikely to want to edit the @@ -10131,7 +10334,7 @@ fi is only released infrequently, this is a good approach.

-

+

The hard method is to build the configuration file from scratch in the postinst script, and to take the responsibility for fixing any mistakes made in earlier @@ -10139,12 +10342,12 @@ fi appropriate if the file is likely to need to be different on each system.

- + Automatic handling of configuration files by dpkg -

+

A package may contain a control area file called conffiles. This file should be a list of filenames of configuration files needing automatic handling, separated @@ -10153,14 +10356,14 @@ fi package.

-

+

When a package is upgraded dpkg will process the configuration files during the configuration stage, shortly before it runs the package's postinst script,

-

+

For each file it checks to see whether the version of the file included in the package is the same as the one that was included in the last version of the package (the one that is @@ -10169,7 +10372,7 @@ fi version.

-

+

If neither the user nor the package maintainer has changed the file, it is left alone. If one or the other has changed their version, then the changed version is preferred - i.e., @@ -10182,20 +10385,20 @@ fi and must resolve the differences themselves.

-

+

The comparisons are done by calculating the MD5 message digests of the files, and storing the MD5 of the file as it was included in the most recent version of the package.

-

+

When a package is installed for the first time dpkg will install the file that comes with it, unless that would mean overwriting a file already on the filesystem.

-

+

However, note that dpkg will not replace a conffile that was removed by the user (or by a script). This is necessary because with some programs a @@ -10204,38 +10407,38 @@ fi kept that way if the user did it.

-

+

Note that a package should not modify a dpkg-handled conffile in its maintainer scripts. Doing this will lead to dpkg giving the user confusing and possibly dangerous options for conffile update when the package is upgraded.

 - + Fully-featured maintainer script configuration handling -

+

For files which contain site-specific information such as the hostname and networking details and so forth, it is better to create the file in the package's postinst script.

-

+

This will typically involve examining the state of the rest of the system to determine values and other information, and may involve prompting the user for some information which can't be obtained some other way.

-

+

When using this method there are a couple of important issues which should be considered:

-

+

If you discover a bug in the program which generates the configuration file, or if the format of the file changes from one version to the next, you will have to arrange for @@ -10248,7 +10451,7 @@ fi deal with them correctly.

-

+

If you do go down this route it's probably a good idea to make the program that generates the configuration file(s) a separate program in /usr/sbin, by convention called @@ -10262,20 +10465,20 @@ fi already exists, and require a --force flag to overwrite it.

 - + Alternative versions of an interface - update-alternatives (from old Packaging Manual) -

+

When several packages all provide different versions of the same program or file it is useful to have the system select a default, but to allow the system administrator to change it and have their decisions respected.

-

+

For example, there are several versions of the vi editor, and there is no reason to prevent all of them from being installed at once, each under their own name @@ -10284,65 +10487,65 @@ fi refer to something, at least by default.

-

+

If all the packages involved cooperate, this can be done with update-alternatives.

-

+

Each package provides its own version under its own name, and calls update-alternatives in its postinst to register its version (and again in its prerm to deregister it).

-

+

See the manpage for details.

-

+

If update-alternatives does not seem appropriate you may wish to consider using diversions instead.

 - + Diversions - overriding a package's version of a file (from old Packaging Manual) -

+

It is possible to have dpkg not overwrite a file when it reinstalls the package it belongs to, and to have it put the file from the package somewhere else instead.

-

+

This can be used locally to override a package's version of a file, or by one package to override another's version (or provide a wrapper for it).

-

+

Before deciding to use a diversion, read to see if you really want a diversion rather than several alternative versions of a program.

-

+

There is a diversion list, which is read by dpkg, and updated by a special program dpkg-divert. Please see for full details of its operation.

-

+

When a package wishes to divert a file from another, it should call dpkg-divert in its preinst to add the diversion and rename the existing file. For example, supposing that a smailwrapper package wishes to install a wrapper around /usr/sbin/smail: - if [ install = "$1" -o upgrade = "$1" ]; then + if [ install = "$1" ]; then dpkg-divert --package smailwrapper --add --rename \ --divert /usr/sbin/smail.real /usr/sbin/smail fi @@ -10354,7 +10557,7 @@ fi get installed as the true version.

-

+

The postrm has to do the reverse: if [ remove = "$1" ]; then @@ -10364,7 +10567,7 @@ fi

-

+

Do not attempt to divert a file which is vitally important for the system's operation - when using dpkg-divert there is a time, after it has been diverted but before diff --git a/upgrading-checklist.html b/upgrading-checklist.html index 187d657..2b57d33 100644 --- a/upgrading-checklist.html +++ b/upgrading-checklist.html @@ -7,9 +7,9 @@ Created On : Thu Oct 29 20:54:48 1998 Created On Node : tiamat.datasync.com Last Modified By : Manoj Srivastava - Last Modified On : Thu Mar 14 11:42:10 2002 + Last Modified On : Sat Aug 31 02:02:54 2002 Last Machine Used: glaurung.green-gryphon.com - Update Count : 20 + Update Count : 28 Status : Unknown, Use with caution! HISTORY : Description : @@ -53,6 +53,31 @@ picking your way through this list.

The checklist

+3.5.7.0                    Aug 02
+
+     - Packages no longer have to ask permission to call MAKEDEV in
+       postinst, merely notifying the user ought to be enough.
+     - cryptographic software may now be included in the main
+       archive. 
+     - task packages are now not permitted; tasks are now created by a
+       special Tasks: field in the control file.
+     - window managers that support netwm now can added 20 points when
+       they add themselves as an alternative for
+       /usr/bin/x-window-manager
+     - There are new rules for build-indep/build-arch targets and
+       there is a new Build-Depend-Indep semantic. These were actually
+       introduced in 3.5.6, but I forgot to mention them here.
+     - The default compilation options have now changed, one should
+       provide debugging symbols in all cases, and optionally step
+       back optimization to -O0, depending on the DEB_BUILD_OPTIONS
+       environment variable.
+     - Added mention of build-arch, build-indep, etc, in describing
+       the relationships with `Build-Depends', `Build-Conflicts',
+       `Build-Depends-Indep', and `Build-Conflicts-Indep'. May need to
+       review the new rules. 
+     - Changed rules on how, and when, to invoke ldconfig in maintiner
+       scripts. Long rationale.
+
 3.5.6.0                    Jul 01
 
      - Emacs and TeX are no longer mandated by policy to be priority
diff --git a/virtual-package-names-list.txt b/virtual-package-names-list.txt
index 2e8b5e6..5b7e6f5 100644
--- a/virtual-package-names-list.txt
+++ b/virtual-package-names-list.txt
@@ -63,6 +63,8 @@ others may do so as well.]
 awk                     Anything providing suitable /usr/bin/{awk,nawk} (*)
 c-compiler              Anything providing a C compiler
 c-shell                 Anything providing a suitable /bin/csh (*)
+debconf-2.0             Any package that provides the debconf protocol
+dhcp-client             Any package providing a DHCP client                 
 dotfile-module          Anything that provides a module for the
                         Dotfile Generator
 dict-client             Any package providing clients for the Dictionary Server
@@ -74,8 +76,8 @@ ftp-server              Any ftp server
 httpd                   Any HTTP server
 ident-server            Anything providing an identd daemon
 info-browser            Something that can browse GNU Info files
-ispell-dictionary       Anything providing a dictionary for the
-                        ispell system
+aspell-dictionary       Anything providing a dictionary for the aspell system
+ispell-dictionary       Anything providing a dictionary for the ispell system
 kernel-headers          Kernel header files (, )
 kernel-image            Kernel image (vmlinuz, System.map, modules)
 kernel-source           Kernel source code
@@ -89,6 +91,7 @@ pdf-preview             Any preprocessor that creates PDF output
 pdf-viewer              Anything that can display PDF files
 postscript-preview      Any preprocessor that creates Postscript output
 postscript-viewer       Anything that can display Postscript files
+radius-server           Any package that provides a RADIUS server for acct/auth
 rsh-client              Any package that provides an rsh client
 rsh-server              Any package that provides an rsh server
 system-log-daemon       A daemon that provides a logging facility for
@@ -215,3 +218,8 @@ Manoj Srivastava
 	      Added dict-client
 	      Added foomatic-data
 	      Added audio-mixer and x-audio-mixer
+Manoj Srivastava
+  30 Aug 2002 Added debconf-2.0
+              Added dhcp-client
+              Added aspell-dictionary
+              Added radius-server
\ No newline at end of file
-- 
2.39.2