From 8f1b68ff69b7d2978c6b50c10adb770548a3dcdb Mon Sep 17 00:00:00 2001 From: Russ Allbery Date: Wed, 16 Jun 2010 11:00:04 -0700 Subject: [PATCH] Significantly rework the discussion of Breaks and Conflicts Recommend Breaks over Conflicts for most purposes. List the places Breaks should be used and the places Conflicts should be used. Add Breaks to the example in Replaces, and add a footnote explaining why Breaks is normally required along with Replaces when files are moving between packages. Add additional discussion of conflicting with a virtual package. --- policy.sgml | 241 ++++++++++++++++++++++++++++++++++------------------ 1 file changed, 160 insertions(+), 81 deletions(-) diff --git a/policy.sgml b/policy.sgml index 8aa51e7..7cac854 100644 --- a/policy.sgml +++ b/policy.sgml @@ -2575,7 +2575,7 @@ Package: libc6 Standards-Version (recommended) Build-Depends et al Checksums-Sha1 - and Checksums-Sha256 (recommended) + and Checksums-Sha256 (recommended) Files (mandatory)

@@ -2621,7 +2621,7 @@ Package: libc6 Closes Changes (mandatory) Checksums-Sha1 - and Checksums-Sha256 (recommended) + and Checksums-Sha256 (recommended) Files (mandatory)

@@ -4641,17 +4641,29 @@ Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any]

Normally a Breaks entry will have an "earlier than" version clause; such a Breaks is introduced in the - version of an (implicit or explicit) dependency which - violates an assumption or reveals a bug in earlier versions - of the broken package. This use of Breaks will - inform higher-level package management tools that broken - package must be upgraded before the new one. + version of an (implicit or explicit) dependency which violates + an assumption or reveals a bug in earlier versions of the broken + package, or which takes over a file from earlier versions of the + broken package. This use of Breaks will inform + higher-level package management tools that broken package must + be upgraded before the new one.

If the breaking package also overwrites some files from the - older package, it should use Replaces (not - Conflicts) to ensure this goes smoothly. + older package, it should use Replaces to ensure this + goes smoothly. See for a full discussion + of taking over files from other packages, including how to + use Breaks in those cases. +

+ +

+ Many of the cases where Breaks should be used were + previously handled with Conflicts + because Breaks did not yet exist. + Many Conflicts fields should now be Breaks. + See for more information about the + differences.

@@ -4662,21 +4674,24 @@ Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any] When one binary package declares a conflict with another using a Conflicts field, dpkg will refuse to allow them to be installed on the system at the - same time. + same time. This is a stronger restriction than Breaks, + which just prevents both packages from being configured at the + same time. Conflicting packages cannot be unpacked 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 (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 is specifically designed to produce an error when - the installed package is Essential, but the new - package is not. + first. If the package being installed is marked as replacing + (see , but note that Breaks should + normally be used in this case) 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 is specifically designed to produce an + error when the installed package is Essential, but the + new package is not.

@@ -4696,12 +4711,49 @@ Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any]

- A Conflicts entry should almost never have an - "earlier than" version clause. This would prevent - dpkg from upgrading or installing the package - which declared such a conflict until the upgrade or removal - of the conflicted-with package had been completed. Instead, - Breaks may be used. + Normally, Breaks should be used instead + of Conflicts since Conflicts imposes a + stronger restriction on the ordering of package installation or + upgrade and can make it more difficult for the package manager + to find a correct solution to an upgrade or installation + problem. Breaks should be used + + when moving a file from one package to another (see + ), + when splitting a package (a special case of the previous + one), or + when the breaking package exposes a bug in or interacts + badly with particular versions of the broken + package. + + Conflicts should be used + + when two packages provide the same file and will + continue to do so (but be aware that this is often an error + that should be fixed rather than using Conflicts -- + see, for example, ), + in conjunction with Provides when only one + package providing a given virtual facility may be installed + at a time (see ), + in other cases where one must prevent simultaneous + installation of two packages for reasons that are ongoing + (not fixed in a later version of one of the packages) or + that must prevent both packages from being unpacked at the + same time, not just configured. + +

+ +

+ A Conflicts entry may have an "earlier than" version + clause if the reason for the conflict is corrected in a later + version of one of the packages. However, normally the presence + of an "earlier than" version clause is a sign + that Breaks should have been used instead. An "earlier + than" version clause in Conflicts + prevents dpkg from upgrading or installing the + package which declares such a conflict until the upgrade or + removal of the conflicted-with package has been completed, which + is a strong restriction.

