From 202206511b87e973c294babb58d1c27f79ef31a4 Mon Sep 17 00:00:00 2001 From: Manoj Srivastava Date: Thu, 16 Jun 2005 05:12:09 +0000 Subject: [PATCH] * Finished updates to chapter 7 Author: jdg Date: 2001/04/30 12:58:53 * Finished updates to chapter 7 * Scrapped chapter 8 (but preserved so that the rest of policy doesn't change its numbering) git-archimport-id: srivasta@debian.org--etch/debian-policy--devel--3.0--patch-106 --- policy.sgml | 315 +++++++++++++++++++++++++++------------------------- 1 file changed, 165 insertions(+), 150 deletions(-) diff --git a/policy.sgml b/policy.sgml index d59e64b..6808342 100644 --- a/policy.sgml +++ b/policy.sgml @@ -2240,17 +2240,8 @@

To be precise, the string should match the following - Perl regular expression (where $pound=#;): - -/closes:\s*(?:bug)?${pound}?\s?\d+(?:,\s*(?:bug)?\${pound}?\s?\d+)*/i - - -

We had to introduce the $pound variable in the - regexp above because otherwise the utilities - rendering the policy documents gor confused by a - backslashed "#" symbol. -

- + Perl regular expression: + /closes:\s*(?:bug)?\#?\s?\d+(?:,\s*(?:bug)?\#?\s?\d+)*/i Then all of the bug numbers listed will be closed by the archive maintenance script (katie), or in the case of an NMU, marked as fixed. @@ -3222,17 +3213,22 @@

- All but Pre-Depends and Conflicts - (discussed below) take effect only when a package - is to be configured. They do not prevent a package being on - the system in an unconfigured state while its dependencies - are unsatisfied, and it is possible to replace a package - whose dependencies are satisfied and which is properly - installed with a different version whose dependencies are - not and cannot be satisfied; when this is done the depending - package will be left unconfigured (since attempts to - configure it will give errors) and will not function - properly. + A Depends field takes effect only when a + package is to be configured. It does not prevent a package + being on the system in an unconfigured state while its + dependencies are unsatisfied, and it is possible to replace + a package whose dependencies are satisfied and which is + properly installed with a different version whose + dependencies are not and cannot be satisfied; when this is + done the depending package will be left unconfigured (since + attempts to configure it will give errors) and will not + function properly. If it is necessary, a + Pre-Depends field can be used, which has a partial + effect even when a package is being unpacked, as explained + in detail below. (The other three dependency fields, + Recommends, Suggests and + Enhances, are only used by the various front-ends + to dpkg such as dselect.)

@@ -3244,20 +3240,37 @@

- Thus Depends allows package maintainers to impose - an order in which packages should be configured. + The Depends field thus allows package maintainers + to impose an order in which packages should be configured. +

+ +

+ The meaning of the five dependency fields is as follows: Depends -

This declares an absolute dependency. +

+ This declares an absolute dependency. A package will + not be configured unless all of the packages listed in + its Depends field have been correctly + configured.

The Depends field should be used if the depended-on package is required for the depending package to provide a significant amount of - functionality.

+ functionality. +

+

+ The Depends field should also be used if the + postinst, prerm or + postrm scripts require the package to be + present in order to run. Note, however, that the + postrm cannot rely on any non-essential + packages to be present during the purge + phase. Recommends @@ -3302,35 +3315,43 @@ also forces dpkg to complete installation of the packages named before even starting the installation of the package which declares the - Pre-dependency. + pre-dependency, as follows:

- Pre-Depends should be used sparingly, - preferably only by packages whose premature upgrade or - installation would hamper the ability of the system to - continue with any upgrade that might be in progress. + When a package declaring a pre-dependency is about to + be unpacked the pre-dependency can be + satisfied if the depended-on package is either fully + configured, or even if the depended-on + package(s) are only unpacked or half-configured, + provided that they have been configured correctly at + some point in the past (and not removed or partially + removed since). In this case, both the + previously-configured and currently unpacked or + half-configured versions must satisfy any version + clause in the Pre-Depends field.

- When the package declaring it is being configured, a - Pre-Dependency will be considered satisfied - only if the depending package has been correctly - configured, just as if an ordinary Depends - had been used. + When the package declaring a pre-dependency is about + to be configured, the pre-dependency will be + treated as a normal Depends, that is, it will + be considered satisfied only if the depended-on + package has been correctly configured.

- However, when a package declaring a Pre-dependency is - being unpacked the predependency can be satisfied even - if the depended-on package(s) are only unpacked or - half-configured, provided that they have been - configured correctly at some point in the past (and - not removed or partially removed since). In this case - both the previously-configured and currently unpacked - or half-configured versions must satisfy any version - clause in the Pre-Depends field. + Pre-Depends should be used sparingly, + preferably only by packages whose premature upgrade or + installation would hamper the ability of the system to + continue with any upgrade that might be in progress.

+ +

+ Pre-Depends are also required if the + preinst script depends on the named + package. It is best to avoid this situation if + possible.

@@ -3348,30 +3369,30 @@

- Alternative binary packages - - Conflicts and Replaces - + Conflicting binary packages - + Conflicts

When one binary package declares a conflict with another - dpkg will refuse to allow them to be installed - on the system at the same time. + using a Conflicts field, dpkg will + refuse to allow them to be installed on the system at the + same time.

If one package is to be installed, the other must be removed first - if the package being installed is marked as - replacing () the one on the system, or - the one on the system is marked as deselected, or both + replacing (see ) the one on the system, + or the one on the system is marked as deselected, or both packages are marked Essential, then dpkg will automatically remove the package which is causing the conflict, otherwise it will halt the - installation of the new package with an error. This - mechanism specifically doesn't work when the installed - package is Essential, but the new package is not. + installation of the new package with an error. This + mechanism is specifically designed to produce an error when + the installed package is Essential, but the new + package is not.

-

A package will not cause a conflict merely because its configuration files are still installed; it must be at least @@ -3385,7 +3406,7 @@ prevent their installation, and allows a package to conflict with others providing a replacement for it. You use this feature when you want the package in question to be the only - package providing something. + package providing some feature.

@@ -3403,14 +3424,15 @@

As well as the names of actual (`concrete') packages, the package relationship fields Depends, + Recommends, Suggests, Enhances, + Pre-Depends, Conflicts, Build-Depends, Build-Depends-Indep, - Recommends, Suggests, Conflicts, - Build-Conflicts and Build-Conflicts-Indep may - mention virtual packages. + Build-Conflicts and Build-Conflicts-Indep + may mention `virtual packages'.

- A virtual package is one which appears in the + A virtual package is one which appears in the 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 @@ -3424,16 +3446,18 @@ packages which provide it. This is so that, for example, supposing we have - Package: vm - Depends: emacs + Package: foo + Depends: bar - and someone else releases an xemacs package they can say + and someone else releases an enhanced version of the + bar package (for example, a non-US variant), they + can say: - Package: xemacs - Provides: emacs - and all will work in the interim (until a purely - virtual package name is decided on and the emacs - and vm packages are changed to use it). + Package: bar-plus + Provides: bar + + and the bar-plus package will now also satisfy the + dependency for the foo package.

@@ -3458,87 +3482,101 @@

- If you want to specify which of a set of real packages should be the - default to satisfy a particular dependency on a virtual package, you - should list the real package as an alternative before the virtual. + If you want to specify which of a set of real packages + should be the default to satisfy a particular dependency on + a virtual package, you should list the real package as an + alternative before the virtual one.

- Replaces - overwriting - files and replacing packages - + Overwriting files and replacing + packages - Replaces

- The Replaces control file field has two purposes, - which come into play in different situations. + The Replaces control file field has two distinct + purposes, which come into play in different situations.

-

- Virtual packages () are not considered - when looking at a Replaces field - the packages - declared as being replaced must be mentioned by their real - names. -

- - Overwriting files in other packages - + Overwriting files in other packages

Firstly, as mentioned before, it is usually an error for a package to contain files which are on the system in - another package, though currently the - --force-overwrite flag is enabled by default, - downgrading the error to a warning, + another package.

- If the overwriting package declares that it replaces the - one containing the file being overwritten then - dpkg will proceed, and replace the file from - the old package with that from the new. The file will no - longer be listed as `owned' by the old package. + However, if the overwriting package declares that it + Replaces the one containing the file being + overwritten, then dpkg will replace the file + from the old package with that from the new. The file + will no longer be listed as `owned' by the old package.

If a package is completely replaced in this way, so that dpkg does not know of any files it still - contains, it is considered to have disappeared. It will + contains, it is considered to have `disappeared'. It will be marked as not wanted on the system (selected for - removal) and not installed. Any conffiles details noted - in the package will be ignored, as they will have been - taken over by the replacing package(s). The package's - postrm script will be run to allow the - package to do any final cleanup required. See . + removal) and not installed. Any conffiles + details noted for the package will be ignored, as they + will have been taken over by the overwriting package. The + package's postrm script will be run with a + special argument to allow the package to do any final + cleanup required. See .

- In the future dpkg will discard files which - would overwrite those from an already installed package - which declares that it replaces the package being - installed. This is so that you can install an older - version of a package without problems. + If an installed package, foo say, declares that + it replaces another, bar, and an attempt is made + to install bar, dpkg will discard + files in the bar package which would overwrite + those already present in foo. This is so that + you can install an older version of a package without + problems.

- This usage of Replaces only takes effect when - both packages are at least partially on the system at - once, so that it can only happen if they do not conflict - or if the conflict has been overridden.

+ For this usage of Replaces, virtual packages (see + ) are not considered when looking at a + Replaces field - the packages declared as being + replaced must be mentioned by their real names. +

+ +

+ Furthermore, this usage of Replaces only takes + effect when both packages are at least partially on the + system at once, so that it can only happen if they do not + conflict or if the conflict has been overridden. +

+ Replacing whole packages, forcing their - removal - + removal

Secondly, Replaces allows the packaging system to resolve which package should be removed when there is a conflict - see . This usage only takes effect when the two packages do conflict, - so that the two effects do not interfere with each other. + so that the two usages of this field do not interfere with + each other.

+ +

+ In this situation, the package declared as being replaced + can be a virtual package, so for example, all mail + transport agents (MTAs) would have the following fields in + their control files: + +Provides: mail-transport-agent +Conflicts: mail-transport-agent +Replaces: mail-transport-agent + + ensuring that only one MTA can be installed at any one + time. @@ -3549,21 +3587,22 @@

A source package may declare a dependency or a conflict on a - binary package. This is done with the control file fields - Build-Depends, Build-Depends-Indep, - Build-Conflicts, and - Build-Conflicts-Indep. Their semantics are that - the dependencies and conflicts they define must be satisfied - (as defined earlier for binary packages), when one of the - targets in debian/rules that the particular field - applies to is invoked. + binary package, indicating which packages are required to be + present on the system in order to build the binary packages + from the source package. This is done with the control file + fields Build-Depends, Build-Depends-Indep, + 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: Build-Depends, Build-Conflicts

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

@@ -3572,8 +3611,9 @@

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

@@ -3588,32 +3628,7 @@

- 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 - file, but you need them to be able to without losing their - changes, and a new package with a changed version of the file - 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 - versions of the package automatically. This will be - appropriate if the file is likely to need to be different on - each system. + This chapter has been superseded by .

-- 2.39.2