@@ -4748,35 +4800,46 @@ Provides: bar

- If a relationship field has a version number attached - then only real packages will be considered to see whether - the relationship is satisfied (or the prohibition violated, - for a conflict or breakage) - it is assumed that a real - package which provides the virtual package is not of the - "right" version. So, a Provides field may not - contain version numbers, and the version number of the - concrete package which provides a particular virtual package - will not be looked at when considering a dependency on or - conflict with the virtual package name. + If a relationship field has a version number attached, only real + packages will be considered to see whether the relationship is + satisfied (or the prohibition violated, for a conflict or + breakage). In other words, if a version number is specified, + this is a request to ignore all Provides for that + package name and consider only real packages. The package + manager will assume that a package which package which provides + that virtual package is not of the "right" version. + A Provides field may not contain version numbers, and + the version number of the concrete package which provides a + particular virtual package will not be considered when + considering a dependency on or conflict with the virtual package + name. + It is possible that a future release of dpkg may + add the ability to specify a version number for each virtual + package it provides. This feature is not yet present, + however, and is expected to be used only infrequently. +

- It is likely that the ability will be added in a future - release of dpkg to specify a version number for - each virtual package it provides. This feature is not yet - present, however, and is expected to be used only - infrequently. + To specify which of a set of real packages should be the default + to satisfy a particular dependency on a virtual package, list + the real package as an alternative before the virtual one.

- 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. + If the virtual package represents a facility that can only be + provided by one real package at a time, such as + the mail-transport-agent virtual package that + requires installation of a binary that would conflict with all + other providers of that virtual package (see + ), all packages providing that + virtual package should also declare a conflict with it + using Conflicts. This will ensure that at most one + provider of that virtual package is unpacked or installed at a + time.

- Overwriting files and replacing packages - Replaces @@ -4790,31 +4853,51 @@ Provides: bar 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. -

- -

- 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. + It is usually an error for a package to contain files which + are on the system in another 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 and will be taken over by the new package. + Normally, Breaks should be used in conjunction + with Replaces. + To see why Breaks is required in addition + to Provides, consider the + case of a file in the package foo being + taken over by the package foo-data. + Replaces will allow foo-data to + be installed and take over that file. However, + without Breaks, nothing + requires foo to be upgraded to a newer + version that knows it does not include that file and instead + depends on foo-data. Nothing would + prevent the new foo-data package from + being installed and then removed, removing the file that it + took over from foo. After that + operation, the package manager would think the system was in + a consistent state, but the foo package + would be missing one of its files. +

For example, if a package foo is split into foo and foo-data - starting at version 1.2-3, foo-data should - have the field + starting at version 1.2-3, foo-data would + have the fields Replaces: foo (<< 1.2-3) +Breaks: foo (<< 1.2-3) + + in its control file. The new version of the + package foo would normally have the field + +Depends: foo-data (>= 1.2-3) - in its control file. The package foo - doesn't need any special control fields in this example, - although would generally depend on or - recommend foo-data. + (or possibly Recommends or even Suggests if + the files moved into foo-data are not + required for normal operation).

@@ -4829,40 +4912,35 @@ Replaces: foo (<< 1.2-3) special argument to allow the package to do any final cleanup required. See . -

- Replaces is a one way relationship -- you have to - install the replacing package after the replaced - package. -

+ Replaces is a one way relationship. You have to install + the replacing package after the replaced package.

For this usage of Replaces, virtual packages (see ) are not considered when looking at a - Replaces field - the packages declared as being + 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. + This usage of Replaces only takes effect when both + packages are at least partially on the system at once. It is + not relevant if the packages conflict unless the conflict has + been overridden.

- Replacing whole packages, forcing their removal

- Secondly, Replaces allows the packaging system to + Second, 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 usages of this field do not interfere with - each other. + conflict (see ). This usage only takes + effect when the two packages do conflict, so that the + two usages of this field do not interfere with each other.

@@ -4876,7 +4954,8 @@ Conflicts: mail-transport-agent Replaces: mail-transport-agent ensuring that only one MTA can be installed at any one - time. + time. See for more information about this + example. @@ -7056,7 +7135,7 @@ exec /usr/lib/foo/foo "$@" Files - + Binaries

-- 2.39.5